Skip to content

Commit 2d878a0

Browse files
xabbuhxabbuh
committed
split the routing chapter
1 parent 4d3b468 commit 2d878a0

File tree

8 files changed

+870
-869
lines changed

8 files changed

+870
-869
lines changed

‎cookbook/map.rst.inc

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -160,6 +160,11 @@
160160
* :doc:`/cookbook/routing/redirect_trailing_slash`
161161
* :doc:`/cookbook/routing/extra_information`
162162
* :doc:`/cookbook/routing/routing_from_database`
163+
* :doc:`/cookbook/routing/optional_placeholders`
164+
* :doc:`/cookbook/routing/requirements`
165+
* :doc:`/cookbook/routing/conditions`
166+
* :doc:`/cookbook/routing/external_resources`
167+
* :doc:`/cookbook/routing/debug`
163168

164169
* :doc:`Security Authentication (Identifying/Logging in the User) </cookbook/security/index>`
165170

‎cookbook/routing/conditions.rst

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
.. index::
2+
:single: Routing; Conditions
3+
4+
How to Restrict Route Matching through Conditions
5+
=================================================
6+
7+
As you've seen, a route can be made to match only certain routing wildcards
8+
(via regular expressions), HTTP methods, or host names. But the routing system
9+
can be extended to have an almost infinite flexibility using ``conditions``:
10+
11+
.. configuration-block::
12+
13+
.. code-block:: yaml
14+
15+
contact:
16+
path: /contact
17+
defaults: { _controller: AcmeDemoBundle:Main:contact }
18+
condition: "context.getMethod() in ['GET', 'HEAD'] and request.headers.get('User-Agent') matches '/firefox/i'"
19+
20+
.. code-block:: xml
21+
22+
<?xml version="1.0" encoding="UTF-8" ?>
23+
<routes xmlns="http://symfony.com/schema/routing"
24+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
25+
xsi:schemaLocation="http://symfony.com/schema/routing
26+
http://symfony.com/schema/routing/routing-1.0.xsd">
27+
28+
<route id="contact" path="/contact">
29+
<default key="_controller">AcmeDemoBundle:Main:contact</default>
30+
<condition>context.getMethod() in ['GET', 'HEAD'] and request.headers.get('User-Agent') matches '/firefox/i'</condition>
31+
</route>
32+
</routes>
33+
34+
.. code-block:: php
35+
36+
use Symfony\Component\Routing\RouteCollection;
37+
use Symfony\Component\Routing\Route;
38+
39+
$collection = new RouteCollection();
40+
$collection->add('contact', new Route(
41+
'/contact', array(
42+
'_controller' => 'AcmeDemoBundle:Main:contact',
43+
),
44+
array(),
45+
array(),
46+
'',
47+
array(),
48+
array(),
49+
'context.getMethod() in ["GET", "HEAD"] and request.headers.get("User-Agent") matches "/firefox/i"'
50+
));
51+
52+
return $collection;
53+
54+
The ``condition`` is an expression, and you can learn more about its syntax
55+
here: :doc:`/components/expression_language/syntax`. With this, the route
56+
won't match unless the HTTP method is either GET or HEAD *and* if the ``User-Agent``
57+
header matches ``firefox``.
58+
59+
You can do any complex logic you need in the expression by leveraging two
60+
variables that are passed into the expression:
61+
62+
``context``
63+
An instance of :class:`Symfony\\Component\\Routing\\RequestContext`,
64+
which holds the most fundamental information about the route being matched.
65+
``request``
66+
The Symfony :class:`Symfony\\Component\\HttpFoundation\\Request` object
67+
(see :ref:`component-http-foundation-request`).
68+
69+
.. caution::
70+
71+
Conditions are *not* taken into account when generating a URL.
72+
73+
.. sidebar:: Expressions are Compiled to PHP
74+
75+
Behind the scenes, expressions are compiled down to raw PHP. Our example
76+
would generate the following PHP in the cache directory::
77+
78+
if (rtrim($pathinfo, '/contact') === '' && (
79+
in_array($context->getMethod(), array(0 => "GET", 1 => "HEAD"))
80+
&& preg_match("/firefox/i", $request->headers->get("User-Agent"))
81+
)) {
82+
// ...
83+
}
84+
85+
Because of this, using the ``condition`` key causes no extra overhead
86+
beyond the time it takes for the underlying PHP to execute.

‎cookbook/routing/debug.rst

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
.. index::
2+
single: Routing; Debugging
3+
4+
How to Visualize And Debug Routes
5+
=================================
6+
7+
While adding and customizing routes, it's helpful to be able to visualize
8+
and get detailed information about your routes. A great way to see every
9+
route in your application is via the ``debug:router`` console command. Execute
10+
the command by running the following from the root of your project.
11+
12+
.. code-block:: bash
13+
14+
$ php bin/console debug:router
15+
16+
This command will print a helpful list of *all* the configured routes in
17+
your application:
18+
19+
.. code-block:: text
20+
21+
homepage ANY /
22+
contact GET /contact
23+
contact_process POST /contact
24+
article_show ANY /articles/{_locale}/{year}/{title}.{_format}
25+
blog ANY /blog/{page}
26+
blog_show ANY /blog/{slug}
27+
28+
You can also get very specific information on a single route by including
29+
the route name after the command:
30+
31+
.. code-block:: bash
32+
33+
$ php bin/console debug:router article_show
34+
35+
Likewise, if you want to test whether a URL matches a given route, you can
36+
use the ``router:match`` console command:
37+
38+
.. code-block:: bash
39+
40+
$ php bin/console router:match /blog/my-latest-post
41+
42+
This command will print which route the URL matches.
43+
44+
.. code-block:: text
45+
46+
Route "blog_show" matches

‎cookbook/routing/external_resources.rst

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
.. index::
2+
single: Routing; Importing routing resources
3+
4+
How to Include External Routing Resources
5+
=========================================
6+
7+
All routes are loaded via a single configuration file - usually ``app/config/routing.yml``
8+
(see `Creating Routes`_ above). However, if you use routing annotations,
9+
you'll need to point the router to the controllers with the annotations.
10+
This can be done by "importing" directories into the routing configuration:
11+
12+
.. configuration-block::
13+
14+
.. code-block:: yaml
15+
16+
# app/config/routing.yml
17+
app:
18+
resource: '@AppBundle/Controller/'
19+
type: annotation # required to enable the Annotation reader for this resource
20+
21+
.. code-block:: xml
22+
23+
<!-- app/config/routing.xml -->
24+
<?xml version="1.0" encoding="UTF-8" ?>
25+
<routes xmlns="http://symfony.com/schema/routing"
26+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
27+
xsi:schemaLocation="http://symfony.com/schema/routing
28+
http://symfony.com/schema/routing/routing-1.0.xsd">
29+
30+
<!-- the type is required to enable the annotation reader for this resource -->
31+
<import resource="@AppBundle/Controller/" type="annotation"/>
32+
</routes>
33+
34+
.. code-block:: php
35+
36+
// app/config/routing.php
37+
use Symfony\Component\Routing\RouteCollection;
38+
39+
$collection = new RouteCollection();
40+
$collection->addCollection(
41+
// second argument is the type, which is required to enable
42+
// the annotation reader for this resource
43+
$loader->import("@AppBundle/Controller/", "annotation")
44+
);
45+
46+
return $collection;
47+
48+
.. note::
49+
50+
When importing resources from YAML, the key (e.g. ``app``) is meaningless.
51+
Just be sure that it's unique so no other lines override it.
52+
53+
The ``resource`` key loads the given routing resource. In this example the
54+
resource is a directory, where the ``@AppBundle`` shortcut syntax resolves
55+
to the full path of the AppBundle. When pointing to a directory, all files
56+
in that directory are parsed and put into the routing.
57+
58+
.. note::
59+
60+
You can also include other routing configuration files, this is often
61+
used to import the routing of third party bundles:
62+
63+
.. configuration-block::
64+
65+
.. code-block:: yaml
66+
67+
# app/config/routing.yml
68+
app:
69+
resource: '@AcmeOtherBundle/Resources/config/routing.yml'
70+
71+
.. code-block:: xml
72+
73+
<!-- app/config/routing.xml -->
74+
<?xml version="1.0" encoding="UTF-8" ?>
75+
<routes xmlns="http://symfony.com/schema/routing"
76+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
77+
xsi:schemaLocation="http://symfony.com/schema/routing
78+
http://symfony.com/schema/routing/routing-1.0.xsd">
79+
80+
<import resource="@AcmeOtherBundle/Resources/config/routing.xml" />
81+
</routes>
82+
83+
.. code-block:: php
84+
85+
// app/config/routing.php
86+
use Symfony\Component\Routing\RouteCollection;
87+
88+
$collection = new RouteCollection();
89+
$collection->addCollection(
90+
$loader->import("@AcmeOtherBundle/Resources/config/routing.php")
91+
);
92+
93+
return $collection;
94+
95+
Prefixing Imported Routes
96+
~~~~~~~~~~~~~~~~~~~~~~~~~
97+
98+
You can also choose to provide a "prefix" for the imported routes. For example,
99+
suppose you want to prefix all routes in the AppBundle with ``/site`` (e.g.
100+
``/site/blog/{slug}`` instead of ``/blog/{slug}``):
101+
102+
.. configuration-block::
103+
104+
.. code-block:: yaml
105+
106+
# app/config/routing.yml
107+
app:
108+
resource: '@AppBundle/Controller/'
109+
type: annotation
110+
prefix: /site
111+
112+
.. code-block:: xml
113+
114+
<!-- app/config/routing.xml -->
115+
<?xml version="1.0" encoding="UTF-8" ?>
116+
<routes xmlns="http://symfony.com/schema/routing"
117+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
118+
xsi:schemaLocation="http://symfony.com/schema/routing
119+
http://symfony.com/schema/routing/routing-1.0.xsd">
120+
121+
<import
122+
resource="@AppBundle/Controller/"
123+
type="annotation"
124+
prefix="/site" />
125+
</routes>
126+
127+
.. code-block:: php
128+
129+
// app/config/routing.php
130+
use Symfony\Component\Routing\RouteCollection;
131+
132+
$app = $loader->import('@AppBundle/Controller/', 'annotation');
133+
$app->addPrefix('/site');
134+
135+
$collection = new RouteCollection();
136+
$collection->addCollection($app);
137+
138+
return $collection;
139+
140+
The path of each route being loaded from the new routing resource will now
141+
be prefixed with the string ``/site``.
142+
143+
Adding a Host Requirement to Imported Routes
144+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
145+
146+
You can set the host regex on imported routes. For more information, see
147+
:ref:`component-routing-host-imported`.

‎cookbook/routing/index.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,8 @@ Routing
1313
redirect_trailing_slash
1414
extra_information
1515
routing_from_database
16+
optional_placeholders
17+
requirements
18+
conditions
19+
external_resources
20+
debug

0 commit comments

Comments
 (0)