Skip to content

Commit 1d2aefa

Browse files
weaverryanweaverryan
committed
[#1894] Refactoring the hostname routing stuff into a component "cookbook" article with inter-links
1 parent 781d76c commit 1d2aefa

File tree

5 files changed

+178
-155
lines changed

5 files changed

+178
-155
lines changed

‎book/routing.rst

Lines changed: 11 additions & 152 deletions
Original file line numberDiff line numberDiff line change
@@ -703,117 +703,9 @@ Adding a Hostname Pattern
703703
.. versionadded:: 2.2
704704
Hostname matching support was added in Symfony 2.2
705705

706-
You can also match on the HTTP *hostname* of the incoming request:
707-
708-
.. configuration-block::
709-
710-
.. code-block:: yaml
711-
712-
mobile_homepage:
713-
pattern: /
714-
hostname_pattern: m.example.com
715-
defaults: { _controller: AcmeDemoBundle:Main:mobileHomepage }
716-
717-
homepage:
718-
pattern: /
719-
defaults: { _controller: AcmeDemoBundle:Main:homepage }
720-
721-
.. code-block:: xml
722-
723-
<?xml version="1.0" encoding="UTF-8" ?>
724-
725-
<routes xmlns="http://symfony.com/schema/routing"
726-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
727-
xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd">
728-
729-
<route id="mobile_homepage" pattern="/" hostname-pattern="m.example.com">
730-
<default key="_controller">AcmeDemoBundle:Main:mobileHomepage</default>
731-
</route>
732-
733-
<route id="homepage" pattern="/">
734-
<default key="_controller">AcmeDemoBundle:Main:homepage</default>
735-
</route>
736-
</routes>
737-
738-
.. code-block:: php
739-
740-
use Symfony\Component\Routing\RouteCollection;
741-
use Symfony\Component\Routing\Route;
742-
743-
$collection = new RouteCollection();
744-
$collection->add('mobile_homepage', new Route('/', array(
745-
'_controller' => 'AcmeDemoBundle:Main:mobileHomepage',
746-
), array(), array(), 'm.example.com'));
747-
748-
$collection->add('homepage', new Route('/', array(
749-
'_controller' => 'AcmeDemoBundle:Main:homepage',
750-
)));
751-
752-
return $collection;
753-
754-
Both routes match the same pattern ``/``, however the first one will match
755-
only if the hostname is ``m.example.com``.
756-
757-
Placeholders and Requirements in Hostname Patterns
758-
--------------------------------------------------
759-
760-
Placeholders can be used in hostname patterns as well as in patterns, and
761-
requirements also apply to them.
762-
763-
In the following example we avoid hardcoding the domain name by using a
764-
placeholder and a requirement. ``%domain%`` in requirements is replaced
765-
by the value of the ``domain`` dependency injection container parameter.
766-
767-
.. configuration-block::
768-
769-
.. code-block:: yaml
770-
771-
mobile_homepage:
772-
pattern: /
773-
hostname_pattern: m.{domain}
774-
defaults: { _controller: AcmeDemoBundle:Main:mobileHomepage }
775-
requirements:
776-
domain: %domain%
777-
778-
homepage:
779-
pattern: /
780-
defaults: { _controller: AcmeDemoBundle:Main:homepage }
781-
782-
.. code-block:: xml
783-
784-
<?xml version="1.0" encoding="UTF-8" ?>
785-
786-
<routes xmlns="http://symfony.com/schema/routing"
787-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
788-
xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd">
789-
790-
<route id="mobile_homepage" pattern="/" hostname-pattern="m.example.com">
791-
<default key="_controller">AcmeDemoBundle:Main:mobileHomepage</default>
792-
<requirement key="domain">%domain%</requirement>
793-
</route>
794-
795-
<route id="homepage" pattern="/">
796-
<default key="_controller">AcmeDemoBundle:Main:homepage</default>
797-
</route>
798-
</routes>
799-
800-
.. code-block:: php
801-
802-
use Symfony\Component\Routing\RouteCollection;
803-
use Symfony\Component\Routing\Route;
804-
805-
$collection = new RouteCollection();
806-
$collection->add('mobile_homepage', new Route('/', array(
807-
'_controller' => 'AcmeDemoBundle:Main:mobileHomepage',
808-
), array(
809-
'domain' => '%domain%',
810-
), array(), 'm.{domain}'));
811-
812-
$collection->add('homepage', new Route('/', array(
813-
'_controller' => 'AcmeDemoBundle:Main:homepage',
814-
)));
815-
816-
return $collection;
706+
You can also match on the HTTP *hostname* of the incoming request. For more
707+
information, see :doc:`/components/routing/hostname_pattern` in the Routing
708+
component documentation.
817709

818710
.. index::
819711
single: Routing; Advanced example
@@ -1137,53 +1029,20 @@ instead of simply ``/hello/{name}``:
11371029
The string ``/admin`` will now be prepended to the pattern of each route
11381030
loaded from the new routing resource.
11391031

1032+
.. tip::
1033+
1034+
You can also define routes using annotations. See the
1035+
:doc:`FrameworkExtraBundle documentation</bundles/SensioFrameworkExtraBundle/annotations/routing>`
1036+
to see how.
1037+
11401038
Adding a Hostname Pattern to Imported Routes
11411039
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
11421040

11431041
.. versionadded:: 2.2
11441042
Hostname matching support was added in Symfony 2.2
11451043

1146-
You can set a hostname pattern on imported routes:
1147-
1148-
.. configuration-block::
1149-
1150-
.. code-block:: yaml
1151-
1152-
# app/config/routing.yml
1153-
acme_hello:
1154-
resource: "@AcmeHelloBundle/Resources/config/routing.yml"
1155-
hostname_pattern: "hello.example.com"
1156-
1157-
.. code-block:: xml
1158-
1159-
<!-- app/config/routing.xml -->
1160-
<?xml version="1.0" encoding="UTF-8" ?>
1161-
1162-
<routes xmlns="http://symfony.com/schema/routing"
1163-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
1164-
xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd">
1165-
1166-
<import resource="@AcmeHelloBundle/Resources/config/routing.xml" hostname-pattern="hello.example.com" />
1167-
</routes>
1168-
1169-
.. code-block:: php
1170-
1171-
// app/config/routing.php
1172-
use Symfony\Component\Routing\RouteCollection;
1173-
1174-
$collection = new RouteCollection();
1175-
$collection->addCollection($loader->import("@AcmeHelloBundle/Resources/config/routing.php"), '', array(), array(), array(), 'hello.example.com');
1176-
1177-
return $collection;
1178-
1179-
The hostname pattern ``hello.example.com`` will be set on each route
1180-
loaded from the new routing resource.
1181-
1182-
.. tip::
1183-
1184-
You can also define routes using annotations. See the
1185-
:doc:`FrameworkExtraBundle documentation</bundles/SensioFrameworkExtraBundle/annotations/routing>`
1186-
to see how.
1044+
You can set a hostname pattern on imported routes. For more information,
1045+
see :ref:`component-routing-hostname-imported`.
11871046

11881047
.. index::
11891048
single: Routing; Debugging

‎components/map.rst.inc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@
6767
* :doc:`/components/routing/index`
6868

6969
* :doc:`/components/routing/introduction`
70+
* :doc:`/components/routing/hostname_pattern`
7071

7172
* **Serializer**
7273

‎components/routing/hostname_pattern.rst

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
.. index::
2+
single: Routing; Matching on Hostname
3+
4+
How to match a route based on the Hostname
5+
==========================================
6+
7+
.. versionadded:: 2.2
8+
Hostname matching support was added in Symfony 2.2
9+
10+
You can also match on the HTTP *hostname* of the incoming request.
11+
12+
.. configuration-block::
13+
14+
.. code-block:: yaml
15+
16+
mobile_homepage:
17+
pattern: /
18+
hostname_pattern: m.example.com
19+
defaults: { _controller: AcmeDemoBundle:Main:mobileHomepage }
20+
21+
homepage:
22+
pattern: /
23+
defaults: { _controller: AcmeDemoBundle:Main:homepage }
24+
25+
.. code-block:: xml
26+
27+
<?xml version="1.0" encoding="UTF-8" ?>
28+
29+
<routes xmlns="http://symfony.com/schema/routing"
30+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
31+
xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd">
32+
33+
<route id="mobile_homepage" pattern="/" hostname-pattern="m.example.com">
34+
<default key="_controller">AcmeDemoBundle:Main:mobileHomepage</default>
35+
</route>
36+
37+
<route id="homepage" pattern="/">
38+
<default key="_controller">AcmeDemoBundle:Main:homepage</default>
39+
</route>
40+
</routes>
41+
42+
.. code-block:: php
43+
44+
use Symfony\Component\Routing\RouteCollection;
45+
use Symfony\Component\Routing\Route;
46+
47+
$collection = new RouteCollection();
48+
$collection->add('mobile_homepage', new Route('/', array(
49+
'_controller' => 'AcmeDemoBundle:Main:mobileHomepage',
50+
), array(), array(), 'm.example.com'));
51+
52+
$collection->add('homepage', new Route('/', array(
53+
'_controller' => 'AcmeDemoBundle:Main:homepage',
54+
)));
55+
56+
return $collection;
57+
58+
Both routes match the same pattern ``/``, however the first one will match
59+
only if the hostname is ``m.example.com``.
60+
61+
Placeholders and Requirements in Hostname Patterns
62+
--------------------------------------------------
63+
64+
If you're using the :doc:`DependencyInjection Component</components/dependency_injection/index>`
65+
(or the full Symfony2 Framework), then you can use
66+
:ref:`service container parameters<book-service-container-parameters>` as
67+
variables anywhere in your routes.
68+
69+
You can avoid hardcoding the domain name by using a placeholder and a requirement.
70+
The ``%domain%`` in requirements is replaced by the value of the ``domain``
71+
dependency injection container parameter.
72+
73+
.. configuration-block::
74+
75+
.. code-block:: yaml
76+
77+
mobile_homepage:
78+
pattern: /
79+
hostname_pattern: m.{domain}
80+
defaults: { _controller: AcmeDemoBundle:Main:mobileHomepage }
81+
requirements:
82+
domain: %domain%
83+
84+
homepage:
85+
pattern: /
86+
defaults: { _controller: AcmeDemoBundle:Main:homepage }
87+
88+
.. code-block:: xml
89+
90+
<?xml version="1.0" encoding="UTF-8" ?>
91+
92+
<routes xmlns="http://symfony.com/schema/routing"
93+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
94+
xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd">
95+
96+
<route id="mobile_homepage" pattern="/" hostname-pattern="m.example.com">
97+
<default key="_controller">AcmeDemoBundle:Main:mobileHomepage</default>
98+
<requirement key="domain">%domain%</requirement>
99+
</route>
100+
101+
<route id="homepage" pattern="/">
102+
<default key="_controller">AcmeDemoBundle:Main:homepage</default>
103+
</route>
104+
</routes>
105+
106+
.. code-block:: php
107+
108+
use Symfony\Component\Routing\RouteCollection;
109+
use Symfony\Component\Routing\Route;
110+
111+
$collection = new RouteCollection();
112+
$collection->add('mobile_homepage', new Route('/', array(
113+
'_controller' => 'AcmeDemoBundle:Main:mobileHomepage',
114+
), array(
115+
'domain' => '%domain%',
116+
), array(), 'm.{domain}'));
117+
118+
$collection->add('homepage', new Route('/', array(
119+
'_controller' => 'AcmeDemoBundle:Main:homepage',
120+
)));
121+
122+
return $collection;
123+
124+
.. _component-routing-hostname-imported:
125+
126+
Adding a Hostname Pattern to Imported Routes
127+
--------------------------------------------
128+
129+
You can set a hostname pattern on imported routes:
130+
131+
.. configuration-block::
132+
133+
.. code-block:: yaml
134+
135+
# app/config/routing.yml
136+
acme_hello:
137+
resource: "@AcmeHelloBundle/Resources/config/routing.yml"
138+
hostname_pattern: "hello.example.com"
139+
140+
.. code-block:: xml
141+
142+
<!-- app/config/routing.xml -->
143+
<?xml version="1.0" encoding="UTF-8" ?>
144+
145+
<routes xmlns="http://symfony.com/schema/routing"
146+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
147+
xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd">
148+
149+
<import resource="@AcmeHelloBundle/Resources/config/routing.xml" hostname-pattern="hello.example.com" />
150+
</routes>
151+
152+
.. code-block:: php
153+
154+
// app/config/routing.php
155+
use Symfony\Component\Routing\RouteCollection;
156+
157+
$collection = new RouteCollection();
158+
$collection->addCollection($loader->import("@AcmeHelloBundle/Resources/config/routing.php"), '', array(), array(), array(), 'hello.example.com');
159+
160+
return $collection;
161+
162+
The hostname pattern ``hello.example.com`` will be set on each route
163+
loaded from the new routing resource.

‎components/routing/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,4 @@ Routing
55
:maxdepth: 2
66

77
introduction
8+
hostname_pattern

‎components/routing/introduction.rst

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -85,9 +85,8 @@ placeholders as regular expressions.
8585
4. An array of options. These contain internal settings for the route and
8686
are the least commonly needed.
8787

88-
5. A hostname pattern. This is matched against the hostname passed to the
89-
`RequestContext`, and can contain named wildcard placeholders (e.g.
90-
``{placeholders}``) to match dynamic parts in the hostname.
88+
5. A hostname pattern. This is matched against the hostname of the request.
89+
See :doc:`/components/routing/hostname_pattern` for more details.
9190

9291
.. versionadded:: 2.2
9392
The hostname pattern was added in Symfony 2.2

0 commit comments

Comments
 (0)