feature #4800 [Cookbook][Security] Hint about createToken can return …

…null (xelaris)

This PR was merged into the 2.5 branch.

Discussion
----------

[Cookbook][Security] Hint about createToken can return null

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | no
| Applies to    | 2.5+
| Fixed tickets |

see symfony/symfony#12002

Commits
-------

528aa17 [Cookbook][Security] Hint about createToken can return null

cookbook/security/api_key_authentication.rst

@@ -52,6 +52,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(
@@ -103,7 +106,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
 ~~~~~~~~~~~~~~~~