symfony · nicolas-grekas · Jan 5, 2024 · Oct 11, 2023
diff --git a/src/Symfony/Component/Validator/Attribute/HasNamedArguments.php b/src/Symfony/Component/Validator/Attribute/HasNamedArguments.php
@@ -11,6 +11,11 @@

 namespace Symfony\Component\Validator\Attribute;

+/**
+ * Hints the loader that some constraint options are required.
+ *
+ * @see https://symfony.com/doc/current/validation/custom_constraint.html
+ */
 #[\Attribute(\Attribute::TARGET_METHOD)]
 final class HasNamedArguments
 {

diff --git a/src/Symfony/Component/Validator/Constraints/All.php b/src/Symfony/Component/Validator/Constraints/All.php
@@ -14,13 +14,20 @@
 use Symfony\Component\Validator\Constraint;

 /**
+ * When applied to an array (or Traversable object), this constraint allows you to apply
+ * a collection of constraints to each element of the array.
+ *
 * @author Bernhard Schussek <bschussek@gmail.com>
 */
 #[\Attribute(\Attribute::TARGET_PROPERTY | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
 class All extends Composite
 {
    public array|Constraint $constraints = [];

+    /**
+     * @param array<Constraint>|array<string,mixed>|null $constraints
+     * @param string[]|null                              $groups
+     */
    public function __construct(mixed $constraints = null, array $groups = null, mixed $payload = null)
    {
        parent::__construct($constraints ?? [], $groups, $payload);

diff --git a/src/Symfony/Component/Validator/Constraints/AtLeastOneOf.php b/src/Symfony/Component/Validator/Constraints/AtLeastOneOf.php
@@ -14,6 +14,8 @@
 use Symfony\Component\Validator\Constraint;

 /**
+ * Checks that at least one of the given constraint is satisfied.
+ *
 * @author Przemysław Bogusz <przemyslaw.bogusz@tubotax.pl>
 */
 #[\Attribute(\Attribute::TARGET_PROPERTY | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
@@ -30,6 +32,13 @@ class AtLeastOneOf extends Composite
    public string $messageCollection = 'Each element of this collection should satisfy its own set of constraints.';
    public bool $includeInternalMessages = true;

+    /**
+     * @param array<Constraint>|array<string,mixed>|null $constraints             An array of validation constraints
+     * @param string[]|null                              $groups
+     * @param string|null                                $message                 Intro of the failure message that will be followed by the failed constraint(s) message(s)
+     * @param string|null                                $messageCollection       Failure message for All and Collection inner constraints
+     * @param bool|null                                  $includeInternalMessages Whether to include inner constraint messages (defaults to true)
+     */
    public function __construct(mixed $constraints = null, array $groups = null, mixed $payload = null, string $message = null, string $messageCollection = null, bool $includeInternalMessages = null)
    {
        parent::__construct($constraints ?? [], $groups, $payload);

diff --git a/src/Symfony/Component/Validator/Constraints/Bic.php b/src/Symfony/Component/Validator/Constraints/Bic.php
@@ -18,6 +18,10 @@
 use Symfony\Component\Validator\Exception\LogicException;

 /**
+ * Ensures that the value is valid against the BIC format.
+ *
+ * @see https://en.wikipedia.org/wiki/ISO_9362
+ *
 * @author Michael Hirschler <michael.vhirsch@gmail.com>
 */
 #[\Attribute(\Attribute::TARGET_PROPERTY | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
@@ -43,6 +47,12 @@ class Bic extends Constraint
    public ?string $iban = null;
    public ?string $ibanPropertyPath = null;

+    /**
+     * @param array<string,mixed>|null $options
+     * @param string|null              $iban             An IBAN value to validate that its country code is the same as the BIC's one
+     * @param string|null              $ibanPropertyPath Property path to the IBAN value when validating objects
+     * @param string[]|null            $groups
+     */
    public function __construct(array $options = null, string $message = null, string $iban = null, string $ibanPropertyPath = null, string $ibanMessage = null, array $groups = null, mixed $payload = null)
    {
        if (!class_exists(Countries::class)) {

diff --git a/src/Symfony/Component/Validator/Constraints/Blank.php b/src/Symfony/Component/Validator/Constraints/Blank.php
@@ -14,6 +14,8 @@
 use Symfony\Component\Validator\Constraint;

 /**
+ * Validates that a value is blank, i.e. an empty string or null.
+ *
 * @author Bernhard Schussek <bschussek@gmail.com>
 */
 #[\Attribute(\Attribute::TARGET_PROPERTY | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
@@ -27,6 +29,10 @@ class Blank extends Constraint

    public string $message = 'This value should be blank.';

+    /**
+     * @param array<string,mixed>|null $options
+     * @param string[]|null            $groups
+     */
    public function __construct(array $options = null, string $message = null, array $groups = null, mixed $payload = null)
    {
        parent::__construct($options ?? [], $groups, $payload);

diff --git a/src/Symfony/Component/Validator/Constraints/Callback.php b/src/Symfony/Component/Validator/Constraints/Callback.php
@@ -14,6 +14,8 @@
 use Symfony\Component\Validator\Constraint;

 /**
+ * Defines custom validation rules through arbitrary callback methods.
+ *
 * @author Bernhard Schussek <bschussek@gmail.com>
 */
 #[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_PROPERTY | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
@@ -24,6 +26,10 @@ class Callback extends Constraint
     */
    public $callback;

+    /**
+     * @param string|string[]|callable|array<string,mixed>|null $callback The callback definition
+     * @param string[]|null                                     $groups
+     */
    public function __construct(array|string|callable $callback = null, array $groups = null, mixed $payload = null, array $options = [])
    {
        // Invocation through attributes with an array parameter only

diff --git a/src/Symfony/Component/Validator/Constraints/CardScheme.php b/src/Symfony/Component/Validator/Constraints/CardScheme.php
@@ -14,7 +14,7 @@
 use Symfony\Component\Validator\Constraint;

 /**
- * Metadata for the CardSchemeValidator.
+ * Validates a credit card number for a given credit card company.
 *
 * @author Tim Nagel <t.nagel@infinite.net.au>
 * @author Bernhard Schussek <bschussek@gmail.com>
@@ -46,6 +46,11 @@ class CardScheme extends Constraint
    public string $message = 'Unsupported card type or invalid card number.';
    public array|string|null $schemes = null;

+    /**
+     * @param string|string[]|array<string,mixed>|null $schemes Name(s) of the number scheme(s) used to validate the credit card number
+     * @param string[]|null                            $groups
+     * @param array<string,mixed>                      $options
+     */
    public function __construct(array|string|null $schemes, string $message = null, array $groups = null, mixed $payload = null, array $options = [])
    {
        if (\is_array($schemes) && \is_string(key($schemes))) {

diff --git a/src/Symfony/Component/Validator/Constraints/Cascade.php b/src/Symfony/Component/Validator/Constraints/Cascade.php
@@ -15,13 +15,19 @@
 use Symfony\Component\Validator\Exception\ConstraintDefinitionException;

 /**
+ * Validates a whole class, including nested objects in properties.
+ *
 * @author Jules Pietri <jules@heahprod.com>
 */
 #[\Attribute(\Attribute::TARGET_CLASS)]
 class Cascade extends Constraint
 {
    public array $exclude = [];

+    /**
+     * @param string[]|string|array<string,mixed>|null $exclude Properties excluded from validation
+     * @param array<string,mixed>|null                 $options
+     */
    public function __construct(array|string $exclude = null, array $options = null)
    {
        if (\is_array($exclude) && !array_is_list($exclude)) {

diff --git a/src/Symfony/Component/Validator/Constraints/Choice.php b/src/Symfony/Component/Validator/Constraints/Choice.php
@@ -14,6 +14,8 @@
 use Symfony\Component\Validator\Constraint;

 /**
+ * Validates that a value is one of a given set of valid choices.
+ *
 * @author Bernhard Schussek <bschussek@gmail.com>
 */
 #[\Attribute(\Attribute::TARGET_PROPERTY | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
@@ -47,6 +49,16 @@ public function getDefaultOption(): ?string
        return 'choices';
    }

+    /**
+     * @param array|null           $choices  An array of choices (required unless a callback is specified)
+     * @param callable|string|null $callback Callback method to use instead of the choice option to get the choices
+     * @param bool|null            $multiple Whether to expect the value to be an array of valid choices (defaults to false)
+     * @param bool|null            $strict   This option defaults to true and should not be used
+     * @param int|null             $min      Minimum of valid choices if multiple values are expected
+     * @param int|null             $max      Maximum of valid choices if multiple values are expected
+     * @param string[]|null        $groups
+     * @param bool|null            $match    Whether to validate the values are part of the choices or not (defaults to true)
+     */
    public function __construct(
        string|array $options = [],
        array $choices = null,

diff --git a/src/Symfony/Component/Validator/Constraints/Cidr.php b/src/Symfony/Component/Validator/Constraints/Cidr.php
@@ -17,6 +17,8 @@
 /**
 * Validates that a value is a valid CIDR notation.
 *
+ * @see https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing
+ *
 * @author Sorin Pop <popsorin15@gmail.com>
 * @author Calin Bolea <calin.bolea@gmail.com>
 */
@@ -43,6 +45,13 @@ class Cidr extends Constraint
    public int $netmaskMin = 0;
    public int $netmaskMax;

+    /**
+     * @param array<string,mixed>|null $options
+     * @param string|null              $version    The CIDR version to validate (4, 6 or all, defaults to all)
+     * @param int|null                 $netmaskMin The lowest valid for a valid netmask (defaults to 0)
+     * @param int|null                 $netmaskMax The biggest valid for a valid netmask (defaults to 32 for IPv4, 128 for IPv6)
+     * @param string[]|null            $groups
+     */
    public function __construct(
        array $options = null,
        string $version = null,

diff --git a/src/Symfony/Component/Validator/Constraints/Collection.php b/src/Symfony/Component/Validator/Constraints/Collection.php
@@ -14,6 +14,8 @@
 use Symfony\Component\Validator\Constraint;

 /**
+ * Validates a collection with constraints defined for specific keys.
+ *
 * @author Bernhard Schussek <bschussek@gmail.com>
 */
 #[\Attribute(\Attribute::TARGET_PROPERTY | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
@@ -33,7 +35,13 @@ class Collection extends Composite
    public string $extraFieldsMessage = 'This field was not expected.';
    public string $missingFieldsMessage = 'This field is missing.';

-    public function __construct(array $fields = null, array $groups = null, mixed $payload = null, bool $allowExtraFields = null, bool $allowMissingFields = null, string $extraFieldsMessage = null, string $missingFieldsMessage = null)
+    /**
+     * @param array<string,Constraint>|array<string,mixed>|null $fields             An associative array defining keys in the collection and their constraints
+     * @param string[]|null                                     $groups
+     * @param bool|null                                         $allowExtraFields   Whether to allow additional keys not declared in the configured fields (defaults to false)
+     * @param bool|null                                         $allowMissingFields Whether to allow the collection to lack some fields declared in the configured fields (defaults to false)
+     */
+    public function __construct(mixed $fields = null, array $groups = null, mixed $payload = null, bool $allowExtraFields = null, bool $allowMissingFields = null, string $extraFieldsMessage = null, string $missingFieldsMessage = null)
    {
        if (\is_array($fields)
            && (($firstField = reset($fields)) instanceof Constraint

diff --git a/src/Symfony/Component/Validator/Constraints/Count.php b/src/Symfony/Component/Validator/Constraints/Count.php
@@ -15,6 +15,8 @@
 use Symfony\Component\Validator\Exception\MissingOptionsException;

 /**
+ * Validates a collection's element count.
+ *
 * @author Bernhard Schussek <bschussek@gmail.com>
 */
 #[\Attribute(\Attribute::TARGET_PROPERTY | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
@@ -40,6 +42,14 @@ class Count extends Constraint
    public ?int $max = null;
    public ?int $divisibleBy = null;

+    /**
+     * @param int|array<string,mixed>|null $exactly     The exact expected number of elements
+     * @param int|null                     $min         Minimum expected number of elements
+     * @param int|null                     $max         Maximum expected number of elements
+     * @param int|null                     $divisibleBy The number the collection count should be divisible by
+     * @param string[]|null                $groups
+     * @param array<mixed,string>          $options
+     */
    public function __construct(
        int|array $exactly = null,
        int $min = null,

diff --git a/src/Symfony/Component/Validator/Constraints/Country.php b/src/Symfony/Component/Validator/Constraints/Country.php
@@ -16,6 +16,10 @@
 use Symfony\Component\Validator\Exception\LogicException;

 /**
+ * Validates a value is a valid ISO 3166-1 alpha-2 country code.
+ *
+ * @see https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes
+ *
 * @author Bernhard Schussek <bschussek@gmail.com>
 */
 #[\Attribute(\Attribute::TARGET_PROPERTY | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
@@ -30,6 +34,13 @@ class Country extends Constraint
    public string $message = 'This value is not a valid country.';
    public bool $alpha3 = false;

+    /**
+     * @param array<string,mixed>|null $options
+     * @param bool|null                $alpha3  Whether to check for alpha-3 codes instead of alpha-2 (defaults to false)
+     * @param string[]|null            $groups
+     *
+     * @see https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Current_codes
+     */
    public function __construct(
        array $options = null,
        string $message = null,

diff --git a/src/Symfony/Component/Validator/Constraints/CssColor.php b/src/Symfony/Component/Validator/Constraints/CssColor.php
@@ -15,6 +15,8 @@
 use Symfony\Component\Validator\Exception\InvalidArgumentException;

 /**
+ * Validates that a value is a valid CSS color.
+ *
 * @author Mathieu Santostefano <msantostefano@protonmail.com>
 */
 #[\Attribute(\Attribute::TARGET_PROPERTY | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
@@ -60,7 +62,9 @@ class CssColor extends Constraint
    public array|string $formats;

    /**
-     * @param array|string $formats The types of CSS colors allowed (e.g. hexadecimal only, RGB and HSL only, etc.).
+     * @param string[]|string|array<string,mixed> $formats The types of CSS colors allowed ({@see https://symfony.com/doc/current/reference/constraints/CssColor.html#formats})
+     * @param string[]|null                       $groups
+     * @param array<string,mixed>|null            $options
     */
    public function __construct(array|string $formats = [], string $message = null, array $groups = null, $payload = null, array $options = null)
    {

diff --git a/src/Symfony/Component/Validator/Constraints/Currency.php b/src/Symfony/Component/Validator/Constraints/Currency.php
@@ -16,6 +16,10 @@
 use Symfony\Component\Validator\Exception\LogicException;

 /**
+ * Validates that a value is a valid 3-letter ISO 4217 currency name.
+ *
+ * @see https://en.wikipedia.org/wiki/ISO_4217
+ *
 * @author Miha Vrhovnik <miha.vrhovnik@pagein.si>
 * @author Bernhard Schussek <bschussek@gmail.com>
 */
@@ -30,6 +34,10 @@ class Currency extends Constraint

    public string $message = 'This value is not a valid currency.';

+    /**
+     * @param array<string,mixed>|null $options
+     * @param string[]|null            $groups
+     */
    public function __construct(array $options = null, string $message = null, array $groups = null, mixed $payload = null)
    {
        if (!class_exists(Currencies::class)) {

diff --git a/src/Symfony/Component/Validator/Constraints/Date.php b/src/Symfony/Component/Validator/Constraints/Date.php
@@ -14,6 +14,10 @@
 use Symfony\Component\Validator\Constraint;

 /**
+ * Validates that a value is a valid date, i.e. its string representation follows the Y-m-d format.
+ *
+ * @see https://www.php.net/manual/en/datetime.format.php
+ *
 * @author Bernhard Schussek <bschussek@gmail.com>
 */
 #[\Attribute(\Attribute::TARGET_PROPERTY | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
@@ -29,6 +33,10 @@ class Date extends Constraint

    public string $message = 'This value is not a valid date.';

+    /**
+     * @param array<string,mixed>|null $options
+     * @param string[]|null            $groups
+     */
    public function __construct(array $options = null, string $message = null, array $groups = null, mixed $payload = null)
    {
        parent::__construct($options, $groups, $payload);

diff --git a/src/Symfony/Component/Validator/Constraints/DateTime.php b/src/Symfony/Component/Validator/Constraints/DateTime.php
@@ -14,6 +14,10 @@
 use Symfony\Component\Validator\Constraint;

 /**
+ * Validates that a value is a valid "datetime" according to a given format.
+ *
+ * @see https://www.php.net/manual/en/datetime.format.php
+ *
 * @author Bernhard Schussek <bschussek@gmail.com>
 */
 #[\Attribute(\Attribute::TARGET_PROPERTY | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
@@ -32,6 +36,11 @@ class DateTime extends Constraint
    public string $format = 'Y-m-d H:i:s';
    public string $message = 'This value is not a valid datetime.';

+    /**
+     * @param string|array<string,mixed>|null $format  The datetime format to match (defaults to 'Y-m-d H:i:s')
+     * @param string[]|null                   $groups
+     * @param array<string,mixed>             $options
+     */
    public function __construct(string|array $format = null, string $message = null, array $groups = null, mixed $payload = null, array $options = [])
    {
        if (\is_array($format)) {

diff --git a/src/Symfony/Component/Validator/Constraints/DisableAutoMapping.php b/src/Symfony/Component/Validator/Constraints/DisableAutoMapping.php
@@ -25,6 +25,9 @@
 #[\Attribute(\Attribute::TARGET_PROPERTY | \Attribute::TARGET_METHOD | \Attribute::TARGET_CLASS)]
 class DisableAutoMapping extends Constraint
 {
+    /**
+     * @param array<string,mixed>|null $options
+     */
    public function __construct(array $options = null)
    {
        if (\is_array($options) && \array_key_exists('groups', $options)) {

diff --git a/src/Symfony/Component/Validator/Constraints/DivisibleBy.php b/src/Symfony/Component/Validator/Constraints/DivisibleBy.php
@@ -12,6 +12,8 @@
 namespace Symfony\Component\Validator\Constraints;

 /**
+ * Validates that a value is divisible by another value.
+ *
 * @author Colin O'Dell <colinodell@gmail.com>
 */
 #[\Attribute(\Attribute::TARGET_PROPERTY | \Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]