From a4ad744041a58c303f7563795828a4dd78b11b0f Mon Sep 17 00:00:00 2001
From: WouterJ <waldio.webdesign@gmail.com>
Date: Sun, 29 Nov 2015 01:05:33 +0100
Subject: [PATCH] Use path() and url() PHP templating helpers

---
 book/forms.rst                           |  4 ++-
 book/from_flat_php_to_symfony2.rst       |  2 +-
 book/http_cache.rst                      | 13 ++++---
 book/routing.rst                         | 25 +++++++------
 book/templating.rst                      | 45 ++++++++++++++----------
 cookbook/security/csrf_in_login_form.rst |  4 ++-
 cookbook/security/form_login.rst         |  4 ++-
 cookbook/security/form_login_setup.rst   |  4 ++-
 cookbook/security/impersonating_user.rst | 10 +++---
 cookbook/security/remember_me.rst        |  4 ++-
 cookbook/templating/PHP.rst              |  4 +--
 11 files changed, 71 insertions(+), 48 deletions(-)

diff --git a/book/forms.rst b/book/forms.rst
index 7ee7bff700d..504cc8a7ed6 100644
--- a/book/forms.rst
+++ b/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 --git a/book/from_flat_php_to_symfony2.rst b/book/from_flat_php_to_symfony2.rst
index d243b390434..5420a31ea1b 100644
--- a/book/from_flat_php_to_symfony2.rst
+++ b/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 --git a/book/http_cache.rst b/book/http_cache.rst
index bf91ff2345d..e01baff8c6d 100644
--- a/book/http_cache.rst
+++ b/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 --git a/book/routing.rst b/book/routing.rst
index ed0b4bf809c..b57ad003e2e 100644
--- a/book/routing.rst
+++ b/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 --git a/book/templating.rst b/book/templating.rst
index 4c1de72f752..8f558e5cf40 100644
--- a/book/templating.rst
+++ b/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 --git a/cookbook/security/csrf_in_login_form.rst b/cookbook/security/csrf_in_login_form.rst
index b7649aa92f7..5853bbec647 100644
--- a/cookbook/security/csrf_in_login_form.rst
+++ b/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 --git a/cookbook/security/form_login.rst b/cookbook/security/form_login.rst
index b4b5713b531..1478e40d13a 100644
--- a/cookbook/security/form_login.rst
+++ b/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 --git a/cookbook/security/form_login_setup.rst b/cookbook/security/form_login_setup.rst
index c936dd8b08e..b1909a5807e 100644
--- a/cookbook/security/form_login_setup.rst
+++ b/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 --git a/cookbook/security/impersonating_user.rst b/cookbook/security/impersonating_user.rst
index 2e37aaa0b2f..f12ac39941f 100644
--- a/cookbook/security/impersonating_user.rst
+++ b/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 --git a/cookbook/security/remember_me.rst b/cookbook/security/remember_me.rst
index aea7eddcf53..b1bb8650e21 100644
--- a/cookbook/security/remember_me.rst
+++ b/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 --git a/cookbook/templating/PHP.rst b/cookbook/templating/PHP.rst
index c156866f61b..03a16cf2d33 100644
--- a/cookbook/templating/PHP.rst
+++ b/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: