Skip to content

[book] routing ch review, part 2 #6355

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

[book] routing ch review, part 2 #6355

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
872ef18
routing ch review, part 2
talitakz Mar 12, 2016
cb54778
changes according to comments after PR
talitakz Mar 18, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
155 changes: 92 additions & 63 deletions book/routing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -549,10 +549,11 @@ URL Route Parameters

.. _book-routing-requirements:

Adding Requirements
~~~~~~~~~~~~~~~~~~~
Route Requirements
~~~~~~~~~~~~~~~~~~
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This makes sense, but you'll need to add a manual link above it, so that existing links to this section (i.e. #adding-requirements don't suddenly break:

.. adding-requirements:

Route Requirements


Take a quick look at the routes that have been created so far:
Take a quick look at both routes that have been created so far for our
imaginary blog::
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we need to add more to this sentence - it also uses the "first-person" "our" :/


.. configuration-block::

Expand All @@ -564,15 +565,15 @@ Take a quick look at the routes that have been created so far:
class BlogController extends Controller
{
/**
* @Route("/blog/{page}", defaults={"page" = 1})
* @Route("/blog/{page}", name="blog", defaults={"page" = 1})
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

don't use a name here

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, I see you reference it below - so we can keep it - by how about blog_list to be a little less generic sounding?

*/
public function indexAction($page)
{
// ...
}

/**
* @Route("/blog/{slug}")
* @Route("/blog/{slug}", name="blog_show")
*/
public function showAction($slug)
{
Expand Down Expand Up @@ -629,11 +630,11 @@ 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
URLs that look like ``/blog/*``. The Symfony router will always choose the
**first** matching route it finds. In other words, the ``blog_show`` route
URLs 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
the first route (``blog``) and return a nonsense value of ``my-blog-post``
to the ``{page}`` parameter.
the first route named ``blog`` and the variable ``$page`` will get a nonsense
value of ``my-blog-post``.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nice explanation


====================== ======== ===============================
URL Route Parameters
Expand All @@ -645,7 +646,7 @@ URL Route Parameters
The answer to the problem is to add route *requirements*. The routes in this
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:
requirements can easily be added for each parameter. For example::

.. configuration-block::

Expand All @@ -656,8 +657,10 @@ requirements can easily be added for each parameter. For example:
// ...

/**
* @Route("/blog/{page}", defaults={"page": 1}, requirements={
* "page": "\d+"
* @Route("/blog/{page}", name="blog",
* defaults={"page": 1},
* requirements={
* "page": "\d+"
* })
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we're going to do this, why not move name onto the next line too? And now, the final } should be on the line above, not on the same line as the )

*/
public function indexAction($page)
Expand Down Expand Up @@ -723,13 +726,14 @@ URL Route Parameters
``/blog/2-my-blog-post`` ``blog_show`` ``{slug}`` = ``2-my-blog-post``
======================== ============= ===============================

.. sidebar:: Earlier Routes always Win
.. caution:: Earlier Routes always Win

What this all means is that the order of the routes is very important.
If the ``blog_show`` route were placed above the ``blog`` route, the
URL ``/blog/2`` would match ``blog_show`` instead of ``blog`` since the
``{slug}`` parameter of ``blog_show`` has no requirements. By using proper
ordering and clever requirements, you can accomplish just about anything.
What this all means is that the **order of the routes is very
important**. If the ``blog_show`` route were placed above the
``blog`` route, the URL ``/blog/2`` would match ``blog_show``
instead of ``blog`` since the ``{slug}`` placeholder of
``blog_show`` has no requirements. By using proper ordering and
clever requirements, you can accomplish just about anything.

Since the parameter requirements are regular expressions, the complexity
and flexibility of each requirement is entirely up to you. Suppose the homepage
Expand All @@ -746,12 +750,15 @@ URL:
class MainController extends Controller
{
/**
* @Route("/{_locale}", defaults={"_locale": "en"}, requirements={
* "_locale": "en|fr"
* @Route("/{_locale}", name="homepage",
* defaults={"_locale": "en"},
* requirements={
* "_locale": "en|fr"
* })
*/
public function homepageAction($_locale)
{
// ...
}
}

Expand Down Expand Up @@ -811,14 +818,21 @@ Path Parameters
.. index::
single: Routing; Method requirement

Adding HTTP Method Requirements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
HTTP Method Requirements
~~~~~~~~~~~~~~~~~~~~~~~~
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's keep this - it doesn't hurt, and we won't have to add a manual anchor to not break the links


In addition to the URL, you can also match on the *method* of the incoming
request (i.e. GET, HEAD, POST, PUT, DELETE). Suppose you create an API for
your blog and you have 2 routes: One for displaying a post (on a GET or HEAD
request) and one for updating a post (on a PUT request). This can be
accomplished with the following route configuration:
request (i.e. GET, HEAD, POST, PUT, DELETE) using ``@Method`` annotation
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

using the @Method annotation or the methods array in YAML.

or ``methods`` array in YAML.

.. versionadded:: 2.2
The ``methods`` option was introduced in Symfony 2.2. Use the ``_method``
requirement in older versions.

Suppose you create an API for your blog and you have 2 routes: one for
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suppose you're creating an API...

displaying a post (on a GET or HEAD request) and one for updating a post
(on a PUT request). This can be accomplished with the following route
configuration::

.. configuration-block::

Expand All @@ -833,7 +847,7 @@ accomplished with the following route configuration:
class BlogApiController extends Controller
{
/**
* @Route("/api/posts/{id}")
* @Route("/api/posts/{id}", name="api_post_show")
* @Method({"GET","HEAD"})
*/
public function showAction($id)
Expand All @@ -842,7 +856,7 @@ accomplished with the following route configuration:
}

/**
* @Route("/api/posts/{id}")
* @Route("/api/posts/{id}", name="api_post_edit")
* @Method("PUT")
*/
public function editAction($id)
Expand Down Expand Up @@ -899,22 +913,27 @@ accomplished with the following route configuration:

return $collection;

.. versionadded:: 2.2
The ``methods`` option was introduced in Symfony 2.2. Use the ``_method``
requirement in older versions.

Despite the fact that these two routes have identical paths
(``/api/posts/{id}``), the first route will match only GET or HEAD requests and
the second route will match only PUT requests. This means that you can display
and edit the post with the same URL, while using distinct controllers for the
two actions.
(``/api/posts/{id}``), the first route will match only GET or HEAD
requests and the second route will match only PUT requests. This means
that you can display and edit the post with the same URL, while using
distinct controllers for the two actions.

.. note::

If no ``methods`` are specified, the route will match on *all* methods.
If no ``@Method`` or ``methods`` parameter is specified, the route
will match on *all* methods.

Adding a Host Requirement
~~~~~~~~~~~~~~~~~~~~~~~~~
.. seealso::

Unfortunately, life isn't quite this simple, since most browsers do not
support sending all method attributes in an HTML form. Fortunately,
Symfony provides you with a simple way of working around this limitation.
To learn about it read cookbook article
:doc:`/cookbook/routing/method_parameters`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would say something like:

Most browsers only support GET and POST requests. To build a form that uses a different
HTTP method (e.g. PUT), see .


Host Requirement
~~~~~~~~~~~~~~~~
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as above - let's not change this


.. versionadded:: 2.2
Host matching support was introduced in Symfony 2.2
Expand All @@ -934,7 +953,7 @@ Advanced Routing Example

At this point, you have everything you need to create a powerful routing
structure in Symfony. The following is an example of just how flexible the
routing system can be:
routing system can be::

.. configuration-block::

Expand All @@ -948,6 +967,7 @@ routing system can be:
/**
* @Route(
* "/articles/{_locale}/{year}/{title}.{_format}",
* name="article_show",
* defaults={"_format": "html"},
* requirements={
* "_locale": "en|fr",
Expand All @@ -958,6 +978,7 @@ routing system can be:
*/
public function showAction($_locale, $year, $title)
{
// ...
}
}

Expand Down Expand Up @@ -1014,10 +1035,13 @@ routing system can be:

return $collection;

As you've seen, this route will only match if the ``{_locale}`` portion of
the URL is either ``en`` or ``fr`` and if the ``{year}`` is a number. This
route also shows how you can use a dot between placeholders instead of
a slash. URLs matching this route might look like:
The route named ``article_show`` will only match if the ``{_locale}``
portion of the URL is either ``en`` or ``fr``, if the ``{year}`` is
a number and if the ``{_format}`` portion of the URL is either ``html``
or ``rss``. We can also notice how the **dot can be used between
placeholders** instead of a slash.

URLs matching this route might look like:

* ``/articles/en/2010/my-post``
* ``/articles/fr/2010/my-post.rss``
Expand All @@ -1027,28 +1051,33 @@ a slash. URLs matching this route might look like:

.. sidebar:: The Special ``_format`` Routing Parameter

This example also highlights the special ``_format`` routing parameter.
When using this parameter, the matched value becomes the "request format"
of the ``Request`` object.

Ultimately, the request format is used for such things as setting the
``Content-Type`` of the response (e.g. a ``json`` request format translates
into a ``Content-Type`` of ``application/json``). It can also be used in the
controller to render a different template for each value of ``_format``.
The ``_format`` parameter is a very powerful way to render the same content
in different formats.

In Symfony versions previous to 3.0, it is possible to override the request
format by adding a query parameter named ``_format`` (for example:
``/foo/bar?_format=json``). Relying on this behavior not only is considered
a bad practice but it will complicate the upgrade of your applications to
Symfony 3.
This example also highlights the special ``_format`` routing
parameter. When using this parameter, the matched value becomes the
"request format" of the ``Request`` object which is ultimately used
for such things as setting the ``Content-Type`` of the response (e.g.
a ``json`` request format translates into a ``Content-Type`` of
``application/json``).

As like any regular route placeholder special ``_format`` routing
parameter is also accessible as arguments to your controller and therefore
available inside the controller where it can be used to render a different
template for each value of ``_format``. So, the ``_format`` parameter is a
very powerful way to render the same content in different formats.

In Symfony versions previous to 3.0, it is possible to override the
request format by adding a query parameter named ``_format`` (for
example: ``/foo/bar?_format=json``). Relying on this behavior not
only is considered a bad practice but it will complicate the upgrade
of your applications to Symfony 3.

.. note::

Sometimes you want to make certain parts of your routes globally configurable.
Symfony provides you with a way to do this by leveraging service container
parameters. Read more about this in ":doc:`/cookbook/routing/service_container_parameters`".
Sometimes you want to make certain parts of your routes globally
configurable. Symfony provides you with a way to do this by
leveraging service container parameters. Read more about this in the
cookbook article :doc:`/cookbook/routing/service_container_parameters`.

.. _book-special-routing-parameters:

Special Routing Parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down