diff --git a/book/routing.rst b/book/routing.rst index 905bc4be85e..960c9ed7e99 100644 --- a/book/routing.rst +++ b/book/routing.rst @@ -707,8 +707,8 @@ form via the same URL, while using distinct controllers for the two actions. If no ``methods`` are specified, the route will match on *all* methods. -Adding a Host -~~~~~~~~~~~~~ +Adding a Host Requirement +~~~~~~~~~~~~~~~~~~~~~~~~~ .. versionadded:: 2.2 Host matching support was added in Symfony 2.2 @@ -1067,8 +1067,8 @@ from the new routing resource. :doc:`FrameworkExtraBundle documentation ` to see how. -Adding a Host regex to Imported Routes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Adding a Host requirement to Imported Routes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. versionadded:: 2.2 Host matching support was added in Symfony 2.2 diff --git a/components/routing/hostname_pattern.rst b/components/routing/hostname_pattern.rst index dfe5df8a445..38499a918d8 100644 --- a/components/routing/hostname_pattern.rst +++ b/components/routing/hostname_pattern.rst @@ -60,17 +60,63 @@ You can also match on the HTTP *host* of the incoming request. Both routes match the same path ``/``, however the first one will match only if the host is ``m.example.com``. -Placeholders and Requirements in Hostname Patterns --------------------------------------------------- +Using Placeholders +------------------ -If you're using the :doc:`DependencyInjection Component ` -(or the full Symfony2 Framework), then you can use -:ref:`service container parameters ` as -variables anywhere in your routes. +The host option uses the same syntax as the path matching system. This means +you can use placeholders in your hostname: -You can avoid hardcoding the domain name by using a placeholder and a requirement. -The ``%domain%`` in requirements is replaced by the value of the ``domain`` -dependency injection container parameter. +.. configuration-block:: + + .. code-block:: yaml + + projects_homepage: + path: / + host: "{project_name}.example.com" + defaults: { _controller: AcmeDemoBundle:Main:mobileHomepage } + + homepage: + path: / + defaults: { _controller: AcmeDemoBundle:Main:homepage } + + .. code-block:: xml + + + + + + + AcmeDemoBundle:Main:mobileHomepage + + + + AcmeDemoBundle:Main:homepage + + + + .. code-block:: php + + use Symfony\Component\Routing\RouteCollection; + use Symfony\Component\Routing\Route; + + $collection = new RouteCollection(); + $collection->add('project_homepage', new Route('/', array( + '_controller' => 'AcmeDemoBundle:Main:mobileHomepage', + ), array(), array(), '{project_name}.example.com')); + + $collection->add('homepage', new Route('/', array( + '_controller' => 'AcmeDemoBundle:Main:homepage', + ))); + + return $collection; + +You can also set requirements and default options for these placeholders. For +instance, if you want to match both ``m.example.com`` and +``mobile.example.com``, you use this: .. configuration-block:: @@ -78,13 +124,15 @@ dependency injection container parameter. mobile_homepage: path: / - host: m.{domain} - defaults: { _controller: AcmeDemoBundle:Main:mobileHomepage } + host: "{subdomain}.example.com" + defaults: + _controller: AcmeDemoBundle:Main:mobileHomepage + subdomain: m requirements: - domain: %domain% + subdomain: m|mobile homepage: - path: / + path: / defaults: { _controller: AcmeDemoBundle:Main:homepage } .. code-block:: xml @@ -93,11 +141,15 @@ dependency injection container parameter. + xsi:schemaLocation="http://symfony.com/schema/routing + http://symfony.com/schema/routing/routing-1.0.xsd" + > - + AcmeDemoBundle:Main:mobileHomepage - %domain% + m + + m|mobile @@ -113,9 +165,10 @@ dependency injection container parameter. $collection = new RouteCollection(); $collection->add('mobile_homepage', new Route('/', array( '_controller' => 'AcmeDemoBundle:Main:mobileHomepage', + 'subdomain' => 'm', ), array( - 'domain' => '%domain%', - ), array(), 'm.{domain}')); + 'subdomain' => 'm|mobile', + ), array(), '{subdomain}.example.com')); $collection->add('homepage', new Route('/', array( '_controller' => 'AcmeDemoBundle:Main:homepage', @@ -123,12 +176,74 @@ dependency injection container parameter. return $collection; +.. tip:: + + Make sure you also include a default option for the ``subdomain`` + placeholder, otherwise you need to include the subdomains value each time + you generate the route. + +.. sidebar:: Using Service Parameters + + You can also use service parameters if you do not want to hardcode the + hostname: + + .. configuration-block:: + + .. code-block:: yaml + + mobile_homepage: + path: / + host: "m.{domain}" + defaults: { _controller: AcmeDemoBundle:Main:mobileHomepage } + requirements: + domain: "%domain%" + + homepage: + path: / + defaults: { _controller: AcmeDemoBundle:Main:homepage } + + .. code-block:: xml + + + + + + + AcmeDemoBundle:Main:mobileHomepage + %domain% + + + + AcmeDemoBundle:Main:homepage + + + + .. code-block:: php + + use Symfony\Component\Routing\RouteCollection; + use Symfony\Component\Routing\Route; + + $collection = new RouteCollection(); + $collection->add('mobile_homepage', new Route('/', array( + '_controller' => 'AcmeDemoBundle:Main:mobileHomepage', + ), array( + 'domain' => '%domain%', + ), array(), 'm.{domain}')); + + $collection->add('homepage', new Route('/', array( + '_controller' => 'AcmeDemoBundle:Main:homepage', + ))); + + return $collection; + .. _component-routing-host-imported: -Adding a Host Regex to Imported Routes --------------------------------------------- +Using Host Matching of Imported Routes +-------------------------------------- -You can set a host regex on imported routes: +You can also set the host option on imported routes: .. configuration-block::