Merge branch '2.5' into 2.6

Author: wouterj

book/routing.rst

@@ -1021,8 +1021,8 @@ routing system can be:
             /**
              * @Route(
              *     "/articles/{_locale}/{year}/{title}.{_format}",
-             *     defaults: {"_format": "html"},
-             *     requirements: {
+             *     defaults={"_format": "html"},
+             *     requirements={
              *         "_locale": "en|fr",
              *         "_format": "html|rss",
              *         "year": "\d+"

book/security.rst

@@ -275,6 +275,7 @@ But who can you login as? Where do users come from?
     or :doc:`build your own </cookbook/security/custom_authentication_provider>`.
 
 .. _security-user-providers:
+.. _where-do-users-come-from-user-providers:
 
 B) Configuring how Users are Loaded
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -433,6 +434,7 @@ If you'd like to load your users via the Doctrine ORM, that's easy! See
 
 .. _book-security-encoding-user-password:
 .. _c-encoding-the-users-password:
+.. _encoding-the-user-s-password:
 
 C) Encoding the User's Password
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

cookbook/cache/varnish.rst

@@ -65,8 +65,9 @@ Ensure Consistent Caching Behaviour
 
 Varnish uses the cache headers sent by your application to determine how
 to cache content. However, versions prior to Varnish 4 did not respect
-``Cache-Control: no-cache``. To ensure consistent behaviour, use the following
-configuration if you are still using Varnish 3:
+``Cache-Control: no-cache``, ``no-store`` and ``private``. To ensure
+consistent behavior, use the following configuration if you are still
+using Varnish 3:
 
 .. configuration-block::
 
@@ -76,13 +77,19 @@ configuration if you are still using Varnish 3:
             /* By default, Varnish3 ignores Cache-Control: no-cache and private
                https://www.varnish-cache.org/docs/3.0/tutorial/increasing_your_hitrate.html#cache-control
              */
-            if (beresp.http.Cache-Control ~ "no-cache" ||
-                beresp.http.Cache-Control ~ "private"
+            if (beresp.http.Cache-Control ~ "private" ||
+                beresp.http.Cache-Control ~ "no-cache" ||
+                beresp.http.Cache-Control ~ "no-store"
             ) {
                 return (hit_for_pass);
             }
         }
 
+.. tip::
+
+    You can see the default behavior of Varnish in the form of a VCL file:
+    `default.vcl`_ for Varnish 3, `builtin.vcl`_ for Varnish 4.
+
 Enable Edge Side Includes (ESI)
 -------------------------------
 
@@ -143,7 +150,7 @@ Symfony adds automatically:
 .. tip::
 
     If you followed the advice about ensuring a consistent caching
-    behaviour, those vcl functions already exist. Just append the code
+    behavior, those vcl functions already exist. Just append the code
     to the end of the function, they won't interfere with each other.
 
 .. index::
@@ -172,3 +179,5 @@ proxy before it has expired, it adds complexity to your caching setup.
 .. _`Surrogate-Capability Header`: http://www.w3.org/TR/edge-arch
 .. _`cache invalidation`: http://tools.ietf.org/html/rfc2616#section-13.10
 .. _`FOSHttpCacheBundle`: http://foshttpcachebundle.readthedocs.org/
+.. _`default.vcl`: https://www.varnish-cache.org/trac/browser/bin/varnishd/default.vcl?rev=3.0
+.. _`builtin.vcl`: https://www.varnish-cache.org/trac/browser/bin/varnishd/builtin.vcl?rev=4.0

cookbook/security/api_key_authentication.rst

@@ -49,6 +49,9 @@ value and then a User object is created::
 
             if (!$apiKey) {
                 throw new BadCredentialsException('No API key found');
+
+                // or to just skip api key authentication
+                // return null;
             }
 
             return new PreAuthenticatedToken(
@@ -100,7 +103,9 @@ is to create a token object that contains all of the information from the
 request that you need to authenticate the user (e.g. the ``apikey`` query
 parameter). If that information is missing, throwing a
 :class:`Symfony\\Component\\Security\\Core\\Exception\\BadCredentialsException`
-will cause authentication to fail.
+will cause authentication to fail. You might want to return ``null`` instead
+to just skip the authentication, so Symfony can fallback to another authentication
+method, if any.
 
 2. supportsToken
 ~~~~~~~~~~~~~~~~