vendor/symfony/validator/Constraint.php line 120

  1. <?php
  3. /*
  4.  * This file is part of the Symfony package.
  5.  *
  6.  * (c) Fabien Potencier <fabien@symfony.com>
  7.  *
  8.  * For the full copyright and license information, please view the LICENSE
  9.  * file that was distributed with this source code.
  10.  */
  12. namespace Symfony\Component\Validator;
  14. use Symfony\Component\Validator\Exception\ConstraintDefinitionException;
  15. use Symfony\Component\Validator\Exception\InvalidArgumentException;
  16. use Symfony\Component\Validator\Exception\InvalidOptionsException;
  17. use Symfony\Component\Validator\Exception\MissingOptionsException;
  19. /**
  20.  * Contains the properties of a constraint definition.
  21.  *
  22.  * A constraint can be defined on a class, a property or a getter method.
  23.  * The Constraint class encapsulates all the configuration required for
  24.  * validating this class, property or getter result successfully.
  25.  *
  26.  * Constraint instances are immutable and serializable.
  27.  *
  28.  * @author Bernhard Schussek <bschussek@gmail.com>
  29.  */
  30. abstract class Constraint
  31. {
  32.     /**
  33.      * The name of the group given to all constraints with no explicit group.
  34.      */
  35.     public const DEFAULT_GROUP = 'Default';
  37.     /**
  38.      * Marks a constraint that can be put onto classes.
  39.      */
  40.     public const CLASS_CONSTRAINT = 'class';
  42.     /**
  43.      * Marks a constraint that can be put onto properties.
  44.      */
  45.     public const PROPERTY_CONSTRAINT = 'property';
  47.     /**
  48.      * Maps error codes to the names of their constants.
  49.      */
  50.     protected const ERROR_NAMES = [];
  52.     /**
  53.      * @deprecated since Symfony 6.1, use protected const ERROR_NAMES instead
  54.      */
  55.     protected static $errorNames = [];
  57.     /**
  58.      * Domain-specific data attached to a constraint.
  59.      *
  60.      * @var mixed
  61.      */
  62.     public $payload;
  64.     /**
  65.      * The groups that the constraint belongs to.
  66.      *
  67.      * @var string[]
  68.      */
  69.     public $groups;
  71.     /**
  72.      * Returns the name of the given error code.
  73.      *
  74.      * @throws InvalidArgumentException If the error code does not exist
  75.      */
  76.     public static function getErrorName(string $errorCode): string
  77.     {
  78.         if (isset(static::ERROR_NAMES[$errorCode])) {
  79.             return static::ERROR_NAMES[$errorCode];
  80.         }
  82.         if (!isset(static::$errorNames[$errorCode])) {
  83.             throw new InvalidArgumentException(sprintf('The error code "%s" does not exist for constraint of type "%s".', $errorCode, static::class));
  84.         }
  86.         trigger_deprecation('symfony/validator', '6.1', 'The "%s::$errorNames" property is deprecated, use protected const ERROR_NAMES instead.', static::class);
  88.         return static::$errorNames[$errorCode];
  89.     }
  91.     /**
  92.      * Initializes the constraint with options.
  93.      *
  94.      * You should pass an associative array. The keys should be the names of
  95.      * existing properties in this class. The values should be the value for these
  96.      * properties.
  97.      *
  98.      * Alternatively you can override the method getDefaultOption() to return the
  99.      * name of an existing property. If no associative array is passed, this
  100.      * property is set instead.
  101.      *
  102.      * You can force that certain options are set by overriding
  103.      * getRequiredOptions() to return the names of these options. If any
  104.      * option is not set here, an exception is thrown.
  105.      *
  106.      * @param mixed    $options The options (as associative array)
  107.      *                          or the value for the default
  108.      *                          option (any other type)
  109.      * @param string[] $groups  An array of validation groups
  110.      * @param mixed    $payload Domain-specific data attached to a constraint
  111.      *
  112.      * @throws InvalidOptionsException       When you pass the names of non-existing
  113.      *                                       options
  114.      * @throws MissingOptionsException       When you don't pass any of the options
  115.      *                                       returned by getRequiredOptions()
  116.      * @throws ConstraintDefinitionException When you don't pass an associative
  117.      *                                       array, but getDefaultOption() returns
  118.      *                                       null
  119.      */
  120.     public function __construct(mixed $options = null, array $groups = null, mixed $payload = null)
  121.     {
  122.         unset($this->groups); // enable lazy initialization
  124.         $options = $this->normalizeOptions($options);
  125.         if (null !== $groups) {
  126.             $options['groups'] = $groups;
  127.         }
  128.         $options['payload'] = $payload ?? $options['payload'] ?? null;
  130.         foreach ($options as $name => $value) {
  131.             $this->$name = $value;
  132.         }
  133.     }
  135.     protected function normalizeOptions(mixed $options): array
  136.     {
  137.         $normalizedOptions = [];
  138.         $defaultOption = $this->getDefaultOption();
  139.         $invalidOptions = [];
  140.         $missingOptions = array_flip((array) $this->getRequiredOptions());
  141.         $knownOptions = get_class_vars(static::class);
  143.         if (\is_array($options) && isset($options['value']) && !property_exists($this, 'value')) {
  144.             if (null === $defaultOption) {
  145.                 throw new ConstraintDefinitionException(sprintf('No default option is configured for constraint "%s".', static::class));
  146.             }
  148.             $options[$defaultOption] = $options['value'];
  149.             unset($options['value']);
  150.         }
  152.         if (\is_array($options)) {
  153.             reset($options);
  154.         }
  155.         if ($options && \is_array($options) && \is_string(key($options))) {
  156.             foreach ($options as $option => $value) {
  157.                 if (\array_key_exists($option, $knownOptions)) {
  158.                     $normalizedOptions[$option] = $value;
  159.                     unset($missingOptions[$option]);
  160.                 } else {
  161.                     $invalidOptions[] = $option;
  162.                 }
  163.             }
  164.         } elseif (null !== $options && !(\is_array($options) && 0 === \count($options))) {
  165.             if (null === $defaultOption) {
  166.                 throw new ConstraintDefinitionException(sprintf('No default option is configured for constraint "%s".', static::class));
  167.             }
  169.             if (\array_key_exists($defaultOption, $knownOptions)) {
  170.                 $normalizedOptions[$defaultOption] = $options;
  171.                 unset($missingOptions[$defaultOption]);
  172.             } else {
  173.                 $invalidOptions[] = $defaultOption;
  174.             }
  175.         }
  177.         if (\count($invalidOptions) > 0) {
  178.             throw new InvalidOptionsException(sprintf('The options "%s" do not exist in constraint "%s".', implode('", "', $invalidOptions), static::class), $invalidOptions);
  179.         }
  181.         if (\count($missingOptions) > 0) {
  182.             throw new MissingOptionsException(sprintf('The options "%s" must be set for constraint "%s".', implode('", "', array_keys($missingOptions)), static::class), array_keys($missingOptions));
  183.         }
  185.         return $normalizedOptions;
  186.     }
  188.     /**
  189.      * Sets the value of a lazily initialized option.
  190.      *
  191.      * Corresponding properties are added to the object on first access. Hence
  192.      * this method will be called at most once per constraint instance and
  193.      * option name.
  194.      *
  195.      * @throws InvalidOptionsException If an invalid option name is given
  196.      */
  197.     public function __set(string $option, mixed $value)
  198.     {
  199.         if ('groups' === $option) {
  200.             $this->groups = (array) $value;
  202.             return;
  203.         }
  205.         throw new InvalidOptionsException(sprintf('The option "%s" does not exist in constraint "%s".', $option, static::class), [$option]);
  206.     }
  208.     /**
  209.      * Returns the value of a lazily initialized option.
  210.      *
  211.      * Corresponding properties are added to the object on first access. Hence
  212.      * this method will be called at most once per constraint instance and
  213.      * option name.
  214.      *
  215.      * @throws InvalidOptionsException If an invalid option name is given
  216.      */
  217.     public function __get(string $option): mixed
  218.     {
  219.         if ('groups' === $option) {
  220.             $this->groups = [self::DEFAULT_GROUP];
  222.             return $this->groups;
  223.         }
  225.         throw new InvalidOptionsException(sprintf('The option "%s" does not exist in constraint "%s".', $option, static::class), [$option]);
  226.     }
  228.     public function __isset(string $option): bool
  229.     {
  230.         return 'groups' === $option;
  231.     }
  233.     /**
  234.      * Adds the given group if this constraint is in the Default group.
  235.      */
  236.     public function addImplicitGroupName(string $group)
  237.     {
  238.         if (null === $this->groups && \array_key_exists('groups', (array) $this)) {
  239.             throw new \LogicException(sprintf('"%s::$groups" is set to null. Did you forget to call "%s::__construct()"?', static::class, self::class));
  240.         }
  242.         if (\in_array(self::DEFAULT_GROUP, $this->groups) && !\in_array($group, $this->groups)) {
  243.             $this->groups[] = $group;
  244.         }
  245.     }
  247.     /**
  248.      * Returns the name of the default option.
  249.      *
  250.      * Override this method to define a default option.
  251.      *
  252.      * @return string|null
  253.      *
  254.      * @see __construct()
  255.      */
  256.     public function getDefaultOption()
  257.     {
  258.         return null;
  259.     }
  261.     /**
  262.      * Returns the name of the required options.
  263.      *
  264.      * Override this method if you want to define required options.
  265.      *
  266.      * @return string[]
  267.      *
  268.      * @see __construct()
  269.      */
  270.     public function getRequiredOptions()
  271.     {
  272.         return [];
  273.     }
  275.     /**
  276.      * Returns the name of the class that validates this constraint.
  277.      *
  278.      * By default, this is the fully qualified name of the constraint class
  279.      * suffixed with "Validator". You can override this method to change that
  280.      * behavior.
  281.      *
  282.      * @return string
  283.      */
  284.     public function validatedBy()
  285.     {
  286.         return static::class.'Validator';
  287.     }
  289.     /**
  290.      * Returns whether the constraint can be put onto classes, properties or
  291.      * both.
  292.      *
  293.      * This method should return one or more of the constants
  294.      * Constraint::CLASS_CONSTRAINT and Constraint::PROPERTY_CONSTRAINT.
  295.      *
  296.      * @return string|string[] One or more constant values
  297.      */
  298.     public function getTargets()
  299.     {
  300.         return self::PROPERTY_CONSTRAINT;
  301.     }
  303.     /**
  304.      * Optimizes the serialized value to minimize storage space.
  305.      *
  306.      * @internal
  307.      */
  308.     public function __sleep(): array
  309.     {
  310.         // Initialize "groups" option if it is not set
  311.         $this->groups;
  313.         return array_keys(get_object_vars($this));
  314.     }
  315. }