Merge branch '2.3' into 2.5

* 2.3:
  Re-wording based on Wouter's recommendation
  update text to use SetHandler (not ProxyPassMatch)
  cache_csrf_form
  [Book][Security] Add isPasswordValid doc as in 2.6
  [#4656] Re-reading private service section

book/forms.rst

@@ -1791,6 +1791,13 @@ section.
     The ``intention`` option is optional but greatly enhances the security of
     the generated token by making it different for each form.
 
+.. caution::
+
+    CSRF tokens are meant to be different for every user. This is why you
+    need to be cautious if you try to cache pages with forms including this
+    kind of protection. For more information, see
+    :doc:`/cookbook/cache/form_csrf_caching`.
+
 .. index::
    single: Forms; With no class
 
@@ -1926,6 +1933,8 @@ Learn more from the Cookbook
 * :doc:`/cookbook/form/form_customization`
 * :doc:`/cookbook/form/dynamic_form_modification`
 * :doc:`/cookbook/form/data_transformers`
+* :doc:`/cookbook/security/csrf_in_login_form`
+* :doc:`/cookbook/cache/form_csrf_caching`
 
 .. _`Symfony Form component`: https://github.com/symfony/Form
 .. _`DateTime`: http://php.net/manual/en/class.datetime.php

book/security.rst

@@ -1176,6 +1176,10 @@ In order for this to work, just make sure that you have the encoder for your
 user class (e.g. ``AppBundle\Entity\User``) configured under the ``encoders``
 key in ``app/config/security.yml``.
 
+The ``$encoder`` object also has an ``isPasswordValid`` method, which takes
+the ``User`` object as the first argument and the plain password to check
+as the second argument.
+
 .. caution::
 
     When you allow a user to submit a plaintext password (e.g. registration

components/dependency_injection/advanced.rst

@@ -10,29 +10,19 @@ Marking Services as public / private
 When defining services, you'll usually want to be able to access these definitions
 within your application code. These services are called ``public``. For example,
 the ``doctrine`` service registered with the container when using the DoctrineBundle
-is a public service as you can access it via::
+is a public service. This means that you can fetch it from the container
+using the ``get()`` method::
 
    $doctrine = $container->get('doctrine');
 
-However, there are use-cases when you don't want a service to be public. This
-is common when a service is only defined because it could be used as an
-argument for another service.
+In some cases, a service *only* exists to be injected into another service
+and is *not* intended to be fetched directly from the container as shown
+above. 
 
 .. _inlined-private-services:
 
-Since a container is not able to detect if a service is retrieved from inside
-the container or the outside, a private service may still be retrieved using
-the ``get()`` method.
-
-What makes private services special, is that they are converted from services
-to inlined instantiation (e.g. ``new PrivateThing()``) when they are only
-injected once, to increase the container performance. This means that you can
-never be sure if a private service exists in the container.
-
-Simply said: A service will be private when you do not want to access it
-directly from your code.
-
-Here is an example:
+In these cases, to get a minor performance boost, you can set the service
+to be *not* public (i.e. private):
 
 .. configuration-block::
 
@@ -63,11 +53,19 @@ Here is an example:
         $definition->setPublic(false);
         $container->setDefinition('foo', $definition);
 
-Now that the service is private, you *should not* call (should not means, this
-*might* fail, see the explaination above)::
+What makes private services special is that, if they are only injected once,
+they are converted from services to inlined instantiations (e.g. ``new PrivateThing()``).
+This increases the container's performance.
+
+Now that the service is private, you *should not* fetch the service directly
+from the container::
 
     $container->get('foo');
 
+This *may or may not work*, depending on if the service could be inlined.
+Simply said: A service can be marked as private if you do not want to access
+it directly from your code.
+
 However, if a service has been marked as private, you can still alias it (see
 below) to access this service (via the alias).
 

cookbook/cache/form_csrf_caching.rst

@@ -0,0 +1,48 @@
+.. index::
+    single: Cache; CSRF; Forms
+
+Caching Pages that Contain CSRF Protected Forms
+===============================================
+
+CSRF tokens are meant to be different for every user. This is why you
+need to be cautious if you try to cache pages with forms including them.
+
+For more information about how CSRF protection works in Symfony, please
+check :ref:`CSRF Protection <forms-csrf>`.
+
+Why Reverse Proxy Caches do not Cache these Pages by Default
+------------------------------------------------------------
+
+There are many ways to generate unique tokens for each user but in order get
+them validated when the form is submitted, you need to store them inside the
+PHP Session.
+
+If you are using Varnish or some similar reverse proxy cache and you try to cache
+pages containing forms with CSRF token protection, you will see that, by default,
+the reverse proxy cache refuses to cache.
+
+This happens because a cookie is sent in order to preserve the PHP session open and
+Varnish default behaviour is to not cache HTTP requests with cookies.
+
+If you think about it, if you managed to cache the form you would end up
+with many users getting the same token in the form generation. When these
+users try to send the form to the server, the CSRF validation will fail for
+them because the expected token is stored in their session and different
+for each user.
+
+How to Cache Most of the Page and still Be Able to Use CSRF Protection
+----------------------------------------------------------------------
+
+To cache a page that contains a CSRF token you can use more advanced caching
+techniques like `ESI`_ fragments, having a TTL for the full page and embedding
+the form inside an ESI tag with no cache at all.
+
+Another option to be able to cache that heavy page would be loading the form
+via an uncached AJAX request but cache the rest of the HTML response.
+
+Or you can even load just the CSRF token with an AJAX request and replace the
+form field value with it.
+
+.. _`Cross-site request forgery`: http://en.wikipedia.org/wiki/Cross-site_request_forgery
+.. _`ESI`: http://www.w3.org/TR/esi-lang
+.. _`Security CSRF Component`: https://github.com/symfony/security-csrf

cookbook/cache/index.rst

@@ -5,3 +5,4 @@ Cache
     :maxdepth: 2
 
     varnish
+    form_csrf_caching

cookbook/configuration/web_server_configuration.rst

@@ -118,7 +118,7 @@ Using mod_proxy_fcgi with Apache 2.4
 If you are running Apache 2.4, you can easily use ``mod_proxy_fcgi`` to pass
 incoming requests to PHP-FPM. Configure PHP-FPM to listen on a TCP socket
 (``mod_proxy`` currently `does not support unix sockets`_), enable ``mod_proxy``
-and ``mod_proxy_fcgi`` in your Apache configuration and use the ``ProxyPassMatch``
+and ``mod_proxy_fcgi`` in your Apache configuration and use the ``SetHandler``
 directive to pass requests for PHP files to PHP FPM:
 
 .. code-block:: apache
@@ -133,14 +133,17 @@ directive to pass requests for PHP files to PHP FPM:
         # SetEnvIfNoCase ^Authorization$ "(.+)" HTTP_AUTHORIZATION=$1
 
         # For Apache 2.4.9 or higher
-        # Using SetHandler avoids issues with using ProxyPassMatch in combination 
+        # Using SetHandler avoids issues with using ProxyPassMatch in combination
         # with mod_rewrite or mod_autoindex
         <FilesMatch \.php$>
             SetHandler proxy:fcgi://127.0.0.1:9000
         </FilesMatch>
         # If you use Apache version below 2.4.9 you must consider update or use this instead
         # ProxyPassMatch ^/(.*\.php(/.*)?)$ fcgi://127.0.0.1:9000/var/www/project/web/$1
-        
+        # If you run your Symfony application on a subpath of your document root, the
+        # regular expression must be changed accordingly:
+        # ProxyPassMatch ^/path-to-app/(.*\.php(/.*)?)$ fcgi://127.0.0.1:9000/var/www/project/web/$1
+
         DocumentRoot /var/www/project/web
         <Directory /var/www/project/web>
             # enable the .htaccess rewrites
@@ -152,16 +155,6 @@ directive to pass requests for PHP files to PHP FPM:
         CustomLog /var/log/apache2/project_access.log combined
     </VirtualHost>
 
-.. caution::
-
-    When you run your Symfony application on a subpath of your document root,
-    the regular expression used in ``ProxyPassMatch`` directive must be changed
-    accordingly:
-
-    .. code-block:: apache
-
-        ProxyPassMatch ^/path-to-app/(.*\.php(/.*)?)$ fcgi://127.0.0.1:9000/var/www/project/web/$1
-
 PHP-FPM with Apache 2.2
 ~~~~~~~~~~~~~~~~~~~~~~~
 

cookbook/map.rst.inc

@@ -20,6 +20,7 @@
 * :doc:`/cookbook/cache/index`
 
   * :doc:`/cookbook/cache/varnish`
+  * :doc:`/cookbook/cache/form_csrf_caching`
 
 * **Composer**