PasswordStrength Documentation pages

Author: Spomky

reference/configuration/framework.rst

@@ -2587,6 +2587,15 @@ metadata of the class. You can define an array of strings with the names of
 several methods. In that case, all of them will be called in that order to load
 the metadata.
 
+.. _reference-validation-password-strength:
+
+password_strength
+.................
+
+The :doc:`PasswordStrength </reference/constraints/PasswordStrength>`
+constraint verifies the submitted string entropy is matching the minimum entropy score.
+The strength of the password is measured using the external library `zxcvbn-php`_.
+
 .. _reference-validation-email_validation_mode:
 
 email_validation_mode
@@ -3688,3 +3697,4 @@ the ``#[WithLogLevel]`` attribute::
 .. _`utf-8 modifier`: https://www.php.net/reference.pcre.pattern.modifiers
 .. _`Link HTTP header`: https://tools.ietf.org/html/rfc5988
 .. _`SMTP session`: https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol#SMTP_transport_example
+.. _`zxcvbn-php`: https://github.com/bjeavons/zxcvbn-php

reference/constraints.rst

@@ -75,6 +75,7 @@ Validation Constraints Reference
    constraints/All
    constraints/UserPassword
    constraints/NotCompromisedPassword
+   constraints/PasswordStrength
    constraints/Valid
    constraints/Traverse
    constraints/CssColor

reference/constraints/Compound.rst

@@ -37,6 +37,7 @@ you can create your own named set or requirements to be reused consistently ever
                     new Assert\Type('string'),
                     new Assert\Length(['min' => 12]),
                     new Assert\NotCompromisedPassword(),
+                    new Assert\PasswordStrength(['minScore' => 4]),
                 ];
             }
         }

reference/constraints/PasswordStrength.rst

@@ -0,0 +1,103 @@
+PasswordStrength
+================
+
+Validates that the given password has reached the minimum strength required by
+the constraint. The strength is measured using the `zxcvbn-php`_. library.
+
+==========  ===================================================================
+Applies to  :ref:`property or method <validation-property-target>`
+Class       :class:`Symfony\\Component\\Validator\\Constraints\\PasswordStrength`
+Validator   :class:`Symfony\\Component\\Validator\\Constraints\\PasswordStrengthValidator`
+==========  ===================================================================
+
+Basic Usage
+-----------
+
+The following constraint ensures that the ``rawPassword`` property of the
+``User`` class reaches the minimum strength required by the constraint.
+By default, the minimum required score is 2.
+
+.. configuration-block::
+
+    .. code-block:: php-attributes
+
+        // src/Entity/User.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class User
+        {
+            #[Assert\PasswordStrength]
+            protected $rawPassword;
+        }
+
+    .. code-block:: yaml
+
+        # config/validator/validation.yaml
+        App\Entity\User:
+            properties:
+                rawPassword:
+                    - PasswordStrength
+
+    .. code-block:: xml
+
+        <!-- config/validator/validation.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+
+            <class name="App\Entity\User">
+                <property name="rawPassword">
+                    <constraint name="PasswordStrength"></constraint>
+                </property>
+            </class>
+        </constraint-mapping>
+
+    .. code-block:: php
+
+        // src/Entity/User.php
+        namespace App\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+
+        class User
+        {
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('rawPassword', new Assert\PasswordStrength());
+            }
+        }
+
+Available Options
+-----------------
+
+.. include:: /reference/constraints/_groups-option.rst.inc
+
+``lowStrengthMessage``
+~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``The password strength is too low. Please use a stronger password.``
+
+The default message supplied when the password does not reach the minimum required score.
+
+.. include:: /reference/constraints/_payload-option.rst.inc
+
+``restrictedData``
+~~~~~~~~~~~~~~~
+
+**type**: ``string[]`` **default**: ``[]``
+
+It is possible to determine if the submitted password contains restricted data
+such as the user given/family name,
+
+``restrictedDataMessage``
+~~~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``The password contains the following restricted data: {{ wordList }}.``
+
+The default message supplied when the password contains at least one restricted data.
+
+.. _`zxcvbn-php`: https://github.com/bjeavons/zxcvbn-php

reference/constraints/map.rst.inc

@@ -28,6 +28,7 @@ String Constraints
 * :doc:`Ulid </reference/constraints/Ulid>`
 * :doc:`UserPassword </reference/constraints/UserPassword>`
 * :doc:`NotCompromisedPassword </reference/constraints/NotCompromisedPassword>`
+* :doc:`PasswordStrength </reference/constraints/PasswordStrength>`
 * :doc:`CssColor </reference/constraints/CssColor>`
 * :doc:`NoSuspiciousCharacters </reference/constraints/NoSuspiciousCharacters>`