Skip to content

Update routing.rst #4760

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

Merged
merged 1 commit into from
Jan 8, 2015
Merged

Update routing.rst #4760

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
43 changes: 29 additions & 14 deletions book/routing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -177,8 +177,10 @@ file:
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

<framework:config>
<!-- ... -->
Expand Down Expand Up @@ -652,7 +654,9 @@ requirements can easily be added for each parameter. For example:
// ...

/**
* @Route("/blog/{page}", defaults={"page": 1}, requirements={"page": "\d+"})
* @Route("/blog/{page}", defaults={"page": 1}, requirements={
* "page": "\d+"
* })
*/
public function indexAction($page)
{
Expand Down Expand Up @@ -740,7 +744,9 @@ URL:
class MainController extends Controller
{
/**
* @Route("/{_locale}", defaults={"_locale": "en"}, requirements={"_locale": "en|fr"})
* @Route("/{_locale}", defaults={"_locale": "en"}, requirements={
* "_locale": "en|fr"
* })
*/
public function homepageAction($_locale)
{
Expand Down Expand Up @@ -939,8 +945,12 @@ routing system can be:
/**
* @Route(
* "/articles/{_locale}/{year}/{title}.{_format}",
* defaults: {"_format": "html"}
* requirements: {"_locale": "en|fr", "_format": "html|rss", "year": "\d+"}
* defaults: {"_format": "html"},
* requirements: {
* "_locale": "en|fr",
* "_format": "html|rss",
* "year": "\d+"
* }
* )
*/
public function showAction($_locale, $year, $title)
Expand Down Expand Up @@ -1017,7 +1027,7 @@ a slash. URLs matching this route might look like:
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 such as setting the ``Content-Type`` of the response (e.g. a ``json``
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
Expand Down Expand Up @@ -1109,7 +1119,7 @@ each is made available as an argument to the controller method::

public function showAction($slug)
{
// ...
// ...
}

In reality, the entire ``defaults`` collection is merged with the parameter
Expand Down Expand Up @@ -1184,8 +1194,8 @@ configuration:

$collection = new RouteCollection();
$collection->addCollection(
// second argument is the type, which is required to enable the annotation reader
// for this resource
// second argument is the type, which is required to enable
// the annotation reader for this resource
$loader->import("@AppBundle/Controller/", "annotation")
);

Expand Down Expand Up @@ -1275,7 +1285,7 @@ suppose you want to prefix all routes in the AppBundle with ``/site`` (e.g.
// app/config/routing.php
use Symfony\Component\Routing\RouteCollection;

$app = $loader->import('@AppBundle/Controller/');
$app = $loader->import('@AppBundle/Controller/', 'annotation');
$app->addPrefix('/site');

$collection = new RouteCollection();
Expand Down Expand Up @@ -1361,7 +1371,9 @@ system. Take the ``blog_show`` example route from earlier::
// '_controller' => 'AppBundle:Blog:show',
// )

$uri = $this->get('router')->generate('blog_show', array('slug' => 'my-blog-post'));
$uri = $this->get('router')->generate('blog_show', array(
'slug' => 'my-blog-post'
));
// /blog/my-blog-post

To generate a URL, you need to specify the name of the route (e.g. ``blog_show``)
Expand Down Expand Up @@ -1429,7 +1441,10 @@ Generating URLs with Query Strings
The ``generate`` method takes an array of wildcard values to generate the URI.
But if you pass extra ones, they will be added to the URI as a query string::

$this->get('router')->generate('blog', array('page' => 2, 'category' => 'Symfony'));
$this->get('router')->generate('blog', array(
'page' => 2,
'category' => 'Symfony'
Copy link
Member

Choose a reason for hiding this comment

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

A quick question: do we add a trailing comma for the last array element in the docs ... or do we only add it in code?

Copy link
Member

Choose a reason for hiding this comment

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

Usually we follow this rule in the docs too.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Crap, missed the comma, losing my sharpness I guess :D

Yea, usually docs have the trailing comma and as contribution docs has a section about having trailing comma, in my opinion it's a good idea to follow that rule in docs also.

));
// /blog/2?category=Symfony

Generating URLs from a Template
Expand Down Expand Up @@ -1470,7 +1485,7 @@ method::

From a template, in Twig, simply use the ``url()`` function (which generates an absolute URL)
rather than the ``path()`` function (which generates a relative URL). In PHP, pass ``true``
to ``generateUrl()``:
to ``generate()``:

.. configuration-block::

Expand Down