Merge remote-tracking branch 'origin/master'

* origin/master: (93 commits)
  [#5623] don't configure default constraint message
  [Validator] added BIC validator
  Update links
  Added September changelog
  Added September changelog
  Misspelling
  [#5689] Some minor syntax fixes
  [DI] Add some documentation for the deprecation feature
  Info about implicit session start
  Revert "[#5771] remove another Response constant"
  Revert "Remove not existing response constant"
  [#5771] remove another Response constant
  [#5761] add versionadded directive
  Fixed two typos
  Remember me, Renamed key to secret
  translations have been removed from symfony.com
  Remove not existing response constant
  Update HttpFoundation note after recent changes in routing component
  [#5584] language tweak and XML config fix
  Add DebugBundle config reference
  ...

Author: weaverryan

_theme/_templates/layout.html

@@ -44,9 +44,9 @@
         <div id="sidebar" class="col-sm-3">
             <div id="sidebar-content">
                 <div id="demo-warning">
-                    <h4>This is a demo</h4>
-                    <p>This is a demo provided by platform.sh.<br>
-                    <a href="http://symfony.com/doc/current/{{ pagename }}">Visit on symfony.com</a>.</p>
+                    <h4>Pull request build</h4>
+                    <p>Each pull request of the Symfony Documentation is automatically deployed and hosted on <a href="https://platform.sh">Platform.sh</a>.<br>
+                    View this page on <a href="https://symfony.com/doc/current/{{ pagename }}">symfony.com</a>.</p>
                 </div>
 
                 {%- include "globaltoc.html" %}

book/controller.rst

@@ -619,8 +619,8 @@ session.
 Flash Messages
 ~~~~~~~~~~~~~~
 
-You can also store small messages that will be stored on the user's session
-for exactly one additional request. This is useful when processing a form:
+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.
 
@@ -675,9 +675,17 @@ the ``notice`` message:
             </div>
         <?php endforeach ?>
 
-By design, flash messages are meant to live for exactly one request (they're
-"gone in a flash"). They're designed to be used across redirects exactly as
-you've done in this example.
+.. 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.
+
+.. tip::
+
+    You can use the
+    :method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::peek`
+    method instead to retrieve the message while keeping it in the bag.
 
 .. index::
    single: Controller; Response object

book/forms.rst

@@ -232,13 +232,21 @@ controller::
         $form->handleRequest($request);
 
         if ($form->isValid()) {
-            // perform some action, such as saving the task to the database
+            // ... perform some action, such as saving the task to the database
 
             return $this->redirectToRoute('task_success');
         }
 
-        // ...
+        return $this->render('default/new.html.twig', array(
+            'form' => $form->createView(),
+        ));
     }
+    
+.. caution::
+
+    Be aware that the ``createView()`` method should be called *after* ``handleRequest``
+    is called. Otherwise, changes done in the ``*_SUBMIT`` events aren't applied to the
+    view (like validation errors).
 
 .. versionadded:: 2.3
     The :method:`Symfony\\Component\\Form\\FormInterface::handleRequest` method
@@ -1774,6 +1782,11 @@ The ``_token`` field is a hidden field and will be automatically rendered
 if you include the ``form_end()`` function in your template, which ensures
 that all un-rendered fields are output.
 
+.. caution::
+
+    Since the token is stored in the session, a session is started automatically
+    as soon as you render a form with CSRF protection.
+
 The CSRF token can be customized on a form-by-form basis. For example::
 
     use Symfony\Component\OptionsResolver\OptionsResolver;
@@ -1953,7 +1966,7 @@ Learn more from the Cookbook
 * :doc:`/cookbook/security/csrf_in_login_form`
 * :doc:`/cookbook/cache/form_csrf_caching`
 
-.. _`Symfony Form component`: https://github.com/symfony/Form
+.. _`Symfony Form component`: https://github.com/symfony/form
 .. _`DateTime`: http://php.net/manual/en/class.datetime.php
 .. _`Twig Bridge`: https://github.com/symfony/symfony/tree/master/src/Symfony/Bridge/Twig
 .. _`form_div_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig

book/from_flat_php_to_symfony2.rst

@@ -757,8 +757,8 @@ Learn more from the Cookbook
 
 .. _`Doctrine`: http://www.doctrine-project.org
 .. _`download Composer`: https://getcomposer.org/download/
-.. _`Routing`: https://github.com/symfony/Routing
-.. _`Templating`: https://github.com/symfony/Templating
+.. _`Routing`: https://github.com/symfony/routing
+.. _`Templating`: https://github.com/symfony/templating
 .. _`KnpBundles.com`: http://knpbundles.com/
 .. _`Twig`: http://twig.sensiolabs.org
 .. _`Varnish`: https://www.varnish-cache.org/

book/http_cache.rst

@@ -230,7 +230,7 @@ Here is a list of the main options:
 ``allow_revalidate``
     Specifies whether the client can force a cache revalidate by including a
     ``Cache-Control`` "max-age=0" directive in the request. Set it to ``true`` for
-    compliance with RFC 2616 (default: false).
+    compliance with RFC 2616 (default: ``false``).
 
 ``stale_while_revalidate``
     Specifies the default number of seconds (the granularity is the second as the
@@ -651,6 +651,7 @@ header value::
     namespace AppBundle\Controller;
 
     // ...
+    use Symfony\Component\HttpFoundation\Response;
     use Symfony\Component\HttpFoundation\Request;
     use AppBundle\Entity\Article;
 
@@ -665,6 +666,7 @@ header value::
 
             $date = $authorDate > $articleDate ? $authorDate : $articleDate;
 
+            $response = new Response();
             $response->setLastModified($date);
             // Set response as public. Otherwise it will be private by default.
             $response->setPublic();
@@ -880,8 +882,8 @@ that data from its cache.
 
     If you want to use cache invalidation, have a look at the
     `FOSHttpCacheBundle`_. This bundle provides services to help with various
-    cache invalidation concepts, and also documents the configuration for the
-    a couple of common caching proxies.
+    cache invalidation concepts and also documents the configuration for a
+    couple of common caching proxies.
 
 If one content corresponds to one URL, the ``PURGE`` model works well.
 You send a request to the cache proxy with the HTTP method ``PURGE`` (using

book/http_fundamentals.rst

@@ -579,5 +579,5 @@ sensible defaults. For more advanced users, the sky is the limit.
 .. _`List of HTTP status codes`: https://en.wikipedia.org/wiki/List_of_HTTP_status_codes
 .. _`List of HTTP header fields`: https://en.wikipedia.org/wiki/List_of_HTTP_header_fields
 .. _`List of common media types`: https://www.iana.org/assignments/media-types/media-types.xhtml
-.. _`Validator`: https://github.com/symfony/Validator
+.. _`Validator`: https://github.com/symfony/validator
 .. _`Swift Mailer`: http://swiftmailer.org/

book/installation.rst

@@ -239,7 +239,7 @@ If there are any issues, correct them now before moving on.
         $ rm -rf app/cache/*
         $ rm -rf app/logs/*
 
-        $ HTTPDUSER=`ps aux | grep -E '[a]pache|[h]ttpd|[_]www|[w]ww-data|[n]ginx' | grep -v root | head -1 | cut -d\  -f1`
+        $ HTTPDUSER=`ps axo user,comm | grep -E '[a]pache|[h]ttpd|[_]www|[w]ww-data|[n]ginx' | grep -v root | head -1 | cut -d\  -f1`
         $ sudo chmod +a "$HTTPDUSER allow delete,write,append,file_inherit,directory_inherit" app/cache app/logs
         $ sudo chmod +a "`whoami` allow delete,write,append,file_inherit,directory_inherit" app/cache app/logs
 
@@ -254,7 +254,7 @@ If there are any issues, correct them now before moving on.
 
     .. code-block:: bash
 
-        $ HTTPDUSER=`ps aux | grep -E '[a]pache|[h]ttpd|[_]www|[w]ww-data|[n]ginx' | grep -v root | head -1 | cut -d\  -f1`
+        $ HTTPDUSER=`ps axo user,comm | grep -E '[a]pache|[h]ttpd|[_]www|[w]ww-data|[n]ginx' | grep -v root | head -1 | cut -d\  -f1`
         $ sudo setfacl -R -m u:"$HTTPDUSER":rwX -m u:`whoami`:rwX app/cache app/logs
         $ sudo setfacl -dR -m u:"$HTTPDUSER":rwX -m u:`whoami`:rwX app/cache app/logs
 

book/security.rst

@@ -512,7 +512,7 @@ else, you'll want to encode their passwords. The best algorithm to use is
 
 .. include:: /cookbook/security/_ircmaxwell_password-compat.rst.inc
 
-Of course, your user's passwords now need to be encoded with this exact algorithm.
+Of course, your users' passwords now need to be encoded with this exact algorithm.
 For hardcoded users, you can use an `online tool`_, which will give you something
 like this:
 

book/translation.rst

@@ -593,7 +593,7 @@ use somewhere in your application::
         public $name;
     }
 
-Add constraints though any of the supported methods. Set the message option to the
+Add constraints through any of the supported methods. Set the message option to the
 translation source text. For example, to guarantee that the ``$name`` property is
 not empty, add the following:
 

book/validation.rst

@@ -734,19 +734,19 @@ user registers and when a user updates their contact information later:
         class User implements UserInterface
         {
             /**
-            * @Assert\Email(groups={"registration"})
-            */
+             * @Assert\Email(groups={"registration"})
+             */
             private $email;
 
             /**
-            * @Assert\NotBlank(groups={"registration"})
-            * @Assert\Length(min=7, groups={"registration"})
-            */
+             * @Assert\NotBlank(groups={"registration"})
+             * @Assert\Length(min=7, groups={"registration"})
+             */
             private $password;
 
             /**
-            * @Assert\Length(min=2)
-            */
+             * @Assert\Length(min=2)
+             */
             private $city;
         }
 
@@ -927,13 +927,13 @@ username and the password are different only if all other validation passes
         class User implements UserInterface
         {
             /**
-            * @Assert\NotBlank
-            */
+             * @Assert\NotBlank
+             */
             private $username;
 
             /**
-            * @Assert\NotBlank
-            */
+             * @Assert\NotBlank
+             */
             private $password;
 
             /**
@@ -1300,5 +1300,5 @@ Learn more from the Cookbook
 
 * :doc:`/cookbook/validation/custom_constraint`
 
-.. _Validator: https://github.com/symfony/Validator
+.. _Validator: https://github.com/symfony/validator
 .. _JSR303 Bean Validation specification: http://jcp.org/en/jsr/detail?id=303