Use path() and url() PHP templating helpers

Author: wouterj

Diff for: book/forms.rst

@@ -1036,7 +1036,9 @@ to the ``form()`` or the ``form_start()`` helper:
 
         <!-- app/Resources/views/default/newAction.html.php -->
         <?php echo $view['form']->start($form, array(
-            'action' => $view['router']->generate('target_route'),
+            // The path() method was introduced in Symfony 2.8. Prior to 2.8,
+            // you had to use generate().
+            'action' => $view['router']->path('target_route'),
             'method' => 'GET',
         )) ?>
 

Diff for: book/from_flat_php_to_symfony2.rst

@@ -598,7 +598,7 @@ database and the Templating component to render a template and return a
     <ul>
         <?php foreach ($posts as $post): ?>
         <li>
-            <a href="<?php echo $view['router']->generate(
+            <a href="<?php echo $view['router']->path(
                 'blog_show',
                 array('id' => $post->getId())
             ) ?>">

Diff for: book/http_cache.rst

@@ -1087,23 +1087,22 @@ matter), Symfony uses the standard ``render`` helper to configure ESI tags:
 
         <!-- app/Resources/views/static/about.html.php -->
 
-        // you can use a controller reference
-        use Symfony\Component\HttpKernel\Controller\ControllerReference;
+        <!-- you can use a controller reference -->
         <?php echo $view['actions']->render(
-            new ControllerReference(
+            new \Symfony\Component\HttpKernel\Controller\ControllerReference(
                 'AppBundle:News:latest',
                 array('maxPerPage' => 5)
             ),
             array('strategy' => 'esi')
         ) ?>
 
-        // ... or a URL
-        use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
+        <!-- ... or a URL -->
         <?php echo $view['actions']->render(
-            $view['router']->generate(
+            // The url() method was introduced in Symfony 2.8. Prior to 2.8,
+            // you had to use generate($name, $parameters, UrlGeneratorInterface::ABSOLUTE_URL)
+            $view['router']->url(
                 'latest_news',
                 array('maxPerPage' => 5),
-                UrlGeneratorInterface::ABSOLUTE_URL
             ),
             array('strategy' => 'esi'),
         ) ?>

Diff for: book/routing.rst

@@ -1531,12 +1531,16 @@ a template helper function:
 
     .. code-block:: html+php
 
-        <a href="<?php echo $view['router']->generate('blog_show', array(
+        <a href="<?php echo $view['router']->path('blog_show', array(
             'slug' => 'my-blog-post',
         )) ?>">
             Read this blog post.
         </a>
 
+.. versionadded:: 2.8
+    The ``path()`` PHP templating helper was introduced in Symfony 2.8. Prior
+    to 2.8, you had to use the ``generate()`` helper method.
+
 .. index::
    single: Routing; Absolute URLs
 
@@ -1550,9 +1554,8 @@ method::
     $this->generateUrl('blog_show', array('slug' => 'my-blog-post'), true);
     // http://www.example.com/blog/my-blog-post
 
-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 ``generate()``:
+From a template, simply use the ``url()`` function (which generates an absolute
+URL) rather than the ``path()`` function (which generates a relative URL):
 
 .. configuration-block::
 
@@ -1564,16 +1567,18 @@ to ``generate()``:
 
     .. code-block:: html+php
 
-        <?php
-        use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
-        ?>
-
-        <a href="<?php echo $view['router']->generate('blog_show', array(
+        <a href="<?php echo $view['router']->url('blog_show', array(
             'slug' => 'my-blog-post',
-        ), UrlGeneratorInterface::ABSOLUTE_URL) ?>">
+        )) ?>">
             Read this blog post.
         </a>
 
+.. versionadded:: 2.8
+    The ``url()`` PHP templating helper was introduced in Symfony 2.8. Prior
+    to 2.8, you had to use the ``generate()`` helper method with
+    ``Symfony\Component\Routing\Generator\UrlGeneratorInterface::ABSOLUTE_URL``
+    passed as third argument.
+
 .. note::
 
     The host that's used when generating an absolute URL is automatically

Diff for: book/templating.rst

@@ -709,8 +709,11 @@ tags:
             array('renderer' => 'hinclude')
         ) ?>
 
+        <!-- The url() method was introduced in Symfony 2.8. Prior to 2.8, you
+             had to use generate() with UrlGeneratorInterface::ABSOLUTE_URL
+             passed as third argument. -->
         <?php echo $view['actions']->render(
-            $view['router']->generate('...'),
+            $view['router']->url('...'),
             array('renderer' => 'hinclude')
         ) ?>
 
@@ -918,7 +921,9 @@ To link to the page, just use the ``path`` Twig function and refer to the route:
 
     .. code-block:: html+php
 
-        <a href="<?php echo $view['router']->generate('_welcome') ?>">Home</a>
+        <!-- The path() method was introduced in Symfony 2.8. Prior to 2.8, you
+             had to use generate(). -->
+        <a href="<?php echo $view['router']->path('_welcome') ?>">Home</a>
 
 As expected, this will generate the URL ``/``. Now, for a more complicated
 route:
@@ -997,7 +1002,9 @@ correctly:
 
         <!-- app/Resources/views/Article/recent_list.html.php -->
         <?php foreach ($articles in $article): ?>
-            <a href="<?php echo $view['router']->generate('article_show', array(
+            <!-- The path() method was introduced in Symfony 2.8. Prior to 2.8,
+                 you had to use generate(). -->
+            <a href="<?php echo $view['router']->path('article_show', array(
                 'slug' => $article->getSlug(),
             )) ?>">
                 <?php echo $article->getTitle() ?>
@@ -1006,26 +1013,26 @@ correctly:
 
 .. tip::
 
-    You can also generate an absolute URL by using the ``url`` Twig function:
+    You can also generate an absolute URL by using the ``url`` function:
 
-    .. code-block:: html+twig
+    .. configuration-block::
 
-        <a href="{{ url('_welcome') }}">Home</a>
+        .. code-block:: html+twig
 
-    The same can be done in PHP templates by passing a third argument to
-    the ``generate()`` method:
+            <a href="{{ url('_welcome') }}">Home</a>
 
-    .. code-block:: html+php
+        .. code-block:: html+php
 
-        <?php
-        use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
-        ?>
+            <a href="<?php echo $view['router']->url(
+                '_welcome',
+                array()
+            ) ?>">Home</a>
 
-        <a href="<?php echo $view['router']->generate(
-            '_welcome',
-            array(),
-            UrlGeneratorInterface::ABSOLUTE_URL
-        ) ?>">Home</a>
+    .. versionadded:: 2.8
+        The ``url()`` PHP templating helper was introduced in Symfony 2.8. Prior
+        to 2.8, you had to use the ``generate()`` helper method with
+        ``Symfony\Component\Routing\Generator\UrlGeneratorInterface::ABSOLUTE_URL``
+        passed as third argument.
 
 .. index::
    single: Templating; Linking to assets
@@ -1696,7 +1703,9 @@ key in the parameter hash:
 
     .. code-block:: html+php
 
-        <a href="<?php echo $view['router']->generate('article_show', array(
+        <!-- The path() method was introduced in Symfony 2.8. Prior to 2.8, you
+             had to use generate(). -->
+        <a href="<?php echo $view['router']->path('article_show', array(
             'id' => 123,
             '_format' => 'pdf',
         )) ?>">

Diff for: cookbook/security/csrf_in_login_form.rst

@@ -107,7 +107,9 @@ using the login form:
         <!-- src/AppBundle/Resources/views/Security/login.html.php -->
 
         <!-- ... -->
-        <form action="<?php echo $view['router']->generate('login_check') ?>" method="post">
+        <!-- The path() method was introduced in Symfony 2.8. Prior to 2.8, you
+             had to use generate(). -->
+        <form action="<?php echo $view['router']->path('login_check') ?>" method="post">
             <!-- ... the login fields -->
 
             <input type="hidden" name="_csrf_token"

Diff for: cookbook/security/form_login.rst

@@ -253,7 +253,9 @@ redirect to the URL defined by some ``account`` route, use the following:
             <div><?php echo $error->getMessage() ?></div>
         <?php endif ?>
 
-        <form action="<?php echo $view['router']->generate('login_check') ?>" method="post">
+        <!-- The path() method was introduced in Symfony 2.8. Prior to 2.8, you
+             had to use generate(). -->
+        <form action="<?php echo $view['router']->path('login_check') ?>" method="post">
             <label for="username">Username:</label>
             <input type="text" id="username" name="_username" value="<?php echo $last_username ?>" />
 

Diff for: cookbook/security/form_login_setup.rst

@@ -237,7 +237,9 @@ Finally, create the template:
             <div><?php echo $error->getMessage() ?></div>
         <?php endif ?>
 
-        <form action="<?php echo $view['router']->generate('login_check') ?>" method="post">
+        <!-- The path() method was introduced in Symfony 2.8. Prior to 2.8, you
+             had to use generate(). -->
+        <form action="<?php echo $view['router']->path('login_check') ?>" method="post">
             <label for="username">Username:</label>
             <input type="text" id="username" name="_username" value="<?php echo $last_username ?>" />
 

Diff for: cookbook/security/impersonating_user.rst

@@ -84,11 +84,11 @@ to show a link to exit impersonation:
     .. code-block:: html+php
 
         <?php if ($view['security']->isGranted('ROLE_PREVIOUS_ADMIN')): ?>
-            <a
-                href="<?php echo $view['router']->generate('homepage', array(
-                    '_switch_user' => '_exit',
-                ) ?>"
-            >
+            <!-- The path() method was introduced in Symfony 2.8. Prior to 2.8, you
+                had to use generate(). -->
+            <a href="<?php echo $view['router']->path('homepage', array(
+                '_switch_user' => '_exit',
+            ) ?>">
                 Exit impersonation
             </a>
         <?php endif ?>

Diff for: cookbook/security/remember_me.rst

@@ -175,7 +175,9 @@ this:
             <div><?php echo $error->getMessage() ?></div>
         <?php endif ?>
 
-        <form action="<?php echo $view['router']->generate('login_check') ?>" method="post">
+        <!-- The path() method was introduced in Symfony 2.8. Prior to 2.8, you
+             had to use generate(). -->
+        <form action="<?php echo $view['router']->path('login_check') ?>" method="post">
             <label for="username">Username:</label>
             <input type="text" id="username"
                    name="_username" value="<?php echo $last_username ?>" />

Diff for: cookbook/templating/PHP.rst

@@ -306,11 +306,11 @@ updated by changing the configuration:
 
 .. code-block:: html+php
 
-    <a href="<?php echo $view['router']->generate('hello', array('name' => 'Thomas')) ?>">
+    <a href="<?php echo $view['router']->path('hello', array('name' => 'Thomas')) ?>">
         Greet Thomas!
     </a>
 
-The ``generate()`` method takes the route name and an array of parameters as
+The ``path()`` method takes the route name and an array of parameters as
 arguments. The route name is the main key under which routes are referenced
 and the parameters are the values of the placeholders defined in the route
 pattern: