Use path() and url() PHP templating helpers

Author: wouterj

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',
         )) ?>
 

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())
             ) ?>">

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'),
         ) ?>

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

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',
         )) ?>">

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"

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 ?>" />
 

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 ?>" />
 

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 ?>

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 ?>" />