Merge branch '5.4' into 6.0

* 5.4:
  [Validator] Add attributes documentation of composite constraints
  Fix custom password hasher doc

Author: wouterj

reference/constraints/All.rst

@@ -36,6 +36,23 @@ entry in that array:
             protected $favoriteColors = [];
         }
 
+    .. code-block:: php-attributes
+
+        // src/Entity/User.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        // IMPORTANT: nested attributes requires PHP 8.1 or higher
+        class User
+        {
+            #[Assert\All([
+                new Assert\NotBlank,
+                new Assert\Length(min: 5),
+            ])]
+            protected $favoriteColors = [];
+        }
+
     .. code-block:: yaml
 
         # config/validator/validation.yaml
@@ -90,6 +107,11 @@ entry in that array:
             }
         }
 
+.. versionadded:: 5.4
+
+    The ``#[All]`` PHP attribute was introduced in Symfony 5.4 and requires
+    PHP 8.1 (which added nested attribute support).
+
 Now, each entry in the ``favoriteColors`` array will be validated to not
 be blank and to be at least 5 characters long.
 

reference/constraints/AtLeastOneOf.rst

@@ -50,6 +50,31 @@ The following constraints ensure that:
             protected $grades;
         }
 
+    .. code-block:: php-attributes
+
+        // src/Entity/Student.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        // IMPORTANT: nested attributes requires PHP 8.1 or higher
+        class Student
+        {
+            #[Assert\AtLeastOneOf([
+                new Assert\Regex('/#/'),
+                new Assert\Length(min: 10),
+            ])]
+            protected $plainPassword;
+
+            #[Assert\AtLeastOneOf([
+                new Assert\Count(min: 3),
+                new Assert\All(
+                    new Assert\GreaterThanOrEqual(5)
+                ),
+            ])]
+            protected $grades;
+        }
+
     .. code-block:: yaml
 
         # config/validator/validation.yaml
@@ -139,6 +164,11 @@ The following constraints ensure that:
             }
         }
 
+.. versionadded:: 5.4
+
+    The ``#[AtLeastOneOf]`` PHP attribute was introduced in Symfony 5.4 and
+    requires PHP 8.1 (which added nested attribute support).
+
 Options
 -------
 

reference/constraints/Collection.rst

@@ -81,6 +81,35 @@ following:
             ];
         }
 
+    .. code-block:: php-attributes
+
+        // src/Entity/Author.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        // IMPORTANT: nested attributes requires PHP 8.1 or higher
+        class Author
+        {
+            #[Assert\Collection(
+                fields: [
+                    'personal_email' => new Assert\Email,
+                    'short_bio' => [
+                        new Assert\NotBlank,
+                        new Assert\Length(
+                            max: 100,
+                            maxMessage: 'Your short bio is too long!'
+                        )
+                    ]
+                ],
+                allowMissingFields: true,
+            )]
+            protected $profileData = [
+                'personal_email' => '...',
+                'short_bio' => '...',
+            ];
+        }
+
     .. code-block:: yaml
 
         # config/validator/validation.yaml
@@ -155,6 +184,11 @@ following:
             }
         }
 
+.. versionadded:: 5.4
+
+    The ``#[Collection]`` PHP attribute was introduced in Symfony 5.4 and
+    requires PHP 8.1 (which added nested attribute support).
+
 Presence and Absence of Fields
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

reference/constraints/Sequentially.rst

@@ -60,6 +60,27 @@ You can validate each of these constraints sequentially to solve these issues:
             public $address;
         }
 
+    .. code-block:: php-attributes
+
+        // src/Localization/Place.php
+        namespace App\Localization;
+
+        use App\Validator\Constraints as AcmeAssert;
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        // IMPORTANT: nested attributes requires PHP 8.1 or higher
+        class Place
+        {
+            #[Assert\Sequentially([
+                new Assert\NotNull,
+                new Assert\Type('string'),
+                new Assert\Length(min: 10),
+                new Assert\Regex(Place::ADDRESS_REGEX),
+                new AcmeAssert\Geolocalizable,
+            ])]
+            public $address;
+        }
+
     .. code-block:: yaml
 
         # config/validator/validation.yaml
@@ -121,6 +142,11 @@ You can validate each of these constraints sequentially to solve these issues:
             }
         }
 
+.. versionadded:: 5.4
+
+    The ``#[Sequentially]`` PHP attribute was introduced in Symfony 5.4 and
+    requires PHP 8.1 (which added nested attribute support).
+
 Options
 -------
 

security/passwords.rst

@@ -770,12 +770,12 @@ Creating a custom Password Hasher
 
 If you need to create your own, it needs to follow these rules:
 
-#. The class must implement :class:`Symfony\\Component\\PasswordHasher\\Hasher\\UserPasswordHasherInterface`
-   (you can also extend :class:`Symfony\\Component\\PasswordHasher\\Hasher\\UserPasswordHasher`);
+#. The class must implement :class:`Symfony\\Component\\PasswordHasher\\PasswordHasherInterface`
+   (you can also implement :class:`Symfony\\Component\\PasswordHasher\\LegacyPasswordHasherInterface` if your hash algorithm uses a separate salt);
 
 #. The implementations of
-   :method:`Symfony\\Component\\PasswordHasher\\Hasher\\UserPasswordHasherInterface::hashPassword`
-   and :method:`Symfony\\Component\\PasswordHasher\\Hasher\\UserPasswordHasherInterface::isPasswordValid`
+   :method:`Symfony\\Component\\PasswordHasher\\PasswordHasherInterface::hash`
+   and :method:`Symfony\\Component\\PasswordHasher\\PasswordHasherInterface::verify`
    **must validate that the password length is no longer than 4096
    characters.** This is for security reasons (see `CVE-2013-5750`_).
 
@@ -784,31 +784,31 @@ If you need to create your own, it needs to follow these rules:
 
 .. code-block:: php
 
-    // src/Security/CustomVerySecureHasher.php
-    namespace App\Security;
+    // src/Security/Hasher/CustomVerySecureHasher.php
+    namespace App\Security\Hasher;
 
+    use Symfony\Component\PasswordHasher\Exception\InvalidPasswordException;
     use Symfony\Component\PasswordHasher\Hasher\CheckPasswordLengthTrait;
-    use Symfony\Component\PasswordHasher\Hasher\UserPasswordHasher;
-    use Symfony\Component\Security\Core\Exception\BadCredentialsException;
+    use Symfony\Component\PasswordHasher\PasswordHasherInterface;
 
-    class CustomVerySecureHasher extends UserPasswordHasher
+    class CustomVerySecureHasher implements PasswordHasherInterface
     {
         use CheckPasswordLengthTrait;
 
-        public function hashPassword(UserInterface $user, string $plainPassword): string
+        public function hash(string $plainPassword): string
         {
-            if ($this->isPasswordTooLong($user->getPassword())) {
-                throw new BadCredentialsException('Invalid password.');
+            if ($this->isPasswordTooLong($plainPassword)) {
+                throw new InvalidPasswordException();
             }
 
             // ... hash the plain password in a secure way
 
             return $hashedPassword;
         }
 
-        public function isPasswordValid(UserInterface $user, string $plainPassword): bool
+        public function verify(string $hashedPassword, string $plainPassword): bool
         {
-            if ($this->isPasswordTooLong($user->getPassword())) {
+            if ('' === $plainPassword || $this->isPasswordTooLong($plainPassword)) {
                 return false;
             }
 
@@ -849,21 +849,21 @@ Now, define a password hasher using the ``id`` setting:
                 <!-- ... -->
                 <!-- id: the service ID of your custom hasher (the FQCN using the default services.yaml) -->
                 <security:password_hasher class="app_hasher"
-                    id="App\Security\Hasher\MyCustomPasswordHasher"/>
+                    id="App\Security\Hasher\CustomVerySecureHasher"/>
             </config>
         </srv:container>
 
     .. code-block:: php
 
         // config/packages/security.php
-        use App\Security\Hasher\MyCustomPasswordHasher;
+        use App\Security\Hasher\CustomVerySecureHasher;
         use Symfony\Config\SecurityConfig;
 
         return static function (SecurityConfig $security) {
             // ...
             $security->passwordHasher('app_hasher')
                 // the service ID of your custom hasher (the FQCN using the default services.yaml)
-                ->id(MyCustomPasswordHasher::class)
+                ->id(CustomVerySecureHasher::class)
             ;
         };