Merge branch '4.1'

* 4.1:
  Add all serialized class properties
  Use version name in installer command
  Fix the page title for the mbstring polyfill
  Update tags declaration in yaml format
  Use the new Security helper in some code examples
  [Routing] add documentation for prefixing i18n routes with a locale

Author: javiereguiluz

components/polyfill_mbstring.rst

@@ -3,8 +3,8 @@
     single: Mbstring
     single: Components; Polyfill
 
-The Symfony Polyfill / Intl Mbstring Component
-==============================================
+The Symfony Polyfill / Mbstring Component
+=========================================
 
     This component provides a partial, native PHP implementation for the
     ``mbstring`` PHP extension.

components/serializer.rst

@@ -132,7 +132,7 @@ use the Serializer service created before::
 
     $jsonContent = $serializer->serialize($person, 'json');
 
-    // $jsonContent contains {"name":"foo","age":99,"sportsperson":false}
+    // $jsonContent contains {"name":"foo","age":99,"sportsperson":false,"createdAt":null}
 
     echo $jsonContent; // or return it in a Response
 

controller/argument_value_resolver.rst

@@ -91,16 +91,15 @@ retrieved from the token storage::
     use Symfony\Component\HttpFoundation\Request;
     use Symfony\Component\HttpKernel\Controller\ArgumentValueResolverInterface;
     use Symfony\Component\HttpKernel\ControllerMetadata\ArgumentMetadata;
-    use Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorageInterface;
-    use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
+    use Symfony\Component\Security\Core\Security;
 
     class UserValueResolver implements ArgumentValueResolverInterface
     {
-        private $tokenStorage;
+        private $security;
 
-        public function __construct(TokenStorageInterface $tokenStorage)
+        public function __construct(Security $security)
         {
-            $this->tokenStorage = $tokenStorage;
+            $this->security = $security;
         }
 
         public function supports(Request $request, ArgumentMetadata $argument)
@@ -109,27 +108,20 @@ retrieved from the token storage::
                 return false;
             }
 
-            $token = $this->tokenStorage->getToken();
-
-            if (!$token instanceof TokenInterface) {
-                return false;
-            }
-
-            return $token->getUser() instanceof User;
+            return $this->security->getUser() instanceof User;
         }
 
         public function resolve(Request $request, ArgumentMetadata $argument)
         {
-            yield $this->tokenStorage->getToken()->getUser();
+            yield $this->security->getUser();
         }
     }
 
 In order to get the actual ``User`` object in your argument, the given value
 must fulfill the following requirements:
 
 * An argument must be type-hinted as ``User`` in your action method signature;
-* A security token must be present;
-* The value must be an instance of the ``User``.
+* The value must be an instance of the ``User`` class.
 
 When all those requirements are met and ``true`` is returned, the
 ``ArgumentResolver`` calls ``resolve()`` with the same values as it called

form/dynamic_form_modification.rst

@@ -234,6 +234,7 @@ contains only this user's friends. This can be done injecting the ``Security``
 service into the form type so you can get the current user object::
 
     use Symfony\Component\Security\Core\Security;
+    // ...
 
     private $security;
 
@@ -254,7 +255,8 @@ service into the form type so you can get the current user object::
 Customizing the Form Type
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Now that you have all the basics in place you can complete the listener logic::
+Now that you have all the basics in place you can use the features of the
+security helper to fill in the listener logic::
 
     // src/Form/Type/FriendMessageFormType.php
 

routing.rst

@@ -210,6 +210,23 @@ should be used during the request. Defining routes this way also eliminated the
 need for duplicate registration of routes which minimizes the risk for any bugs
 caused by definition inconsistency.
 
+A common requirement for internationalized applications is to prefix all routes
+with a locale. This can be done by defining a different prefix for each locale
+(and setting an empty prefix for your default locale if you prefer it):
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/routes/annotations.yaml
+        controllers:
+            resource: '../src/Controller/'
+            type: annotation
+            prefix:
+                en: '' # don't prefix URLs for English, the default locale
+                fr: '/fr'
+                es: '/es'
+
 .. _routing-requirements:
 
 Adding {wildcard} Requirements

security.rst

@@ -1069,16 +1069,18 @@ the User object, and use the ``isGranted()`` method (or
 
     An alternative way to get the current user in a controller is to type-hint
     the controller argument with
-    :class:`Symfony\\Component\\Security\\Core\\User\\UserInterface`
-    (and default it to ``null`` if being logged-in is optional)::
+    :class:`Symfony\\Component\\Security\\Core\\Security`::
 
-        use Symfony\Component\Security\Core\User\UserInterface;
+        use Symfony\Component\Security\Core\Security;
 
-        public function index(UserInterface $user = null)
+        public function indexAction(Security $security)
         {
-            // $user is null when not logged-in or anon.
+            $user = $security->getUser();
         }
 
+    .. versionadded:: 3.4
+        The ``Security`` utility class was introduced in Symfony 3.4.
+
     This is only recommended for experienced developers who don't extend from the
     :ref:`Symfony base controller <the-base-controller-class-services>` and
     don't use the :class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\ControllerTrait`

security/impersonating_user.rst

@@ -108,25 +108,28 @@ over the user's roles until you find one that a ``SwitchUserRole`` object::
     use Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorageInterface;
     use Symfony\Component\Security\Core\Authorization\AuthorizationCheckerInterface;
     use Symfony\Component\Security\Core\Role\SwitchUserRole;
+    use Symfony\Component\Security\Core\Security;
+    // ...
 
-    private $authorizationChecker;
-    private $tokenStorage;
-
-    public function __construct(AuthorizationCheckerInterface $authorizationChecker, TokenStorageInterface $tokenStorage)
+    public class SomeService
     {
-        $this->authorizationChecker = $authorizationChecker;
-        $this->tokenStorage = $tokenStorage;
-    }
+        private $security;
 
-    public function someMethod()
-    {
-        // ...
+        public function __construct(Security $security)
+        {
+            $this->security = $security;
+        }
+
+        public function someMethod()
+        {
+            // ...
 
-        if ($authorizationChecker->isGranted('ROLE_PREVIOUS_ADMIN')) {
-            foreach ($tokenStorage->getToken()->getRoles() as $role) {
-                if ($role instanceof SwitchUserRole) {
-                    $impersonatorUser = $role->getSource()->getUser();
-                    break;
+            if ($this->security->isGranted('ROLE_PREVIOUS_ADMIN')) {
+                foreach ($this->security->getToken()->getRoles() as $role) {
+                    if ($role instanceof SwitchUserRole) {
+                        $impersonatorUser = $role->getSource()->getUser();
+                        break;
+                    }
                 }
             }
         }

security/securing_services.rst

@@ -44,28 +44,27 @@ Before you add security, the class looks something like this::
     }
 
 Your goal is to check the user's role when the ``sendNewsletter()`` method is
-called. The first step towards this is to inject the
-``Symfony\Component\Security\Core\Authorization\AuthorizationCheckerInterface``
-service into the object::
+called. The first step towards this is to inject the ``security.helper`` service
+using the :class:`Symfony\\Component\\Security\\Core\\Security` class::
 
     // src/Newsletter/NewsletterManager.php
 
     // ...
-    use Symfony\Component\Security\Core\Authorization\AuthorizationCheckerInterface;
     use Symfony\Component\Security\Core\Exception\AccessDeniedException;
+    use Symfony\Component\Security\Core\Security;
 
     class NewsletterManager
     {
-        protected $authChecker;
+        protected $security;
 
-        public function __construct(AuthorizationCheckerInterface $authChecker)
+        public function __construct(Security $security)
         {
-            $this->authChecker = $authChecker;
+            $this->security = $security;
         }
 
         public function sendNewsletter()
         {
-            if (!$this->authChecker->isGranted('ROLE_NEWSLETTER_ADMIN')) {
+            if (!$this->security->isGranted('ROLE_NEWSLETTER_ADMIN')) {
                 throw new AccessDeniedException();
             }
 
@@ -76,8 +75,8 @@ service into the object::
     }
 
 If you're using the :ref:`default services.yaml configuration <service-container-services-load-example>`,
-Symfony will automatically pass the authorization checker to your service
-thanks to autowiring and the ``AuthorizationCheckerInterface`` type-hint.
+Symfony will automatically pass the ``security.helper`` to your service
+thanks to autowiring and the ``Security`` type-hint.
 
 If the current user does not have the ``ROLE_NEWSLETTER_ADMIN``, they will
 be prompted to log in.

service_container/tags.rst

@@ -17,7 +17,7 @@ example:
         services:
             App\Twig\AppExtension:
                 public: false
-                tags: [twig.extension]
+                tags: ['twig.extension']
 
     .. code-block:: xml
 
@@ -162,10 +162,10 @@ For example, you may add the following transports as services:
         services:
             Swift_SmtpTransport:
                 arguments: ['%mailer_host%']
-                tags: [app.mail_transport]
+                tags: ['app.mail_transport']
 
             Swift_SendmailTransport:
-                tags: [app.mail_transport]
+                tags: ['app.mail_transport']
 
     .. code-block:: xml
 
@@ -317,11 +317,11 @@ To answer this, change the service declaration:
             Swift_SmtpTransport:
                 arguments: ['%mailer_host%']
                 tags:
-                    - { name: app.mail_transport, alias: smtp }
+                    - { name: 'app.mail_transport', alias: 'smtp' }
 
             Swift_SendmailTransport:
                 tags:
-                    - { name: app.mail_transport, alias: sendmail }
+                    - { name: 'app.mail_transport', alias: 'sendmail' }
 
     .. code-block:: xml
 
@@ -368,13 +368,13 @@ To answer this, change the service declaration:
             # Compact syntax
             Swift_SendmailTransport:
                 class: \Swift_SendmailTransport
-                tags: [app.mail_transport]
+                tags: ['app.mail_transport']
 
             # Verbose syntax
             Swift_SendmailTransport:
                 class: \Swift_SendmailTransport
                 tags:
-                    - { name: app.mail_transport }
+                    - { name: 'app.mail_transport' }
 
 Notice that you've added a generic ``alias`` key to the tag. To actually
 use this, update the compiler::
@@ -424,10 +424,10 @@ first  constructor argument to the ``App\HandlerCollection`` service:
         # config/services.yaml
         services:
             App\Handler\One:
-                tags: [app.handler]
+                tags: ['app.handler']
 
             App\Handler\Two:
-                tags: [app.handler]
+                tags: ['app.handler']
 
             App\HandlerCollection:
                 # inject all services tagged with app.handler as first argument
@@ -500,7 +500,7 @@ application handlers.
             services:
                 App\Handler\One:
                     tags:
-                        - { name: app.handler, priority: 20 }
+                        - { name: 'app.handler', priority: 20 }
 
         .. code-block:: xml
 

session/proxy_examples.rst

@@ -110,15 +110,15 @@ can intercept the session before it is written::
 
     use App\Entity\User;
     use Symfony\Component\HttpFoundation\Session\Storage\Proxy\SessionHandlerProxy;
-    use Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorageInterface;
+    use Symfony\Component\Security\Core\Security;
 
     class ReadOnlySessionProxy extends SessionHandlerProxy
     {
-        private $tokenStorage;
+        private $security;
 
-        public function __construct(\SessionHandlerInterface $handler, TokenStorageInterface $tokenStorage)
+        public function __construct(\SessionHandlerInterface $handler, Security $security)
         {
-            $this->tokenStorage = $tokenStorage;
+            $this->security = $security;
 
             parent::__construct($handler);
         }
@@ -134,11 +134,7 @@ can intercept the session before it is written::
 
         private function getUser()
         {
-            if (!$token = $this->tokenStorage->getToken()) {
-                return;
-            }
-
-            $user = $token->getUser();
+            $user = $this->security->getUser();
             if (is_object($user)) {
                 return $user;
             }