From ec51dd2fa313eee56d302d8abc8aa0bd668417ea Mon Sep 17 00:00:00 2001 From: Florent Morselli Date: Sat, 25 Mar 2023 21:58:26 +0100 Subject: [PATCH] PasswordStrength Documentation pages --- reference/configuration/framework.rst | 8 ++ reference/constraints.rst | 1 + reference/constraints/Compound.rst | 1 + reference/constraints/PasswordStrength.rst | 126 +++++++++++++++++++++ reference/constraints/map.rst.inc | 1 + 5 files changed, 137 insertions(+) create mode 100644 reference/constraints/PasswordStrength.rst diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index b7170e37a0d..624bdc8658b 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -2587,6 +2587,14 @@ 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 ` +constraint verifies the submitted string entropy is matching the minimum entropy score. + .. _reference-validation-email_validation_mode: email_validation_mode diff --git a/reference/constraints.rst b/reference/constraints.rst index 67544bc45c3..d676e006f42 100644 --- a/reference/constraints.rst +++ b/reference/constraints.rst @@ -75,6 +75,7 @@ Validation Constraints Reference constraints/All constraints/UserPassword constraints/NotCompromisedPassword + constraints/PasswordStrength constraints/Valid constraints/Traverse constraints/CssColor diff --git a/reference/constraints/Compound.rst b/reference/constraints/Compound.rst index 695ae4f00ec..05109c4a184 100644 --- a/reference/constraints/Compound.rst +++ b/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]), ]; } } diff --git a/reference/constraints/PasswordStrength.rst b/reference/constraints/PasswordStrength.rst new file mode 100644 index 00000000000..2625cbc0f40 --- /dev/null +++ b/reference/constraints/PasswordStrength.rst @@ -0,0 +1,126 @@ +PasswordStrength +================ + +Validates that the given password has reached the minimum strength required by +the constraint. + +========== =================================================================== +Applies to :ref:`property or method ` +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 + + + + + + + + + + + + + .. 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 +----------------- + +``minScore`` +~~~~~~~~~~~~ + +**type**: ``integer`` **default**: ``PasswordStrength::STRENGTH_REASONABLE`` (``2``) + +The minimum required strength of the password. Available constants are: +* ``PasswordStrength::STRENGTH_WEAK`` = ``1`` +* ``PasswordStrength::STRENGTH_REASONABLE`` = ``2`` +* ``PasswordStrength::STRENGTH_STRONG`` = ``3`` +* ``PasswordStrength::STRENGTH_VERY_STRONG`` = ``4`` + +``PasswordStrength::STRENGTH_VERY_WEAK`` is available but only used internally +or by a custom password strength estimator. + +.. code-block:: php-attributes + + // src/Entity/User.php + namespace App\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class User + { + #[Assert\PasswordStrength([ + 'minScore' => PasswordStrength::STRENGTH_VERY_STRONG, // Very strong password required + ])] + protected $rawPassword; + } + +``message`` +~~~~~~~~~~~ + +**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. + +.. code-block:: php-attributes + + // src/Entity/User.php + namespace App\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class User + { + #[Assert\PasswordStrength([ + 'message' => 'Le mot de passe est trop faible. Veuillez utiliser un mot de passe plus fort.' + ])] + protected $rawPassword; + } diff --git a/reference/constraints/map.rst.inc b/reference/constraints/map.rst.inc index 1c16d47f81d..8689c88d9f0 100644 --- a/reference/constraints/map.rst.inc +++ b/reference/constraints/map.rst.inc @@ -28,6 +28,7 @@ String Constraints * :doc:`Ulid ` * :doc:`UserPassword ` * :doc:`NotCompromisedPassword ` +* :doc:`PasswordStrength ` * :doc:`CssColor ` * :doc:`NoSuspiciousCharacters `