Merge branch '5.2' into 5.x

* 5.2:
  Update setup page for Symfony 5.1 - add version
  Update setup page for Symfony 5.2 - drop dev
  [#14671] Added example of inline host defaults/requirements
  [#14672] Updated more docs related to the UserBadge
  Update experimental_authenticators : add UserBadge
  Document routing inline requirements and defaults for host

Author: wouterj

routing.rst

@@ -2036,6 +2036,16 @@ these routes.
             // ['HTTP_HOST' => 'm.' . $client->getContainer()->getParameter('domain')]
         );
 
+.. tip::
+
+    You can also use the inline defaults and requirements format in the
+    ``host`` option: ``{subdomain<m|mobile>?m}.example.com``
+
+.. versionadded:: 5.2
+
+    Inline parameter default values support in hosts were introduced in
+    Symfony 5.2. Prior to Symfony 5.2, they were supported in the path only.
+
 .. _i18n-routing:
 
 Localized Routes (i18n)

security/experimental_authenticators.rst

@@ -295,8 +295,8 @@ method that fits most use-cases::
     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\UsernameNotFoundException;
     use Symfony\Component\Security\Http\Authenticator\AbstractAuthenticator;
+    use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
     use Symfony\Component\Security\Http\Authenticator\Passport\PassportInterface;
     use Symfony\Component\Security\Http\Authenticator\Passport\SelfValidatingPassport;
 
@@ -328,14 +328,7 @@ method that fits most use-cases::
                 throw new CustomUserMessageAuthenticationException('No API token provided');
             }
 
-            $user = $this->entityManager->getRepository(User::class)
-                ->findOneBy(['apiToken' => $apiToken])
-            ;
-            if (null === $user) {
-                throw new UsernameNotFoundException();
-            }
-
-            return new SelfValidatingPassport($user);
+            return new SelfValidatingPassport(new UserBadge($apiToken));
         }
 
         public function onAuthenticationSuccess(Request $request, TokenInterface $token, string $firewallName): ?Response
@@ -442,23 +435,61 @@ into a security
 Security Passports
 ~~~~~~~~~~~~~~~~~~
 
+.. versionadded:: 5.2
+
+    The ``UserBadge`` was introduced in Symfony 5.2. Prior to 5.2, the user
+    instance was provided directly to the passport.
+
 A passport is an object that contains the user that will be authenticated as
 well as other pieces of information, like whether a password should be checked
 or if "remember me" functionality should be enabled.
 
 The default
 :class:`Symfony\\Component\\Security\\Http\\Authenticator\\Passport\\Passport`
-requires a user object and credentials. The following credential classes
-are supported by default:
+requires a user and credentials.
+
+Use the
+:class:`Symfony\\Component\\Security\\Http\\Authenticator\\Passport\\Badge\\UserBadge`
+to attach the user to the passport. The ``UserBadge`` requires a user
+identifier (e.g. the username or email), which is used to load the user
+using :ref:`the user provider <security-user-providers>`::
 
+    use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
+
+    // ...
+    $passport = new Passport(new UserBadge($email), $credentials);
+
+.. note::
+
+    You can optionally pass a user loader as second argument to the
+    ``UserBadge``. This callable receives the ``$userIdentifier``
+    and must return a ``UserInterface`` object (otherwise a
+    ``UsernameNotFoundException`` is thrown)::
+
+        // ...
+        $passport = new Passport(
+            new UserBadge($email, function ($userIdentifier) {
+                return $this->userRepository->findOneBy(['email' => $userIdentifier]);
+            }),
+            $credentials
+        );
+
+The following credential classes are supported by default:
 
 :class:`Symfony\\Component\\Security\\Http\\Authenticator\\Passport\\Credentials\\PasswordCredentials`
     This requires a plaintext ``$password``, which is validated using the
-    :ref:`password encoder configured for the user <security-encoding-user-password>`.
+    :ref:`password encoder configured for the user <security-encoding-user-password>`::
+
+        use Symfony\Component\Security\Http\Authenticator\Passport\Credentials\PasswordCredentials;
+
+        // ...
+        return new Passport($user, new PasswordCredentials($plaintextPassword));
 
 :class:`Symfony\\Component\\Security\\Http\\Authenticator\\Passport\\Credentials\\CustomCredentials`
     Allows a custom closure to check credentials::
 
+        use Symfony\Component\Security\Http\Authenticator\Passport\Credentials\CustomCredentials;
+
         // ...
         return new Passport($user, new CustomCredentials(
             // If this function returns anything else than `true`, the credentials
@@ -472,12 +503,15 @@ are supported by default:
             $apiToken
         ));
 
-.. note::
 
-    If you don't need any credentials to be checked (e.g. a JWT token), you
-    can use the
-    :class:`Symfony\\Component\\Security\\Http\\Authenticator\\Passport\\SelfValidatingPassport`.
-    This class only requires a user and optionally `Passport Badges`_.
+Self Validating Passport
+........................
+
+If you don't need any credentials to be checked (e.g. when using API
+tokens), you can use the
+:class:`Symfony\\Component\\Security\\Http\\Authenticator\\Passport\\SelfValidatingPassport`.
+This class only requires a ``UserBadge`` object and optionally `Passport
+Badges`_.
 
 Passport Badges
 ~~~~~~~~~~~~~~~
@@ -507,16 +541,21 @@ the following badges are supported:
     initiated). This skips the
     :doc:`pre-authentication user checker </security/user_checkers>`.
 
-For instance, if you want to add CSRF and password migration to your custom
-authenticator, you would initialize the passport like this::
+.. versionadded:: 5.2
+
+    Since 5.2, the ``PasswordUpgradeBadge`` is automatically added to
+    the passport if the passport has ``PasswordCredentials``.
+
+For instance, if you want to add CSRF to your custom authenticator, you
+would initialize the passport like this::
 
     // src/Service/LoginAuthenticator.php
     namespace App\Service;
 
     // ...
     use Symfony\Component\Security\Http\Authenticator\AbstractAuthenticator;
     use Symfony\Component\Security\Http\Authenticator\Passport\Badge\CsrfTokenBadge;
-    use Symfony\Component\Security\Http\Authenticator\Passport\Badge\PasswordUpgradeBadge;
+    use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
     use Symfony\Component\Security\Http\Authenticator\Passport\Passport;
     use Symfony\Component\Security\Http\Authenticator\Passport\PassportInterface;
 
@@ -528,14 +567,13 @@ authenticator, you would initialize the passport like this::
             $username = $request->request->get('username');
             $csrfToken = $request->request->get('csrf_token');
 
-            // ... get the $user from the $username and validate no
-            // parameter is empty
+            // ... validate no parameter is empty
 
-            return new Passport($user, new PasswordCredentials($password), [
-                // $this->userRepository must implement PasswordUpgraderInterface
-                new PasswordUpgradeBadge($password, $this->userRepository),
-                new CsrfTokenBadge('login', $csrfToken),
-            ]);
+            return new Passport(
+                new UserBadge($user),
+                new PasswordCredentials($password),
+                [new CsrfTokenBadge('login', $csrfToken)]
+            );
         }
     }
 
@@ -547,7 +585,7 @@ authenticator, you would initialize the passport like this::
     ``createAuthenticatedToken()``)::
 
         // ...
-        use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
+        use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
 
         class LoginAuthenticator extends AbstractAuthenticator
         {
@@ -557,7 +595,7 @@ authenticator, you would initialize the passport like this::
             {
                 // ... process the request
 
-                $passport = new SelfValidatingPassport($username, []);
+                $passport = new SelfValidatingPassport(new UserBadge($username), []);
 
                 // set a custom attribute (e.g. scope)
                 $passport->setAttribute('scope', $oauthScope);

setup.rst

@@ -50,10 +50,10 @@ application:
 .. code-block:: terminal
 
     # run this if you are building a traditional web application
-    $ symfony new my_project_name --version=next --full
+    $ symfony new my_project_name --full
 
     # run this if you are building a microservice, console application or API
-    $ symfony new my_project_name --version=next
+    $ symfony new my_project_name
 
 The only difference between these two commands is the number of packages
 installed by default. The ``--full`` option installs all the packages that you
@@ -65,10 +65,10 @@ Symfony application using Composer:
 .. code-block:: terminal
 
     # run this if you are building a traditional web application
-    $ composer create-project symfony/website-skeleton:"5.2.x@dev" my_project_name
+    $ composer create-project symfony/website-skeleton my_project_name
 
     # run this if you are building a microservice, console application or API
-    $ composer create-project symfony/skeleton:"5.2.x@dev" my_project_name
+    $ composer create-project symfony/skeleton my_project_name
 
 No matter which command you run to create the Symfony application. All of them
 will create a new ``my_project_name/`` directory, download some dependencies