Chris@0: <?php
Chris@0: 
Chris@0: /*
Chris@0:  * This file is part of the Symfony package.
Chris@0:  *
Chris@0:  * (c) Fabien Potencier <fabien@symfony.com>
Chris@0:  *
Chris@0:  * For the full copyright and license information, please view the LICENSE
Chris@0:  * file that was distributed with this source code.
Chris@0:  */
Chris@0: 
Chris@0: namespace Symfony\Component\Validator;
Chris@0: 
Chris@0: use Symfony\Component\Validator\Exception\ConstraintDefinitionException;
Chris@0: use Symfony\Component\Validator\Exception\InvalidArgumentException;
Chris@0: use Symfony\Component\Validator\Exception\InvalidOptionsException;
Chris@0: use Symfony\Component\Validator\Exception\MissingOptionsException;
Chris@0: 
Chris@0: /**
Chris@0:  * Contains the properties of a constraint definition.
Chris@0:  *
Chris@0:  * A constraint can be defined on a class, a property or a getter method.
Chris@0:  * The Constraint class encapsulates all the configuration required for
Chris@0:  * validating this class, property or getter result successfully.
Chris@0:  *
Chris@0:  * Constraint instances are immutable and serializable.
Chris@0:  *
Chris@0:  * @property array $groups The groups that the constraint belongs to
Chris@0:  *
Chris@0:  * @author Bernhard Schussek <bschussek@gmail.com>
Chris@0:  */
Chris@0: abstract class Constraint
Chris@0: {
Chris@0:     /**
Chris@0:      * The name of the group given to all constraints with no explicit group.
Chris@0:      */
Chris@0:     const DEFAULT_GROUP = 'Default';
Chris@0: 
Chris@0:     /**
Chris@0:      * Marks a constraint that can be put onto classes.
Chris@0:      */
Chris@0:     const CLASS_CONSTRAINT = 'class';
Chris@0: 
Chris@0:     /**
Chris@0:      * Marks a constraint that can be put onto properties.
Chris@0:      */
Chris@0:     const PROPERTY_CONSTRAINT = 'property';
Chris@0: 
Chris@0:     /**
Chris@0:      * Maps error codes to the names of their constants.
Chris@0:      */
Chris@17:     protected static $errorNames = [];
Chris@0: 
Chris@0:     /**
Chris@0:      * Domain-specific data attached to a constraint.
Chris@0:      *
Chris@0:      * @var mixed
Chris@0:      */
Chris@0:     public $payload;
Chris@0: 
Chris@0:     /**
Chris@0:      * Returns the name of the given error code.
Chris@0:      *
Chris@0:      * @param string $errorCode The error code
Chris@0:      *
Chris@0:      * @return string The name of the error code
Chris@0:      *
Chris@0:      * @throws InvalidArgumentException If the error code does not exist
Chris@0:      */
Chris@0:     public static function getErrorName($errorCode)
Chris@0:     {
Chris@0:         if (!isset(static::$errorNames[$errorCode])) {
Chris@17:             throw new InvalidArgumentException(sprintf('The error code "%s" does not exist for constraint of type "%s".', $errorCode, \get_called_class()));
Chris@0:         }
Chris@0: 
Chris@0:         return static::$errorNames[$errorCode];
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Initializes the constraint with options.
Chris@0:      *
Chris@0:      * You should pass an associative array. The keys should be the names of
Chris@0:      * existing properties in this class. The values should be the value for these
Chris@0:      * properties.
Chris@0:      *
Chris@0:      * Alternatively you can override the method getDefaultOption() to return the
Chris@0:      * name of an existing property. If no associative array is passed, this
Chris@0:      * property is set instead.
Chris@0:      *
Chris@0:      * You can force that certain options are set by overriding
Chris@0:      * getRequiredOptions() to return the names of these options. If any
Chris@0:      * option is not set here, an exception is thrown.
Chris@0:      *
Chris@0:      * @param mixed $options The options (as associative array)
Chris@0:      *                       or the value for the default
Chris@0:      *                       option (any other type)
Chris@0:      *
Chris@0:      * @throws InvalidOptionsException       When you pass the names of non-existing
Chris@0:      *                                       options
Chris@0:      * @throws MissingOptionsException       When you don't pass any of the options
Chris@0:      *                                       returned by getRequiredOptions()
Chris@0:      * @throws ConstraintDefinitionException When you don't pass an associative
Chris@0:      *                                       array, but getDefaultOption() returns
Chris@0:      *                                       null
Chris@0:      */
Chris@0:     public function __construct($options = null)
Chris@0:     {
Chris@18:         $defaultOption = $this->getDefaultOption();
Chris@17:         $invalidOptions = [];
Chris@0:         $missingOptions = array_flip((array) $this->getRequiredOptions());
Chris@0:         $knownOptions = get_object_vars($this);
Chris@0: 
Chris@0:         // The "groups" option is added to the object lazily
Chris@0:         $knownOptions['groups'] = true;
Chris@0: 
Chris@18:         if (\is_array($options) && isset($options['value']) && !property_exists($this, 'value')) {
Chris@18:             if (null === $defaultOption) {
Chris@18:                 throw new ConstraintDefinitionException(sprintf('No default option is configured for constraint "%s".', \get_class($this)));
Chris@18:             }
Chris@18: 
Chris@18:             $options[$defaultOption] = $options['value'];
Chris@0:             unset($options['value']);
Chris@0:         }
Chris@0: 
Chris@17:         if (\is_array($options)) {
Chris@0:             reset($options);
Chris@0:         }
Chris@17:         if ($options && \is_array($options) && \is_string(key($options))) {
Chris@0:             foreach ($options as $option => $value) {
Chris@18:                 if (\array_key_exists($option, $knownOptions)) {
Chris@0:                     $this->$option = $value;
Chris@0:                     unset($missingOptions[$option]);
Chris@0:                 } else {
Chris@0:                     $invalidOptions[] = $option;
Chris@0:                 }
Chris@0:             }
Chris@17:         } elseif (null !== $options && !(\is_array($options) && 0 === \count($options))) {
Chris@18:             if (null === $defaultOption) {
Chris@18:                 throw new ConstraintDefinitionException(sprintf('No default option is configured for constraint "%s".', \get_class($this)));
Chris@0:             }
Chris@0: 
Chris@18:             if (\array_key_exists($defaultOption, $knownOptions)) {
Chris@18:                 $this->$defaultOption = $options;
Chris@18:                 unset($missingOptions[$defaultOption]);
Chris@0:             } else {
Chris@18:                 $invalidOptions[] = $defaultOption;
Chris@0:             }
Chris@0:         }
Chris@0: 
Chris@17:         if (\count($invalidOptions) > 0) {
Chris@18:             throw new InvalidOptionsException(sprintf('The options "%s" do not exist in constraint "%s".', implode('", "', $invalidOptions), \get_class($this)), $invalidOptions);
Chris@0:         }
Chris@0: 
Chris@17:         if (\count($missingOptions) > 0) {
Chris@18:             throw new MissingOptionsException(sprintf('The options "%s" must be set for constraint "%s".', implode('", "', array_keys($missingOptions)), \get_class($this)), array_keys($missingOptions));
Chris@0:         }
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Sets the value of a lazily initialized option.
Chris@0:      *
Chris@0:      * Corresponding properties are added to the object on first access. Hence
Chris@0:      * this method will be called at most once per constraint instance and
Chris@0:      * option name.
Chris@0:      *
Chris@0:      * @param string $option The option name
Chris@0:      * @param mixed  $value  The value to set
Chris@0:      *
Chris@0:      * @throws InvalidOptionsException If an invalid option name is given
Chris@0:      */
Chris@0:     public function __set($option, $value)
Chris@0:     {
Chris@0:         if ('groups' === $option) {
Chris@0:             $this->groups = (array) $value;
Chris@0: 
Chris@0:             return;
Chris@0:         }
Chris@0: 
Chris@18:         throw new InvalidOptionsException(sprintf('The option "%s" does not exist in constraint "%s".', $option, \get_class($this)), [$option]);
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Returns the value of a lazily initialized option.
Chris@0:      *
Chris@0:      * Corresponding properties are added to the object on first access. Hence
Chris@0:      * this method will be called at most once per constraint instance and
Chris@0:      * option name.
Chris@0:      *
Chris@0:      * @param string $option The option name
Chris@0:      *
Chris@0:      * @return mixed The value of the option
Chris@0:      *
Chris@0:      * @throws InvalidOptionsException If an invalid option name is given
Chris@0:      *
Chris@14:      * @internal this method should not be used or overwritten in userland code
Chris@0:      */
Chris@0:     public function __get($option)
Chris@0:     {
Chris@0:         if ('groups' === $option) {
Chris@17:             $this->groups = [self::DEFAULT_GROUP];
Chris@0: 
Chris@0:             return $this->groups;
Chris@0:         }
Chris@0: 
Chris@18:         throw new InvalidOptionsException(sprintf('The option "%s" does not exist in constraint "%s".', $option, \get_class($this)), [$option]);
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@14:      * @param string $option The option name
Chris@14:      *
Chris@14:      * @return bool
Chris@14:      */
Chris@14:     public function __isset($option)
Chris@14:     {
Chris@14:         return 'groups' === $option;
Chris@14:     }
Chris@14: 
Chris@14:     /**
Chris@0:      * Adds the given group if this constraint is in the Default group.
Chris@0:      *
Chris@0:      * @param string $group
Chris@0:      */
Chris@0:     public function addImplicitGroupName($group)
Chris@0:     {
Chris@17:         if (\in_array(self::DEFAULT_GROUP, $this->groups) && !\in_array($group, $this->groups)) {
Chris@0:             $this->groups[] = $group;
Chris@0:         }
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Returns the name of the default option.
Chris@0:      *
Chris@0:      * Override this method to define a default option.
Chris@0:      *
Chris@18:      * @return string|null
Chris@0:      *
Chris@0:      * @see __construct()
Chris@0:      */
Chris@0:     public function getDefaultOption()
Chris@0:     {
Chris@18:         return null;
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Returns the name of the required options.
Chris@0:      *
Chris@0:      * Override this method if you want to define required options.
Chris@0:      *
Chris@0:      * @return array
Chris@0:      *
Chris@0:      * @see __construct()
Chris@0:      */
Chris@0:     public function getRequiredOptions()
Chris@0:     {
Chris@17:         return [];
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Returns the name of the class that validates this constraint.
Chris@0:      *
Chris@0:      * By default, this is the fully qualified name of the constraint class
Chris@0:      * suffixed with "Validator". You can override this method to change that
Chris@18:      * behavior.
Chris@0:      *
Chris@0:      * @return string
Chris@0:      */
Chris@0:     public function validatedBy()
Chris@0:     {
Chris@17:         return \get_class($this).'Validator';
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Returns whether the constraint can be put onto classes, properties or
Chris@0:      * both.
Chris@0:      *
Chris@0:      * This method should return one or more of the constants
Chris@0:      * Constraint::CLASS_CONSTRAINT and Constraint::PROPERTY_CONSTRAINT.
Chris@0:      *
Chris@0:      * @return string|array One or more constant values
Chris@0:      */
Chris@0:     public function getTargets()
Chris@0:     {
Chris@0:         return self::PROPERTY_CONSTRAINT;
Chris@0:     }
Chris@0: 
Chris@0:     /**
Chris@0:      * Optimizes the serialized value to minimize storage space.
Chris@0:      *
Chris@0:      * @return array The properties to serialize
Chris@0:      *
Chris@17:      * @internal
Chris@0:      */
Chris@0:     public function __sleep()
Chris@0:     {
Chris@0:         // Initialize "groups" option if it is not set
Chris@0:         $this->groups;
Chris@0: 
Chris@0:         return array_keys(get_object_vars($this));
Chris@0:     }
Chris@0: }