Merge branch '2.3' into 2.7

Conflicts:
	book/controller.rst

Author: xabbuh

book/controller.rst

@@ -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::
 

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/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::

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;
         });