From 8420b022728a0cbd9628831bca25734d04058f03 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Mon, 21 Jan 2013 14:16:29 +0100 Subject: [PATCH 1/5] Fixes most pattern, _scheme or _method occurences --- book/controller.rst | 14 +-- book/from_flat_php_to_symfony2.rst | 4 +- book/http_fundamentals.rst | 4 +- book/page_creation.rst | 10 +- book/routing.rst | 107 ++++++++---------- book/templating.rst | 8 +- book/translation.rst | 6 +- components/routing/hostname_pattern.rst | 32 +++--- components/routing/introduction.rst | 49 ++++---- cookbook/routing/method_parameters.rst | 46 +++----- cookbook/routing/redirect_in_config.rst | 4 +- cookbook/routing/scheme.rst | 18 ++- .../routing/service_container_parameters.rst | 14 +-- cookbook/routing/slash_in_parameter.rst | 10 +- 14 files changed, 145 insertions(+), 181 deletions(-) diff --git a/book/controller.rst b/book/controller.rst index efd310c8b33..ca6692b5565 100644 --- a/book/controller.rst +++ b/book/controller.rst @@ -141,7 +141,7 @@ Mapping a URL to a Controller ----------------------------- The new controller returns a simple HTML page. To actually view this page -in your browser, you need to create a route, which maps a specific URL pattern +in your browser, you need to create a route, which maps a specific URL path to the controller: .. configuration-block:: @@ -150,13 +150,13 @@ to the controller: # app/config/routing.yml hello: - pattern: /hello/{name} - defaults: { _controller: AcmeHelloBundle:Hello:index } + path: /hello/{name} + defaults: { _controller: AcmeHelloBundle:Hello:index } .. code-block:: xml - + AcmeHelloBundle:Hello:index @@ -229,13 +229,13 @@ example: # app/config/routing.yml hello: - pattern: /hello/{first_name}/{last_name} - defaults: { _controller: AcmeHelloBundle:Hello:index, color: green } + path: /hello/{first_name}/{last_name} + defaults: { _controller: AcmeHelloBundle:Hello:index, color: green } .. code-block:: xml - + AcmeHelloBundle:Hello:index green diff --git a/book/from_flat_php_to_symfony2.rst b/book/from_flat_php_to_symfony2.rst index 3796084c3e7..8476bc1d010 100644 --- a/book/from_flat_php_to_symfony2.rst +++ b/book/from_flat_php_to_symfony2.rst @@ -639,11 +639,11 @@ A routing configuration map provides this information in a readable format: # app/config/routing.yml blog_list: - pattern: /blog + path: /blog defaults: { _controller: AcmeBlogBundle:Blog:list } blog_show: - pattern: /blog/show/{id} + path: /blog/show/{id} defaults: { _controller: AcmeBlogBundle:Blog:show } Now that Symfony2 is handling all the mundane tasks, the front controller diff --git a/book/http_fundamentals.rst b/book/http_fundamentals.rst index c39d0889856..ff864cd9a4c 100644 --- a/book/http_fundamentals.rst +++ b/book/http_fundamentals.rst @@ -423,12 +423,12 @@ by adding an entry for ``/contact`` to your routing configuration file: # app/config/routing.yml contact: - pattern: /contact + path: /contact defaults: { _controller: AcmeDemoBundle:Main:contact } .. code-block:: xml - + AcmeBlogBundle:Main:contact diff --git a/book/page_creation.rst b/book/page_creation.rst index b07b7b43b96..e30f0c7d5d3 100644 --- a/book/page_creation.rst +++ b/book/page_creation.rst @@ -8,7 +8,7 @@ Creating a new page in Symfony2 is a simple two-step process: * *Create a route*: A route defines the URL (e.g. ``/about``) to your page and specifies a controller (which is a PHP function) that Symfony2 should - execute when the URL of an incoming request matches the route pattern; + execute when the URL of an incoming request matches the route path; * *Create a controller*: A controller is a PHP function that takes the incoming request and transforms it into the Symfony2 ``Response`` object that's @@ -147,7 +147,7 @@ the new route that defines the URL of the page that you're about to create: # src/Acme/HelloBundle/Resources/config/routing.yml hello: - pattern: /hello/{name} + path: /hello/{name} defaults: { _controller: AcmeHelloBundle:Hello:index } .. code-block:: xml @@ -159,7 +159,7 @@ the new route that defines the URL of the page that you're about to create: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd"> - + AcmeHelloBundle:Hello:index @@ -177,9 +177,9 @@ the new route that defines the URL of the page that you're about to create: return $collection; -The routing consists of two basic pieces: the ``pattern``, which is the URL +The routing consists of two basic pieces: the ``path``, which is the URL that this route will match, and a ``defaults`` array, which specifies the -controller that should be executed. The placeholder syntax in the pattern +controller that should be executed. The placeholder syntax in the path (``{name}``) is a wildcard. It means that ``/hello/Ryan``, ``/hello/Fabien`` or any other similar URL will match this route. The ``{name}`` placeholder parameter will also be passed to the controller so that you can use its value diff --git a/book/routing.rst b/book/routing.rst index f077111514c..d13d6118756 100644 --- a/book/routing.rst +++ b/book/routing.rst @@ -27,7 +27,7 @@ areas of your application. By the end of this chapter, you'll be able to: Routing in Action ----------------- -A *route* is a map from a URL pattern to a controller. For example, suppose +A *route* is a map from a URL path to a controller. For example, suppose you want to match any URL like ``/blog/my-post`` or ``/blog/all-about-symfony`` and send it to a controller that can look up and render that blog entry. The route is simple: @@ -38,7 +38,7 @@ The route is simple: # app/config/routing.yml blog_show: - pattern: /blog/{slug} + path: /blog/{slug} defaults: { _controller: AcmeBlogBundle:Blog:show } .. code-block:: xml @@ -49,7 +49,7 @@ The route is simple: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd"> - + AcmeBlogBundle:Blog:show @@ -67,7 +67,7 @@ The route is simple: return $collection; -The pattern defined by the ``blog_show`` route acts like ``/blog/*`` where +The path defined by the ``blog_show`` route acts like ``/blog/*`` where the wildcard is given the name ``slug``. For the URL ``/blog/my-blog-post``, the ``slug`` variable gets a value of ``my-blog-post``, which is available for you to use in your controller (keep reading). @@ -186,7 +186,7 @@ Basic Route Configuration ~~~~~~~~~~~~~~~~~~~~~~~~~ Defining a route is easy, and a typical application will have lots of routes. -A basic route consists of just two parts: the ``pattern`` to match and a +A basic route consists of just two parts: the ``path`` to match and a ``defaults`` array: .. configuration-block:: @@ -194,7 +194,7 @@ A basic route consists of just two parts: the ``pattern`` to match and a .. code-block:: yaml _welcome: - pattern: / + path: / defaults: { _controller: AcmeDemoBundle:Main:homepage } .. code-block:: xml @@ -205,7 +205,7 @@ A basic route consists of just two parts: the ``pattern`` to match and a xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd"> - + AcmeDemoBundle:Main:homepage @@ -242,7 +242,7 @@ routes will contain one or more named "wildcard" placeholders: .. code-block:: yaml blog_show: - pattern: /blog/{slug} + path: /blog/{slug} defaults: { _controller: AcmeBlogBundle:Blog:show } .. code-block:: xml @@ -253,7 +253,7 @@ routes will contain one or more named "wildcard" placeholders: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd"> - + AcmeBlogBundle:Blog:show @@ -270,13 +270,13 @@ routes will contain one or more named "wildcard" placeholders: return $collection; -The pattern will match anything that looks like ``/blog/*``. Even better, +The path will match anything that looks like ``/blog/*``. Even better, the value matching the ``{slug}`` placeholder will be available inside your controller. In other words, if the URL is ``/blog/hello-world``, a ``$slug`` variable, with a value of ``hello-world``, will be available in the controller. This can be used, for example, to load the blog post matching that string. -The pattern will *not*, however, match simply ``/blog``. That's because, +The path will *not*, however, match simply ``/blog``. That's because, by default, all placeholders are required. This can be changed by adding a placeholder value to the ``defaults`` array. @@ -291,7 +291,7 @@ the available blog posts for this imaginary blog application: .. code-block:: yaml blog: - pattern: /blog + path: /blog defaults: { _controller: AcmeBlogBundle:Blog:index } .. code-block:: xml @@ -302,7 +302,7 @@ the available blog posts for this imaginary blog application: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd"> - + AcmeBlogBundle:Blog:index @@ -329,7 +329,7 @@ entries? Update the route to have a new ``{page}`` placeholder: .. code-block:: yaml blog: - pattern: /blog/{page} + path: /blog/{page} defaults: { _controller: AcmeBlogBundle:Blog:index } .. code-block:: xml @@ -340,7 +340,7 @@ entries? Update the route to have a new ``{page}`` placeholder: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd"> - + AcmeBlogBundle:Blog:index @@ -372,7 +372,7 @@ This is done by including it in the ``defaults`` collection: .. code-block:: yaml blog: - pattern: /blog/{page} + path: /blog/{page} defaults: { _controller: AcmeBlogBundle:Blog:index, page: 1 } .. code-block:: xml @@ -383,7 +383,7 @@ This is done by including it in the ``defaults`` collection: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd"> - + AcmeBlogBundle:Blog:index 1 @@ -433,11 +433,11 @@ Take a quick look at the routes that have been created so far: .. code-block:: yaml blog: - pattern: /blog/{page} + path: /blog/{page} defaults: { _controller: AcmeBlogBundle:Blog:index, page: 1 } blog_show: - pattern: /blog/{slug} + path: /blog/{slug} defaults: { _controller: AcmeBlogBundle:Blog:show } .. code-block:: xml @@ -448,12 +448,12 @@ Take a quick look at the routes that have been created so far: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd"> - + AcmeBlogBundle:Blog:index 1 - + AcmeBlogBundle:Blog:show @@ -475,7 +475,7 @@ Take a quick look at the routes that have been created so far: return $collection; -Can you spot the problem? Notice that both routes have patterns that match +Can you spot the problem? Notice that both routes have paths that match URL's that look like ``/blog/*``. The Symfony router will always choose the **first** matching route it finds. In other words, the ``blog_show`` route will *never* be matched. Instead, a URL like ``/blog/my-blog-post`` will match @@ -491,7 +491,7 @@ to the ``{page}`` parameter. +--------------------+-------+-----------------------+ The answer to the problem is to add route *requirements*. The routes in this -example would work perfectly if the ``/blog/{page}`` pattern *only* matched +example would work perfectly if the ``/blog/{page}`` path *only* matched URLs where the ``{page}`` portion is an integer. Fortunately, regular expression requirements can easily be added for each parameter. For example: @@ -500,7 +500,7 @@ requirements can easily be added for each parameter. For example: .. code-block:: yaml blog: - pattern: /blog/{page} + path: /blog/{page} defaults: { _controller: AcmeBlogBundle:Blog:index, page: 1 } requirements: page: \d+ @@ -513,7 +513,7 @@ requirements can easily be added for each parameter. For example: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd"> - + AcmeBlogBundle:Blog:index 1 \d+ @@ -570,7 +570,7 @@ URL: .. code-block:: yaml homepage: - pattern: /{culture} + path: /{culture} defaults: { _controller: AcmeDemoBundle:Main:homepage, culture: en } requirements: culture: en|fr @@ -583,7 +583,7 @@ URL: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd"> - + AcmeDemoBundle:Main:homepage en en|fr @@ -635,16 +635,14 @@ be accomplished with the following route configuration: .. code-block:: yaml contact: - pattern: /contact + path: /contact defaults: { _controller: AcmeDemoBundle:Main:contact } - requirements: - _method: GET + methods: [GET] contact_process: - pattern: /contact + path: /contact defaults: { _controller: AcmeDemoBundle:Main:contactProcess } - requirements: - _method: POST + methods: [POST] .. code-block:: xml @@ -654,14 +652,12 @@ be accomplished with the following route configuration: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd"> - + AcmeDemoBundle:Main:contact - GET - + AcmeDemoBundle:Main:contactProcess - POST @@ -673,29 +669,22 @@ be accomplished with the following route configuration: $collection = new RouteCollection(); $collection->add('contact', new Route('/contact', array( '_controller' => 'AcmeDemoBundle:Main:contact', - ), array( - '_method' => 'GET', - ))); + ), array(), array(), '', array(), array('GET'))); $collection->add('contact_process', new Route('/contact', array( '_controller' => 'AcmeDemoBundle:Main:contactProcess', - ), array( - '_method' => 'POST', - ))); + ), array(), array(), '', array(), array('POST'))); return $collection; -Despite the fact that these two routes have identical patterns (``/contact``), +Despite the fact that these two routes have identical paths (``/contact``), the first route will match only GET requests and the second route will match only POST requests. This means that you can display the form and submit the form via the same URL, while using distinct controllers for the two actions. .. note:: - If no ``_method`` requirement is specified, the route will match on - *all* methods. -Like the other requirements, the ``_method`` requirement is parsed as a regular -expression. To match ``GET`` *or* ``POST`` requests, you can use ``GET|POST``. + If no ``methods`` are specified, the route will match on *all* methods. Adding a Hostname Pattern ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -725,7 +714,7 @@ routing system can be: .. code-block:: yaml article_show: - pattern: /articles/{culture}/{year}/{title}.{_format} + path: /articles/{culture}/{year}/{title}.{_format} defaults: { _controller: AcmeDemoBundle:Article:show, _format: html } requirements: culture: en|fr @@ -740,7 +729,7 @@ routing system can be: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd"> - + AcmeDemoBundle:Article:show html en|fr @@ -961,7 +950,7 @@ like this: # src/Acme/HelloBundle/Resources/config/routing.yml acme_hello: - pattern: /hello/{name} + path: /hello/{name} defaults: { _controller: AcmeHelloBundle:Hello:index } .. code-block:: xml @@ -973,7 +962,7 @@ like this: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd"> - + AcmeHelloBundle:Hello:index @@ -998,7 +987,7 @@ Prefixing Imported Routes ~~~~~~~~~~~~~~~~~~~~~~~~~ You can also choose to provide a "prefix" for the imported routes. For example, -suppose you want the ``acme_hello`` route to have a final pattern of ``/admin/hello/{name}`` +suppose you want the ``acme_hello`` route to have a final path of ``/admin/hello/{name}`` instead of simply ``/hello/{name}``: .. configuration-block:: @@ -1032,8 +1021,8 @@ instead of simply ``/hello/{name}``: return $collection; -The string ``/admin`` will now be prepended to the pattern of each route -loaded from the new routing resource. +The string ``/admin`` will now be prepended to the path of each route loaded +from the new routing resource. .. tip:: @@ -1047,8 +1036,8 @@ Adding a Hostname Pattern to Imported Routes .. versionadded:: 2.2 Hostname matching support was added in Symfony 2.2 -You can set a hostname pattern on imported routes. For more information, -see :ref:`component-routing-hostname-imported`. +You can set the hostname on imported routes. For more information, see +:ref:`component-routing-hostname-imported`. .. index:: single: Routing; Debugging @@ -1118,8 +1107,8 @@ system. Take the ``blog_show`` example route from earlier:: // /blog/my-blog-post To generate a URL, you need to specify the name of the route (e.g. ``blog_show``) -and any wildcards (e.g. ``slug = my-blog-post``) used in the pattern for -that route. With this information, any URL can easily be generated:: +and any wildcards (e.g. ``slug = my-blog-post``) used in the path for that +route. With this information, any URL can easily be generated:: class MainController extends Controller { diff --git a/book/templating.rst b/book/templating.rst index 720befe4465..b13e5c4815e 100644 --- a/book/templating.rst +++ b/book/templating.rst @@ -781,12 +781,12 @@ configuration: .. code-block:: yaml _welcome: - pattern: / + path: / defaults: { _controller: AcmeDemoBundle:Welcome:index } .. code-block:: xml - + AcmeDemoBundle:Welcome:index @@ -819,12 +819,12 @@ route: .. code-block:: yaml article_show: - pattern: /article/{slug} + path: /article/{slug} defaults: { _controller: AcmeArticleBundle:Article:show } .. code-block:: xml - + AcmeArticleBundle:Article:show diff --git a/book/translation.rst b/book/translation.rst index 6c6ea3da1c2..efefdccd256 100644 --- a/book/translation.rst +++ b/book/translation.rst @@ -299,7 +299,7 @@ priority message files. The filename of the translations is also important as Symfony2 uses a convention to determine details about the translations. Each message file must be named -according to the following pattern: ``domain.locale.loader``: +according to the following path: ``domain.locale.loader``: * **domain**: An optional way to organize messages into groups (e.g. ``admin``, ``navigation`` or the default ``messages``) - see `Using Message Domains`_; @@ -571,14 +571,14 @@ by the routing system using the special ``_locale`` parameter: .. code-block:: yaml contact: - pattern: /{_locale}/contact + path: /{_locale}/contact defaults: { _controller: AcmeDemoBundle:Contact:index, _locale: en } requirements: _locale: en|fr|de .. code-block:: xml - + AcmeDemoBundle:Contact:index en en|fr|de diff --git a/components/routing/hostname_pattern.rst b/components/routing/hostname_pattern.rst index f41f2db5414..488b000373e 100644 --- a/components/routing/hostname_pattern.rst +++ b/components/routing/hostname_pattern.rst @@ -14,12 +14,12 @@ You can also match on the HTTP *hostname* of the incoming request. .. code-block:: yaml mobile_homepage: - pattern: / - hostname_pattern: m.example.com + path: / + hostname: m.example.com defaults: { _controller: AcmeDemoBundle:Main:mobileHomepage } homepage: - pattern: / + path: / defaults: { _controller: AcmeDemoBundle:Main:homepage } .. code-block:: xml @@ -32,11 +32,11 @@ You can also match on the HTTP *hostname* of the incoming request. http://symfony.com/schema/routing/routing-1.0.xsd" > - + AcmeDemoBundle:Main:mobileHomepage - + AcmeDemoBundle:Main:homepage @@ -57,7 +57,7 @@ You can also match on the HTTP *hostname* of the incoming request. return $collection; -Both routes match the same pattern ``/``, however the first one will match +Both routes match the same path ``/``, however the first one will match only if the hostname is ``m.example.com``. Placeholders and Requirements in Hostname Patterns @@ -77,14 +77,14 @@ dependency injection container parameter. .. code-block:: yaml mobile_homepage: - pattern: / - hostname_pattern: m.{domain} + path: / + hostname: m.{domain} defaults: { _controller: AcmeDemoBundle:Main:mobileHomepage } requirements: domain: %domain% homepage: - pattern: / + path: / defaults: { _controller: AcmeDemoBundle:Main:homepage } .. code-block:: xml @@ -95,12 +95,12 @@ dependency injection container parameter. xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd"> - + AcmeDemoBundle:Main:mobileHomepage %domain% - + AcmeDemoBundle:Main:homepage @@ -128,7 +128,7 @@ dependency injection container parameter. Adding a Hostname Pattern to Imported Routes -------------------------------------------- -You can set a hostname pattern on imported routes: +You can set a hostname on imported routes: .. configuration-block:: @@ -137,7 +137,7 @@ You can set a hostname pattern on imported routes: # app/config/routing.yml acme_hello: resource: "@AcmeHelloBundle/Resources/config/routing.yml" - hostname_pattern: "hello.example.com" + hostname: "hello.example.com" .. code-block:: xml @@ -148,7 +148,7 @@ You can set a hostname pattern on imported routes: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd"> - + .. code-block:: php @@ -161,5 +161,5 @@ You can set a hostname pattern on imported routes: return $collection; -The hostname pattern ``hello.example.com`` will be set on each route -loaded from the new routing resource. +The hostname ``hello.example.com`` will be set on each route loaded from the +new routing resource. diff --git a/components/routing/introduction.rst b/components/routing/introduction.rst index daf0facf1aa..39cdad0d975 100644 --- a/components/routing/introduction.rst +++ b/components/routing/introduction.rst @@ -70,9 +70,9 @@ which holds the name of the matched route. Defining routes ~~~~~~~~~~~~~~~ -A full route definition can contain up to five parts: +A full route definition can contain up to seven parts: -1. The URL pattern route. This is matched against the URL passed to the `RequestContext`, +1. The URL path route. This is matched against the URL passed to the `RequestContext`, and can contain named wildcard placeholders (e.g. ``{placeholders}``) to match dynamic parts in the URL. @@ -85,11 +85,16 @@ placeholders as regular expressions. 4. An array of options. These contain internal settings for the route and are the least commonly needed. -5. A hostname pattern. This is matched against the hostname of the request. -See :doc:`/components/routing/hostname_pattern` for more details. +5. A hostname. This is matched against the hostname of the request. See + :doc:`/components/routing/hostname_pattern` for more details. + +6. An array of schemes. These enforce a certain HTTP scheme (``http``, ``https``). + +7. An array of methods. These enforce a certain HTTP request method (``HEAD``, + ``GET``, ``POST``, ...). .. versionadded:: 2.2 - The hostname pattern was added in Symfony 2.2 + The hostname was added in Symfony 2.2 Take the following route, which combines several of these ideas:: @@ -98,7 +103,9 @@ Take the following route, which combines several of these ideas:: array('controller' => 'showArchive'), // default values array('month' => '[0-9]{4}-[0-9]{2}', 'subdomain' => 'www|m'), // requirements array(), // options - '{subdomain}.example.com' // hostname + '{subdomain}.example.com', // hostname + array(), // schemes + array() // methods ); // ... @@ -118,21 +125,6 @@ In this case, the route is matched by ``/archive/2012-01``, because the ``{month wildcard matches the regular expression wildcard given. However, ``/archive/foo`` does *not* match, because "foo" fails the month wildcard. -Besides the regular expression constraints there are two special requirements -you can define: - -* ``_method`` enforces a certain HTTP request method (``HEAD``, ``GET``, ``POST``, ...) -* ``_scheme`` enforces a certain HTTP scheme (``http``, ``https``) - -For example, the following route would only accept requests to /foo with -the POST method and a secure connection:: - - $route = new Route( - '/foo', - array(), - array('_method' => 'post', '_scheme' => 'https' ) - ); - .. tip:: If you want to match all urls which start with a certain path and end in an @@ -150,8 +142,7 @@ Using Prefixes You can add routes or other instances of :class:`Symfony\\Component\\Routing\\RouteCollection` to *another* collection. This way you can build a tree of routes. Additionally you can define a prefix, -default requirements, default options, and hostname pattern to all routes -of a subtree:: +default requirements, default options and hostname to all routes of a subtree:: $rootCollection = new RouteCollection(); @@ -162,10 +153,10 @@ of a subtree:: $rootCollection->addCollection( $subCollection, '/prefix', // prefix - array('_scheme' => 'https'), // defaults array(), // requirements array(), // options 'admin.example.com', // hostname + array('https') // schemes ); Set the Request Parameters @@ -220,9 +211,9 @@ a certain route:: .. note:: - If you have defined the ``_scheme`` requirement, an absolute URL is generated - if the scheme of the current :class:`Symfony\\Component\\Routing\\RequestContext` - does not match the requirement. + If you have defined a scheme, an absolute URL is generated if the scheme + of the current :class:`Symfony\\Component\\Routing\\RequestContext` does + not match the requirement. Load Routes from a File ~~~~~~~~~~~~~~~~~~~~~~~ @@ -244,11 +235,11 @@ If you're using the ``YamlFileLoader``, then route definitions look like this: # routes.yml route1: - pattern: /foo + path: /foo defaults: { _controller: 'MyController::fooAction' } route2: - pattern: /foo/bar + path: /foo/bar defaults: { _controller: 'MyController::foobarAction' } To load this file, you can use the following code. This assumes that your diff --git a/cookbook/routing/method_parameters.rst b/cookbook/routing/method_parameters.rst index 26a614a121f..6499c7e79ff 100644 --- a/cookbook/routing/method_parameters.rst +++ b/cookbook/routing/method_parameters.rst @@ -1,37 +1,34 @@ .. index:: - single: Routing; _method + single: Routing; methods How to use HTTP Methods beyond GET and POST in Routes ===================================================== The HTTP method of a request is one of the requirements that can be checked when seeing if it matches a route. This is introduced in the routing chapter -of the book ":doc:`/book/routing`" with examples using GET and POST. You -can also use other HTTP verbs in this way. For example, if you have a blog -post entry then you could use the same URL pattern to show it, make changes -to it and delete it by matching on GET, PUT and DELETE. +of the book ":doc:`/book/routing`" with examples using GET and POST. You can +also use other HTTP verbs in this way. For example, if you have a blog post +entry then you could use the same URL path to show it, make changes to it and +delete it by matching on GET, PUT and DELETE. .. configuration-block:: .. code-block:: yaml blog_show: - pattern: /blog/{slug} + path: /blog/{slug} defaults: { _controller: AcmeDemoBundle:Blog:show } - requirements: - _method: GET + methods: [GET] blog_update: - pattern: /blog/{slug} + path: /blog/{slug} defaults: { _controller: AcmeDemoBundle:Blog:update } - requirements: - _method: PUT + methods: [PUT] blog_delete: - pattern: /blog/{slug} + path: /blog/{slug} defaults: { _controller: AcmeDemoBundle:Blog:delete } - requirements: - _method: DELETE + methods: [DELETE] .. code-block:: xml @@ -41,19 +38,16 @@ to it and delete it by matching on GET, PUT and DELETE. xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd"> - + AcmeDemoBundle:Blog:show - GET - + AcmeDemoBundle:Blog:update - PUT - + AcmeDemoBundle:Blog:delete - DELETE @@ -65,21 +59,15 @@ to it and delete it by matching on GET, PUT and DELETE. $collection = new RouteCollection(); $collection->add('blog_show', new Route('/blog/{slug}', array( '_controller' => 'AcmeDemoBundle:Blog:show', - ), array( - '_method' => 'GET', - ))); + ), array(), array(), '', array(), array('GET'))); $collection->add('blog_update', new Route('/blog/{slug}', array( '_controller' => 'AcmeDemoBundle:Blog:update', - ), array( - '_method' => 'PUT', - ))); + ), array(), array(), '', array(), array('PUT'))); $collection->add('blog_delete', new Route('/blog/{slug}', array( '_controller' => 'AcmeDemoBundle:Blog:delete', - ), array( - '_method' => 'DELETE', - ))); + ), array(), array(), '', array('DELETE'))); return $collection; diff --git a/cookbook/routing/redirect_in_config.rst b/cookbook/routing/redirect_in_config.rst index 8b0945a0a06..4d6b7004e6e 100644 --- a/cookbook/routing/redirect_in_config.rst +++ b/cookbook/routing/redirect_in_config.rst @@ -20,7 +20,7 @@ Your configuration will look like this: prefix: /app root: - pattern: / + path: / defaults: _controller: FrameworkBundle:Redirect:urlRedirect path: /app @@ -37,4 +37,4 @@ for redirecting request: parameter with the *name* of the route you want to redirect to. The ``permanent`` switch tells both methods to issue a 301 HTTP status code -instead of the default ``302`` status code. \ No newline at end of file +instead of the default ``302`` status code. diff --git a/cookbook/routing/scheme.rst b/cookbook/routing/scheme.rst index ea4d3dfb90d..9786f7a0a27 100644 --- a/cookbook/routing/scheme.rst +++ b/cookbook/routing/scheme.rst @@ -6,17 +6,16 @@ How to force routes to always use HTTPS or HTTP Sometimes, you want to secure some routes and be sure that they are always accessed via the HTTPS protocol. The Routing component allows you to enforce -the URI scheme via the ``_scheme`` requirement: +the URI scheme via schemes: .. configuration-block:: .. code-block:: yaml secure: - pattern: /secure + path: /secure defaults: { _controller: AcmeDemoBundle:Main:secure } - requirements: - _scheme: https + schemes: [https] .. code-block:: xml @@ -26,9 +25,8 @@ the URI scheme via the ``_scheme`` requirement: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd"> - + AcmeDemoBundle:Main:secure - https @@ -40,9 +38,7 @@ the URI scheme via the ``_scheme`` requirement: $collection = new RouteCollection(); $collection->add('secure', new Route('/secure', array( '_controller' => 'AcmeDemoBundle:Main:secure', - ), array( - '_scheme' => 'https', - ))); + ), array(), array(), '', array('https'))); return $collection; @@ -65,8 +61,8 @@ The requirement is also enforced for incoming requests. If you try to access the ``/secure`` path with HTTP, you will automatically be redirected to the same URL, but with the HTTPS scheme. -The above example uses ``https`` for the ``_scheme``, but you can also force a -URL to always use ``http``. +The above example uses ``https`` for the scheme, but you can also force a URL +to always use ``http``. .. note:: diff --git a/cookbook/routing/service_container_parameters.rst b/cookbook/routing/service_container_parameters.rst index 37c855c588d..8b6d100e264 100644 --- a/cookbook/routing/service_container_parameters.rst +++ b/cookbook/routing/service_container_parameters.rst @@ -22,7 +22,7 @@ inside your routing configuration: .. code-block:: yaml contact: - pattern: /{_locale}/contact + path: /{_locale}/contact defaults: { _controller: AcmeDemoBundle:Main:contact } requirements: _locale: %acme_demo.locales% @@ -35,7 +35,7 @@ inside your routing configuration: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd"> - + AcmeDemoBundle:Main:contact %acme_demo.locales% @@ -78,15 +78,15 @@ in your container: # app/config/config.php $container->setParameter('acme_demo.locales', 'en|es'); -You can also use a parameter to define your route pattern (or part of your -pattern): +You can also use a parameter to define your route path (or part of your +path): .. configuration-block:: .. code-block:: yaml some_route: - pattern: /%acme_demo.route_prefix%/contact + path: /%acme_demo.route_prefix%/contact defaults: { _controller: AcmeDemoBundle:Main:contact } .. code-block:: xml @@ -97,7 +97,7 @@ pattern): xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd"> - + AcmeDemoBundle:Main:contact @@ -118,4 +118,4 @@ pattern): Just like in normal service container configuration files, if you actually need a ``%`` in your route, you can escape the percent sign by doubling - it, e.g. ``/score-50%%``, which would resolve to ``/score-50%``. \ No newline at end of file + it, e.g. ``/score-50%%``, which would resolve to ``/score-50%``. diff --git a/cookbook/routing/slash_in_parameter.rst b/cookbook/routing/slash_in_parameter.rst index 0c371f5e7ff..cc1532c16ee 100644 --- a/cookbook/routing/slash_in_parameter.rst +++ b/cookbook/routing/slash_in_parameter.rst @@ -16,18 +16,18 @@ Configure the Route ------------------- By default, the Symfony routing components requires that the parameters -match the following regex pattern: ``[^/]+``. This means that all characters +match the following regex path: ``[^/]+``. This means that all characters are allowed except ``/``. You must explicitly allow ``/`` to be part of your parameter by specifying -a more permissive regex pattern. +a more permissive regex path. .. configuration-block:: .. code-block:: yaml _hello: - pattern: /hello/{name} + path: /hello/{name} defaults: { _controller: AcmeDemoBundle:Demo:hello } requirements: name: ".+" @@ -40,7 +40,7 @@ a more permissive regex pattern. xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd"> - + AcmeDemoBundle:Demo:hello .+ @@ -75,4 +75,4 @@ a more permissive regex pattern. } } -That's it! Now, the ``{name}`` parameter can contain the ``/`` character. \ No newline at end of file +That's it! Now, the ``{name}`` parameter can contain the ``/`` character. From 38e8dad6bcc86a5f6bb88dac7d6cc9ea0d7d9461 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Mon, 21 Jan 2013 14:19:05 +0100 Subject: [PATCH 2/5] Added use of addPrefix to define prefixes --- components/routing/introduction.rst | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/components/routing/introduction.rst b/components/routing/introduction.rst index 39cdad0d975..49e9b56b244 100644 --- a/components/routing/introduction.rst +++ b/components/routing/introduction.rst @@ -142,16 +142,16 @@ Using Prefixes You can add routes or other instances of :class:`Symfony\\Component\\Routing\\RouteCollection` to *another* collection. This way you can build a tree of routes. Additionally you can define a prefix, -default requirements, default options and hostname to all routes of a subtree:: +default requirements, default options and hostname to all routes of a subtree +with the :method:`Symfony\\Component\\Routing\\RouteCollection::addPrefix` +method:: $rootCollection = new RouteCollection(); $subCollection = new RouteCollection(); $subCollection->add(...); $subCollection->add(...); - - $rootCollection->addCollection( - $subCollection, + $subCollection->addPrefix( '/prefix', // prefix array(), // requirements array(), // options @@ -159,6 +159,12 @@ default requirements, default options and hostname to all routes of a subtree:: array('https') // schemes ); + $rootCollection->addCollection($subCollection); + +.. versionadded:: 2.2 + The ``addPrefixs`` method is added in Symfony2.2. This was part of the + ``addCollection`` method in older versions. + Set the Request Parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~ From 75d6b4dd062e3790b980f3beb25d05637b9a264d Mon Sep 17 00:00:00 2001 From: WouterJ Date: Mon, 21 Jan 2013 14:22:33 +0100 Subject: [PATCH 3/5] Addes some versionadded blocks --- book/routing.rst | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/book/routing.rst b/book/routing.rst index d13d6118756..f0b5e77bc39 100644 --- a/book/routing.rst +++ b/book/routing.rst @@ -67,6 +67,10 @@ The route is simple: return $collection; +.. versionadded:: 2.2 + The ``path`` option is new in Symfony2.2, ``pattern`` is used in older + versions. + The path defined by the ``blog_show`` route acts like ``/blog/*`` where the wildcard is given the name ``slug``. For the URL ``/blog/my-blog-post``, the ``slug`` variable gets a value of ``my-blog-post``, which is available @@ -677,6 +681,10 @@ be accomplished with the following route configuration: return $collection; +.. versionadded:: + The ``methods`` option is added in Symfony2.2. Use the ``_method`` + requirement in older versions. + Despite the fact that these two routes have identical paths (``/contact``), the first route will match only GET requests and the second route will match only POST requests. This means that you can display the form and submit the @@ -686,8 +694,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 Hostname Pattern -~~~~~~~~~~~~~~~~~~~~~~~~~ +Adding a Hostname +~~~~~~~~~~~~~~~~~ .. versionadded:: 2.2 Hostname matching support was added in Symfony 2.2 From 0de81943335e49df960e80acf8de595d012f6756 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Mon, 21 Jan 2013 22:22:51 +0100 Subject: [PATCH 4/5] Changed hostname to host --- book/routing.rst | 18 +++++++------- components/routing/hostname_pattern.rst | 32 ++++++++++++------------- components/routing/introduction.rst | 13 +++++----- 3 files changed, 31 insertions(+), 32 deletions(-) diff --git a/book/routing.rst b/book/routing.rst index f0b5e77bc39..d7052b53a39 100644 --- a/book/routing.rst +++ b/book/routing.rst @@ -694,13 +694,13 @@ 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 Hostname -~~~~~~~~~~~~~~~~~ +Adding a Host +~~~~~~~~~~~~~ .. versionadded:: 2.2 - Hostname matching support was added in Symfony 2.2 + Host matching support was added in Symfony 2.2 -You can also match on the HTTP *hostname* of the incoming request. For more +You can also match on the HTTP *host* of the incoming request. For more information, see :doc:`/components/routing/hostname_pattern` in the Routing component documentation. @@ -1038,14 +1038,14 @@ from the new routing resource. :doc:`FrameworkExtraBundle documentation` to see how. -Adding a Hostname Pattern to Imported Routes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Adding a Host regex to Imported Routes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. versionadded:: 2.2 - Hostname matching support was added in Symfony 2.2 + Host matching support was added in Symfony 2.2 -You can set the hostname on imported routes. For more information, see -:ref:`component-routing-hostname-imported`. +You can set the host regex on imported routes. For more information, see +:ref:`component-routing-host-imported`. .. index:: single: Routing; Debugging diff --git a/components/routing/hostname_pattern.rst b/components/routing/hostname_pattern.rst index 488b000373e..38bc0f143eb 100644 --- a/components/routing/hostname_pattern.rst +++ b/components/routing/hostname_pattern.rst @@ -1,13 +1,13 @@ .. index:: single: Routing; Matching on Hostname -How to match a route based on the Hostname -========================================== +How to match a route based on the Host +====================================== .. versionadded:: 2.2 - Hostname matching support was added in Symfony 2.2 + Host matching support was added in Symfony 2.2 -You can also match on the HTTP *hostname* of the incoming request. +You can also match on the HTTP *host* of the incoming request. .. configuration-block:: @@ -15,7 +15,7 @@ You can also match on the HTTP *hostname* of the incoming request. mobile_homepage: path: / - hostname: m.example.com + host: m.example.com defaults: { _controller: AcmeDemoBundle:Main:mobileHomepage } homepage: @@ -32,7 +32,7 @@ You can also match on the HTTP *hostname* of the incoming request. http://symfony.com/schema/routing/routing-1.0.xsd" > - + AcmeDemoBundle:Main:mobileHomepage @@ -58,7 +58,7 @@ You can also match on the HTTP *hostname* of the incoming request. return $collection; Both routes match the same path ``/``, however the first one will match -only if the hostname is ``m.example.com``. +only if the host is ``m.example.com``. Placeholders and Requirements in Hostname Patterns -------------------------------------------------- @@ -78,7 +78,7 @@ dependency injection container parameter. mobile_homepage: path: / - hostname: m.{domain} + host: m.{domain} defaults: { _controller: AcmeDemoBundle:Main:mobileHomepage } requirements: domain: %domain% @@ -95,7 +95,7 @@ dependency injection container parameter. xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd"> - + AcmeDemoBundle:Main:mobileHomepage %domain% @@ -123,12 +123,12 @@ dependency injection container parameter. return $collection; -.. _component-routing-hostname-imported: +.. _component-routing-host-imported: -Adding a Hostname Pattern to Imported Routes +Adding a Host Regex to Imported Routes -------------------------------------------- -You can set a hostname on imported routes: +You can set a host regex on imported routes: .. configuration-block:: @@ -137,7 +137,7 @@ You can set a hostname on imported routes: # app/config/routing.yml acme_hello: resource: "@AcmeHelloBundle/Resources/config/routing.yml" - hostname: "hello.example.com" + host: "hello.example.com" .. code-block:: xml @@ -148,7 +148,7 @@ You can set a hostname on imported routes: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd"> - + .. code-block:: php @@ -161,5 +161,5 @@ You can set a hostname on imported routes: return $collection; -The hostname ``hello.example.com`` will be set on each route loaded from the -new routing resource. +The host ``hello.example.com`` will be set on each route loaded from the new +routing resource. diff --git a/components/routing/introduction.rst b/components/routing/introduction.rst index 49e9b56b244..19ad9f19536 100644 --- a/components/routing/introduction.rst +++ b/components/routing/introduction.rst @@ -85,7 +85,7 @@ placeholders as regular expressions. 4. An array of options. These contain internal settings for the route and are the least commonly needed. -5. A hostname. This is matched against the hostname of the request. See +5. A host. This is matched against the host of the request. See :doc:`/components/routing/hostname_pattern` for more details. 6. An array of schemes. These enforce a certain HTTP scheme (``http``, ``https``). @@ -94,7 +94,7 @@ are the least commonly needed. ``GET``, ``POST``, ...). .. versionadded:: 2.2 - The hostname was added in Symfony 2.2 + Host matching support was added in Symfony 2.2 Take the following route, which combines several of these ideas:: @@ -103,7 +103,7 @@ Take the following route, which combines several of these ideas:: array('controller' => 'showArchive'), // default values array('month' => '[0-9]{4}-[0-9]{2}', 'subdomain' => 'www|m'), // requirements array(), // options - '{subdomain}.example.com', // hostname + '{subdomain}.example.com', // host array(), // schemes array() // methods ); @@ -142,9 +142,8 @@ Using Prefixes You can add routes or other instances of :class:`Symfony\\Component\\Routing\\RouteCollection` to *another* collection. This way you can build a tree of routes. Additionally you can define a prefix, -default requirements, default options and hostname to all routes of a subtree -with the :method:`Symfony\\Component\\Routing\\RouteCollection::addPrefix` -method:: +default requirements, default options and host to all routes of a subtree with +the :method:`Symfony\\Component\\Routing\\RouteCollection::addPrefix` method:: $rootCollection = new RouteCollection(); @@ -155,7 +154,7 @@ method:: '/prefix', // prefix array(), // requirements array(), // options - 'admin.example.com', // hostname + 'admin.example.com', // host array('https') // schemes ); From 4e5cca24b3b35c74185e50baea76db6070d79a30 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Mon, 21 Jan 2013 22:27:11 +0100 Subject: [PATCH 5/5] Fixed typo, thanks to @stof --- components/routing/introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/routing/introduction.rst b/components/routing/introduction.rst index 19ad9f19536..b48f0be9172 100644 --- a/components/routing/introduction.rst +++ b/components/routing/introduction.rst @@ -161,7 +161,7 @@ the :method:`Symfony\\Component\\Routing\\RouteCollection::addPrefix` method:: $rootCollection->addCollection($subCollection); .. versionadded:: 2.2 - The ``addPrefixs`` method is added in Symfony2.2. This was part of the + The ``addPrefix`` method is added in Symfony2.2. This was part of the ``addCollection`` method in older versions. Set the Request Parameters