Skip to content

Commit 53215af

Browse files
javiereguiluzjaviereguiluz
committed
Reorganized some sections
1 parent 1f8acec commit 53215af

File tree

1 file changed

+147
-148
lines changed

1 file changed

+147
-148
lines changed

‎routing.rst

Lines changed: 147 additions & 148 deletions
Original file line numberDiff line numberDiff line change
@@ -199,138 +199,10 @@ Use the ``methods`` option to restrict the verbs each route should respond to:
199199
``_method`` with the method to use (e.g. ``<input type="hidden" name="_method" value="PUT" />``).
200200
If you use :doc:`Symfony forms </forms>` this is done automatically for you.
201201

202-
.. _i18n-routing:
203-
204-
Localized Routes (i18n)
205-
~~~~~~~~~~~~~~~~~~~~~~~
206-
207-
If your application is translated into multiple languages, each route can define
208-
a different URL per each :doc:`translation locale </translation/locale>`. This
209-
avoids the need for duplicating routes, which also reduces the potential bugs:
210-
211-
.. configuration-block::
212-
213-
.. code-block:: php-annotations
214-
215-
// src/Controller/CompanyController.php
216-
namespace App\Controller;
217-
218-
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
219-
use Symfony\Component\Routing\Annotation\Route;
220-
221-
class CompanyController extends AbstractController
222-
{
223-
/**
224-
* @Route({
225-
* "en": "/about-us",
226-
* "nl": "/over-ons"
227-
* }, name="about_us")
228-
*/
229-
public function about()
230-
{
231-
// ...
232-
}
233-
}
234-
235-
.. code-block:: yaml
236-
237-
# config/routes.yaml
238-
about_us:
239-
path:
240-
en: /about-us
241-
nl: /over-ons
242-
controller: App\Controller\CompanyController::about
243-
244-
.. code-block:: xml
245-
246-
<!-- config/routes.xml -->
247-
<?xml version="1.0" encoding="UTF-8" ?>
248-
<routes xmlns="http://symfony.com/schema/routing"
249-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
250-
xsi:schemaLocation="http://symfony.com/schema/routing
251-
https://symfony.com/schema/routing/routing-1.0.xsd">
252-
253-
<route id="about_us" controller="App\Controller\CompanyController::about">
254-
<path locale="en">/about-us</path>
255-
<path locale="nl">/over-ons</path>
256-
</route>
257-
</routes>
258-
259-
.. code-block:: php
260-
261-
// config/routes.php
262-
use App\Controller\CompanyController;
263-
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
264-
265-
return function (RoutingConfigurator $routes) {
266-
$routes->add('about_us', [
267-
'en' => '/about-us',
268-
'nl' => '/over-ons',
269-
])
270-
->controller([CompanyController::class, 'about'])
271-
;
272-
};
273-
274-
When a localized route is matched, Symfony uses the same locale automatically
275-
during the entire request.
276-
277-
.. tip::
278-
279-
When the application uses full "language + territory" locales (e.g. ``fr_FR``,
280-
``fr_BE``), if the URLs are the same in all related locales, routes can use
281-
only the language part (e.g. ``fr``) to avoid repeating the same URLs.
282-
283-
A common requirement for internationalized applications is to prefix all routes
284-
with a locale. This can be done by defining a different prefix for each locale
285-
(and setting an empty prefix for your default locale if you prefer it):
286-
287-
.. configuration-block::
288-
289-
.. code-block:: yaml
290-
291-
# config/routes/annotations.yaml
292-
controllers:
293-
resource: '../src/Controller/'
294-
type: annotation
295-
prefix:
296-
en: '' # don't prefix URLs for English, the default locale
297-
nl: '/nl'
298-
299-
.. code-block:: xml
300-
301-
<!-- config/routes/annotations.xml -->
302-
<?xml version="1.0" encoding="UTF-8" ?>
303-
<routes xmlns="http://symfony.com/schema/routing"
304-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
305-
xsi:schemaLocation="http://symfony.com/schema/routing
306-
https://symfony.com/schema/routing/routing-1.0.xsd">
307-
308-
<import resource="../src/Controller/" type="annotation">
309-
<!-- don't prefix URLs for English, the default locale -->
310-
<prefix locale="en"></prefix>
311-
<prefix locale="nl">/nl</prefix>
312-
</import>
313-
</routes>
314-
315-
.. code-block:: php
316-
317-
// config/routes/annotations.php
318-
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
319-
320-
return function (RoutingConfigurator $routes) {
321-
$routes->import('../src/Controller/', 'annotation')
322-
->prefix([
323-
// don't prefix URLs for English, the default locale
324-
'en' => '',
325-
'nl' => '/nl'
326-
])
327-
;
328-
};
329-
330202
.. _routing-route-groups:
331203

332-
Route Groups
333-
~~~~~~~~~~~~
204+
Route Groups and Prefixes
205+
~~~~~~~~~~~~~~~~~~~~~~~~~
334206

335207
It's common for a group of routes to share some options (e.g. all routes related
336208
to the blog start with ``/blog``) That's why Symfony includes a feature to share
@@ -446,7 +318,7 @@ defined in the class annotation.
446318
and you can even create your own route loader.
447319

448320
Debugging Routes
449-
----------------
321+
~~~~~~~~~~~~~~~~
450322

451323
As your application grows, you'll eventually have a *lot* of routes. Symfony
452324
includes some commands to help you debug routing issues. First, the ``debug:router``
@@ -1321,8 +1193,8 @@ A possible solution is to change the parameter requirements to be more permissiv
13211193
as the token and the format will be empty. This can be solved by replacing
13221194
the ``.+`` requirement by ``[^.]+`` to allow any character except dots.
13231195

1324-
Getting Route Information
1325-
-------------------------
1196+
Getting the Route Name and Parameters
1197+
-------------------------------------
13261198

13271199
The ``Request`` object created by Symfony stores all the route configuration
13281200
(such as the name and parameters) in the "request attributes". You can get this
@@ -1760,21 +1632,148 @@ these routes.
17601632
You can also set the ``host`` option when :ref:`importing routes <routing-route-groups>`
17611633
to make all of them require that host name.
17621634

1763-
Testing Sub-Domain Routing
1764-
~~~~~~~~~~~~~~~~~~~~~~~~~~
1765-
1766-
When using sub-domain routing, you must set the ``Host`` HTTP headers in
1767-
:doc:`functional tests </testing>` or routes won't match::
1768-
1769-
$crawler = $client->request(
1770-
'GET',
1771-
'/',
1772-
[],
1773-
[],
1774-
['HTTP_HOST' => 'm.example.com']
1775-
// or get the value from some container parameter:
1776-
// ['HTTP_HOST' => 'm.' . $client->getContainer()->getParameter('domain')]
1777-
);
1635+
.. note::
1636+
1637+
When using sub-domain routing, you must set the ``Host`` HTTP headers in
1638+
:doc:`functional tests </testing>` or routes won't match::
1639+
1640+
$crawler = $client->request(
1641+
'GET',
1642+
'/',
1643+
[],
1644+
[],
1645+
['HTTP_HOST' => 'm.example.com']
1646+
// or get the value from some container parameter:
1647+
// ['HTTP_HOST' => 'm.' . $client->getContainer()->getParameter('domain')]
1648+
);
1649+
1650+
.. _i18n-routing:
1651+
1652+
Localized Routes (i18n)
1653+
-----------------------
1654+
1655+
If your application is translated into multiple languages, each route can define
1656+
a different URL per each :doc:`translation locale </translation/locale>`. This
1657+
avoids the need for duplicating routes, which also reduces the potential bugs:
1658+
1659+
.. configuration-block::
1660+
1661+
.. code-block:: php-annotations
1662+
1663+
// src/Controller/CompanyController.php
1664+
namespace App\Controller;
1665+
1666+
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
1667+
use Symfony\Component\Routing\Annotation\Route;
1668+
1669+
class CompanyController extends AbstractController
1670+
{
1671+
/**
1672+
* @Route({
1673+
* "en": "/about-us",
1674+
* "nl": "/over-ons"
1675+
* }, name="about_us")
1676+
*/
1677+
public function about()
1678+
{
1679+
// ...
1680+
}
1681+
}
1682+
1683+
.. code-block:: yaml
1684+
1685+
# config/routes.yaml
1686+
about_us:
1687+
path:
1688+
en: /about-us
1689+
nl: /over-ons
1690+
controller: App\Controller\CompanyController::about
1691+
1692+
.. code-block:: xml
1693+
1694+
<!-- config/routes.xml -->
1695+
<?xml version="1.0" encoding="UTF-8" ?>
1696+
<routes xmlns="http://symfony.com/schema/routing"
1697+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
1698+
xsi:schemaLocation="http://symfony.com/schema/routing
1699+
https://symfony.com/schema/routing/routing-1.0.xsd">
1700+
1701+
<route id="about_us" controller="App\Controller\CompanyController::about">
1702+
<path locale="en">/about-us</path>
1703+
<path locale="nl">/over-ons</path>
1704+
</route>
1705+
</routes>
1706+
1707+
.. code-block:: php
1708+
1709+
// config/routes.php
1710+
use App\Controller\CompanyController;
1711+
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
1712+
1713+
return function (RoutingConfigurator $routes) {
1714+
$routes->add('about_us', [
1715+
'en' => '/about-us',
1716+
'nl' => '/over-ons',
1717+
])
1718+
->controller([CompanyController::class, 'about'])
1719+
;
1720+
};
1721+
1722+
When a localized route is matched, Symfony uses the same locale automatically
1723+
during the entire request.
1724+
1725+
.. tip::
1726+
1727+
When the application uses full "language + territory" locales (e.g. ``fr_FR``,
1728+
``fr_BE``), if the URLs are the same in all related locales, routes can use
1729+
only the language part (e.g. ``fr``) to avoid repeating the same URLs.
1730+
1731+
A common requirement for internationalized applications is to prefix all routes
1732+
with a locale. This can be done by defining a different prefix for each locale
1733+
(and setting an empty prefix for your default locale if you prefer it):
1734+
1735+
.. configuration-block::
1736+
1737+
.. code-block:: yaml
1738+
1739+
# config/routes/annotations.yaml
1740+
controllers:
1741+
resource: '../src/Controller/'
1742+
type: annotation
1743+
prefix:
1744+
en: '' # don't prefix URLs for English, the default locale
1745+
nl: '/nl'
1746+
1747+
.. code-block:: xml
1748+
1749+
<!-- config/routes/annotations.xml -->
1750+
<?xml version="1.0" encoding="UTF-8" ?>
1751+
<routes xmlns="http://symfony.com/schema/routing"
1752+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
1753+
xsi:schemaLocation="http://symfony.com/schema/routing
1754+
https://symfony.com/schema/routing/routing-1.0.xsd">
1755+
1756+
<import resource="../src/Controller/" type="annotation">
1757+
<!-- don't prefix URLs for English, the default locale -->
1758+
<prefix locale="en"></prefix>
1759+
<prefix locale="nl">/nl</prefix>
1760+
</import>
1761+
</routes>
1762+
1763+
.. code-block:: php
1764+
1765+
// config/routes/annotations.php
1766+
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
1767+
1768+
return function (RoutingConfigurator $routes) {
1769+
$routes->import('../src/Controller/', 'annotation')
1770+
->prefix([
1771+
// don't prefix URLs for English, the default locale
1772+
'en' => '',
1773+
'nl' => '/nl'
1774+
])
1775+
;
1776+
};
17781777
17791778
.. _routing-generating-urls:
17801779

0 commit comments

Comments
 (0)