Merge branch '2.8'

Author: xabbuh

book/controller.rst

@@ -440,7 +440,7 @@ If you want to redirect the user to another page, use the ``redirectToRoute()``
     }
 
 .. versionadded:: 2.6
-    The ``redirectToRoute()`` method was added in Symfony 2.6. Previously (and still now), you
+    The ``redirectToRoute()`` method was introduced in Symfony 2.6. Previously (and still now), you
     could use ``redirect()`` and ``generateUrl()`` together for this (see the example above).
 
 Or, if you want to redirect externally, just use ``redirect()`` and pass it the URL::
@@ -619,12 +619,12 @@ session.
 Flash Messages
 ~~~~~~~~~~~~~~
 
-You can also store small messages that will be stored on the user's session.
-This is useful when processing a form:
-you want to redirect and have a special message shown on the *next* page.
-These types of messages are called "flash" messages.
+You can also store special messages, called "flash" messages, on the user's
+session. By design, flash messages are meant to be used exactly once: they vanish
+from the session automatically as soon as you retrieve them. This feature makes
+"flash" messages particularly great for storing user notifications.
 
-For example, imagine you're processing a form submit::
+For example, imagine you're processing a form submission::
 
     use Symfony\Component\HttpFoundation\Request;
 
@@ -650,20 +650,20 @@ For example, imagine you're processing a form submit::
         return $this->render(...);
     }
 
-After processing the request, the controller sets a ``notice`` flash message
-in the session and then redirects. The name (``notice``) isn't significant -
-it's just something you invent and reference next.
+After processing the request, the controller sets a flash message in the session
+and then redirects. The message key (``notice`` in this example) can be anything:
+you'll use this key to retrieve the message.
 
-In the template of the next action, the following code could be used to render
-the ``notice`` message:
+In the template of the next page (or even better, in your base layout template),
+read any flash messages from the session::
 
 .. configuration-block::
 
     .. code-block:: html+jinja
 
-        {% for flashMessage in app.session.flashbag.get('notice') %}
+        {% for flash_message in app.session.flashbag.get('notice') %}
             <div class="flash-notice">
-                {{ flashMessage }}
+                {{ flash_message }}
             </div>
         {% endfor %}
 
@@ -677,9 +677,9 @@ the ``notice`` message:
 
 .. note::
 
-    By design, flash messages are meant to be processed exactly once. This means
-    that they vanish from the session automatically when they are retrieved from
-    the flash bag by calling the ``get()`` method.
+    It's common to use ``notice``, ``warning`` and ``error`` as the keys of the
+    different types of flash messages, but you can use any key that fits your
+    needs.
 
 .. tip::
 
@@ -811,6 +811,29 @@ Just like when creating a controller for a route, the order of the arguments of
 order of the arguments, Symfony will still pass the correct value to each
 variable.
 
+Validating a CSRF Token
+-----------------------
+
+Sometimes, you want to use CSRF protection in an action where you don't want to
+use the Symfony Form component. If, for example, you're doing a DELETE action,
+you can use the :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::isCsrfTokenValid`
+method to check the CSRF token::
+
+    if ($this->isCsrfTokenValid('token_id', $submittedToken)) {
+        // ... do something, like deleting an object
+    }
+
+.. versionadded:: 2.6
+    The ``isCsrfTokenValid()`` shortcut method was introduced in Symfony 2.6.
+    It is equivalent to executing the following code:
+
+    .. code-block:: php
+
+        use Symfony\Component\Security\Csrf\CsrfToken;
+
+        $this->get('security.csrf.token_manager')
+            ->isTokenValid(new CsrfToken('token_id', 'TOKEN'));
+
 Final Thoughts
 --------------
 

book/installation.rst

@@ -98,17 +98,17 @@ optional second argument of the ``new`` command:
     $ symfony new my_project_name 2.3.26
     $ symfony new my_project_name 2.6.5
 
-If you want your project to be based on the latest :ref:`Symfony LTS version <releases-lts>`,
-pass ``lts`` as the second argument of the ``new`` command:
+    # use a beta or RC version (useful for testing new Symfony versions)
+    $ symfony new my_project 2.7.0-BETA1
+    $ symfony new my_project 2.7.0-RC1
+
+The installer also supports a special version called ``lts`` which installs the
+most recent :ref:`Symfony LTS version <releases-lts>` available:
 
 .. code-block:: bash
 
-    # Linux, Mac OS X
     $ symfony new my_project_name lts
 
-    # Windows
-    c:\projects\> php symfony new my_project_name lts
-
 Read the :doc:`Symfony Release process </contributing/community/releases>`
 to better understand why there are several Symfony versions and which one
 to use for your projects.

book/routing.rst

@@ -1575,9 +1575,13 @@ to ``generate()``:
 
     .. code-block:: html+php
 
+        <?php
+        use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
+        ?>
+
         <a href="<?php echo $view['router']->generate('blog_show', array(
             'slug' => 'my-blog-post',
-        ), true) ?>">
+        ), UrlGeneratorInterface::ABSOLUTE_URL) ?>">
             Read this blog post.
         </a>
 

book/security.rst

@@ -1378,6 +1378,15 @@ FriendsOfPHP organization.
     any of your dependencies is affected by a known security vulnerability.
     Therefore, you can easily integrate it in your build process.
 
+.. note::
+
+    To enable the ``security:check`` command, make sure the
+    `SensioDistributionBundle`_ is installed.
+
+    .. code-block:: bash
+
+        $ composer require 'sensio/distribution-bundle'
+
 Final Words
 -----------
 
@@ -1408,3 +1417,4 @@ Learn More from the Cookbook
 .. _`frameworkextrabundle documentation`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/index.html
 .. _`security advisories database`: https://github.com/FriendsOfPHP/security-advisories
 .. _`HWIOAuthBundle`: https://github.com/hwi/HWIOAuthBundle
+.. _`SensioDistributionBundle`: https://packagist.org/packages/sensio/distribution-bundle

book/templating.rst

@@ -580,8 +580,8 @@ you set `with_context`_ to false).
     elements, it would look like this: ``{'foo': foo, 'bar': bar}``.
 
 .. versionadded:: 2.3
-    The `include() function`_ is a new Twig feature that's available in Symfony
-    2.3. Prior, the `{% include %} tag`_ tag was used.
+    The `include() function`_ is available since Symfony 2.3. Prior, the
+    `{% include %} tag`_ was used.
 
 .. index::
    single: Templating; Embedding action
@@ -856,6 +856,24 @@ configuration:
 
 .. configuration-block::
 
+    .. code-block:: php-annotations
+
+        // src/AppBundle/Controller/WelcomeController.php
+        // ...
+
+        use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
+
+        class WelcomeController extends Controller
+        {
+            /**
+             * @Route("/", name="_welcome")
+             */
+            public function indexAction()
+            {
+                // ...
+            }
+        }
+
     .. code-block:: yaml
 
         # app/config/routing.yml
@@ -907,6 +925,24 @@ route:
 
 .. configuration-block::
 
+    .. code-block:: php-annotations
+
+        // src/AppBundle/Controller/ArticleController.php
+        // ...
+
+        use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
+
+        class ArticleController extends Controller
+        {
+            /**
+             * @Route("/article/{slug}", name="article_show")
+             */
+            public function showAction($slug)
+            {
+                // ...
+            }
+        }
+
     .. code-block:: yaml
 
         # app/config/routing.yml
@@ -981,10 +1017,14 @@ correctly:
 
     .. code-block:: html+php
 
+        <?php
+        use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
+        ?>
+
         <a href="<?php echo $view['router']->generate(
             '_welcome',
             array(),
-            true
+            UrlGeneratorInterface::ABSOLUTE_URL
         ) ?>">Home</a>
 
 .. index::
@@ -1029,8 +1069,8 @@ configuration option.
 
 .. _`book-templating-version-by-asset`:
 
-If you need to set a version for a specific asset, you can set the fourth
-argument (or the ``version`` argument) to the desired version:
+If you need to set a version for a specific asset, you can set the ``version`` argument
+if you are using Twig (or the fourth argument if you are using PHP) to the desired version:
 
 .. configuration-block::
 
@@ -1051,8 +1091,8 @@ If you don't give a version or pass ``null``, the default package version
 (from :ref:`ref-framework-assets-version`) will be used. If you pass ``false``,
 versioned URL will be deactivated for this asset.
 
-If you need absolute URLs for assets, you can set the third argument (or the
-``absolute`` argument) to ``true``:
+If you need absolute URLs for assets, you can set the ``absolute`` argument
+if you are using Twig (or the third argument if you are using PHP) to ``true``:
 
 .. configuration-block::
 

components/css_selector.rst

@@ -46,12 +46,17 @@ document.
 The CssSelector Component
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. versionadded:: 2.8
+    The ``CssSelectorConverter`` class was introduced in Symfony 2.8. Previously,
+    the ``CssSelector`` class was used and ``toXPath`` was a static method.
+
 The component's only goal is to convert CSS selectors to their XPath
-equivalents::
+equivalents, using :method:`Symfony\\Component\\CssSelector\\CssSelectorConverter::toXPath`::
 
-    use Symfony\Component\CssSelector\CssSelector;
+    use Symfony\Component\CssSelector\CssSelectorConverter;
 
-    var_dump(CssSelector::toXPath('div.item > h4 > a'));
+    $converter = new CssSelectorConverter();
+    var_dump($converter->toXPath('div.item > h4 > a'));
 
 This gives the following output:
 

components/dependency_injection/advanced.rst

@@ -226,8 +226,7 @@ Deprecating Services
     The ``deprecated`` setting was introduced in Symfony 2.8.
 
 Once you have decided to deprecate the use of a service (because it is outdated
-or you decided not to use and maintain it anymore), you can deprecate its
-definition:
+or you decided not to maintain it anymore), you can deprecate its definition:
 
 .. configuration-block::
 
@@ -261,26 +260,25 @@ definition:
             )
         ;
 
-Now, every time a service is created using this deprecated definition, a
-deprecation warning will be triggered, advising you to stop or to change your
-uses of that service.
+Now, every time this service is used, a deprecation warning is triggered,
+advising you to stop or to change your uses of that service.
 
-The message is actually a message template, which will replace occurrences
-of the ``%service_id%`` by the service's id. You **must** have at least one
+The message is actually a message template, which replaces occurrences of the
+``%service_id%`` placeholder by the service's id. You **must** have at least one
 occurrence of the ``%service_id%`` placeholder in your template.
 
 .. note::
 
-    The deprecation message is optional. If not set, Symfony will show a default
-    message ``The "%service_id%" service is deprecated. You should stop using it,
+    The deprecation message is optional. If not set, Symfony will show this default
+    message: ``The "%service_id%" service is deprecated. You should stop using it,
     as it will soon be removed.``.
 
 .. tip::
 
-    It is strongly recommended that you fill the message template, to avoid a
-    message that could be too generic such as the default one. A good message
-    informs when this service was deprecated, and until when it will be
-    maintained (look at the examples above).
+    It is strongly recommended that you define a custom message because the
+    default one is too generic. A good message informs when this service was
+    deprecated, until when it will be maintained and the alternative services
+    to use (if any).
 
 For service decorators (see above), if the definition does not modify the
 deprecated status, it will inherit the status from the definition that is

components/dom_crawler.rst

@@ -87,7 +87,7 @@ Anonymous function can be used to filter with more complex criteria::
     $crawler = $crawler
         ->filter('body > p')
         ->reduce(function (Crawler $node, $i) {
-            // filter even nodes
+            // filter every other node
             return ($i % 2) == 0;
         });