Merge branch '2.8'

* 2.8:
  tweaks thanks to the guys
  removing deprecation note on a section that was removed
  Wrap all strings containing @ in quotes in Yaml
  Updating some places to use the new CustomUserMessageAuthenticationException
  Added a note about the use of _format query parameter
  Always use "main" as the default firewall name (to match Symfony Standard Edition)

book/routing.rst

@@ -1104,12 +1104,20 @@ a slash. URLs matching this route might look like:
 
     This example also highlights the special ``_format`` routing parameter.
     When using this parameter, the matched value becomes the "request format"
-    of the ``Request`` object. Ultimately, the request format is used for such
-    things as setting the ``Content-Type`` of the response (e.g. a ``json``
-    request format translates into a ``Content-Type`` of ``application/json``).
-    It can also be used in the controller to render a different template for
-    each value of ``_format``. The ``_format`` parameter is a very powerful way
-    to render the same content in different formats.
+    of the ``Request`` object.
+
+    Ultimately, the request format is used for such things as setting the
+    ``Content-Type`` of the response (e.g. a ``json`` request format translates
+    into a ``Content-Type`` of ``application/json``). It can also be used in the
+    controller to render a different template for each value of ``_format``.
+    The ``_format`` parameter is a very powerful way to render the same content
+    in different formats.
+
+    In Symfony versions previous to 3.0, it is possible to override the request
+    format by adding a query parameter named ``_format`` (for example:
+    ``/foo/bar?_format=json``). Relying on this behavior not only is considered
+    a bad practice but it will complicate the upgrade of your applications to
+    Symfony 3.
 
 .. note::
 

cookbook/bundles/best_practices.rst

@@ -342,7 +342,7 @@ The end user can provide values in any configuration file:
 
         # app/config/config.yml
         parameters:
-            acme_blog.author.email: fabien@example.com
+            acme_blog.author.email: "fabien@example.com"
 
     .. code-block:: xml
 

cookbook/console/console_command.rst

@@ -82,11 +82,6 @@ for details.
 Getting Services from the Service Container
 -------------------------------------------
 
-.. caution::
-
-    The "container scopes" concept explained in this section has been deprecated
-    in Symfony 2.8 and it will be removed in Symfony 3.0.
-
 By using :class:`Symfony\\Bundle\\FrameworkBundle\\Command\\ContainerAwareCommand`
 as the base class for the command (instead of the more basic
 :class:`Symfony\\Component\\Console\\Command\\Command`), you have access to the

cookbook/email/dev_environment.rst

@@ -66,7 +66,7 @@ via the ``delivery_address`` option:
 
         # app/config/config_dev.yml
         swiftmailer:
-            delivery_address: dev@example.com
+            delivery_address: "dev@example.com"
 
     .. code-block:: xml
 

cookbook/logging/monolog_email.rst

@@ -31,10 +31,10 @@ it is broken down.
                     handler: swift
                 swift:
                     type:       swift_mailer
-                    from_email: error@example.com
-                    to_email:   error@example.com
+                    from_email: "error@example.com"
+                    to_email:   "error@example.com"
                     # or list of recipients
-                    # to_email:   [dev1@example.com, dev2@example.com, ...]
+                    # to_email:   ["dev1@example.com", "dev2@example.com", ...]
                     subject:    An Error Occurred!
                     level:      debug
 
@@ -161,8 +161,8 @@ get logged on the server as well as the emails being sent:
                     handler: swift
                 swift:
                     type:       swift_mailer
-                    from_email: error@example.com
-                    to_email:   error@example.com
+                    from_email: "error@example.com"
+                    to_email:   "error@example.com"
                     subject:    An Error Occurred!
                     level:      debug
 

cookbook/security/api_key_authentication.rst

@@ -37,6 +37,7 @@ value and then a User object is created::
     use Symfony\Component\Security\Core\Authentication\Token\PreAuthenticatedToken;
     use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
     use Symfony\Component\Security\Core\Exception\AuthenticationException;
+    use Symfony\Component\Security\Core\Exception\CustomUserMessageAuthenticationException;
     use Symfony\Component\Security\Core\Exception\BadCredentialsException;
     use Symfony\Component\Security\Core\User\UserProviderInterface;
     use Symfony\Component\Security\Http\Authentication\SimplePreAuthenticatorInterface;
@@ -80,7 +81,9 @@ value and then a User object is created::
             $username = $userProvider->getUsernameForApiKey($apiKey);
 
             if (!$username) {
-                throw new AuthenticationException(
+                // CAUTION: this message will be returned to the client
+                // (so don't put any un-trusted messages / error strings here)
+                throw new CustomUserMessageAuthenticationException(
                     sprintf('API Key "%s" does not exist.', $apiKey)
                 );
             }
@@ -101,6 +104,11 @@ value and then a User object is created::
         }
     }
 
+.. versionadded:: 2.8
+    The ``CustomUserMessageAuthenticationException`` class is new in Symfony 2.8
+    and helps you return custom authentication messages. In 2.7 or earlier, throw
+    an ``AuthenticationException`` or any sub-class (you can still do this in 2.8).
+
 Once you've :ref:`configured <cookbook-security-api-key-config>` everything,
 you'll be able to authenticate by adding an apikey parameter to the query
 string, like ``http://example.com/admin/foo?apikey=37b51d194a7513e45b56f6524f2d51f2``.
@@ -291,7 +299,11 @@ you can use to create an error ``Response``.
 
         public function onAuthenticationFailure(Request $request, AuthenticationException $exception)
         {
-            return new Response("Authentication Failed.", 403);
+            return new Response(
+                // this contains information about *why* authentication failed
+                // use it, or return your own message
+                strtr($exception->getMessageKey(), $exception->getMessageData())
+            , 403)
         }
     }
 
@@ -543,7 +555,8 @@ to see if the stored token has a valid User object that can be used::
             }
 
             if (!$username) {
-                throw new AuthenticationException(
+                // this message will be returned to the client
+                throw new CustomUserMessageAuthenticationException(
                     sprintf('API Key "%s" does not exist.', $apiKey)
                 );
             }

cookbook/security/custom_password_authenticator.rst

@@ -39,7 +39,7 @@ the user::
     use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
     use Symfony\Component\Security\Core\Authentication\Token\UsernamePasswordToken;
     use Symfony\Component\Security\Core\Encoder\UserPasswordEncoderInterface;
-    use Symfony\Component\Security\Core\Exception\AuthenticationException;
+    use Symfony\Component\Security\Core\Exception\CustomUserMessageAuthenticationException;
     use Symfony\Component\Security\Core\Exception\UsernameNotFoundException;
     use Symfony\Component\Security\Core\User\UserProviderInterface;
     use Symfony\Component\Security\Http\Authentication\SimpleFormAuthenticatorInterface;
@@ -58,15 +58,19 @@ the user::
             try {
                 $user = $userProvider->loadUserByUsername($token->getUsername());
             } catch (UsernameNotFoundException $e) {
-                throw new AuthenticationException('Invalid username or password');
+                // CAUTION: this message will be returned to the client
+                // (so don't put any un-trusted messages / error strings here)
+                throw new CustomUserMessageAuthenticationException('Invalid username or password');
             }
 
             $passwordValid = $this->encoder->isPasswordValid($user, $token->getCredentials());
 
             if ($passwordValid) {
                 $currentHour = date('G');
                 if ($currentHour < 14 || $currentHour > 16) {
-                    throw new AuthenticationException(
+                    // CAUTION: this message will be returned to the client
+                    // (so don't put any un-trusted messages / error strings here)
+                    throw new CustomUserMessageAuthenticationException(
                         'You can only log in between 2 and 4!',
                         100
                     );
@@ -80,7 +84,9 @@ the user::
                 );
             }
 
-            throw new AuthenticationException('Invalid username or password');
+            // CAUTION: this message will be returned to the client
+            // (so don't put any un-trusted messages / error strings here)
+            throw new CustomUserMessageAuthenticationException('Invalid username or password');
         }
 
         public function supportsToken(TokenInterface $token, $providerKey)
@@ -95,6 +101,11 @@ the user::
         }
     }
 
+.. versionadded:: 2.8
+    The ``CustomUserMessageAuthenticationException`` class is new in Symfony 2.8
+    and helps you return custom authentication messages. In 2.7 or earlier, throw
+    an ``AuthenticationException`` or any sub-class (you can still do this in 2.8).
+
 How it Works
 ------------
 

cookbook/security/entity_provider.rst

@@ -216,7 +216,7 @@ the username and then check the password (more on passwords in a moment):
                         # manager_name: customer
 
             firewalls:
-                default:
+                main:
                     pattern:    ^/
                     http_basic: ~
                     provider: our_db_provider
@@ -244,7 +244,7 @@ the username and then check the password (more on passwords in a moment):
                     <entity class="AppBundle:User" property="username" />
                 </provider>
 
-                <firewall name="default" pattern="^/" provider="our_db_provider">
+                <firewall name="main" pattern="^/" provider="our_db_provider">
                     <http-basic />
                 </firewall>
 
@@ -273,7 +273,7 @@ the username and then check the password (more on passwords in a moment):
                 ),
             ),
             'firewalls' => array(
-                'default' => array(
+                'main' => array(
                     'pattern'    => '^/',
                     'http_basic' => null,
                     'provider'   => 'our_db_provider',

cookbook/security/form_login_setup.rst

@@ -23,7 +23,7 @@ First, enable form login under your firewall:
             # ...
 
             firewalls:
-                default:
+                main:
                     anonymous: ~
                     form_login:
                         login_path: /login
@@ -40,7 +40,7 @@ First, enable form login under your firewall:
                 http://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <config>
-                <firewall name="default">
+                <firewall name="main">
                     <anonymous />
                     <form-login login-path="/login" check-path="/login_check" />
                 </firewall>
@@ -52,7 +52,7 @@ First, enable form login under your firewall:
         // app/config/security.php
         $container->loadFromExtension('security', array(
             'firewalls' => array(
-                'default' => array(
+                'main' => array(
                     'anonymous'  => null,
                     'form_login' => array(
                         'login_path' => '/login',

cookbook/security/remember_me.rst

@@ -19,7 +19,7 @@ the session lasts using a cookie with the ``remember_me`` firewall option:
             # ...
 
             firewalls:
-                default:
+                main:
                     # ...
                     remember_me:
                         secret:   "%secret%"
@@ -43,7 +43,7 @@ the session lasts using a cookie with the ``remember_me`` firewall option:
             <config>
                 <!-- ... -->
 
-                <firewall name="default">
+                <firewall name="main">
                     <!-- ... -->
 
                     <!-- 604800 is 1 week in seconds -->
@@ -65,7 +65,7 @@ the session lasts using a cookie with the ``remember_me`` firewall option:
             // ...
 
             'firewalls' => array(
-                'default' => array(
+                'main' => array(
                     // ...
                     'remember_me' => array(
                         'secret'   => '%secret%',