www.aleph1.co.uk Git - yaffs-website/blob - vendor/symfony/validator/Constraint.php

   1 <?php
   2
   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  */
  11
  12 namespace Symfony\Component\Validator;
  13
  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;
  18
  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  * @property array $groups The groups that the constraint belongs to
  29  *
  30  * @author Bernhard Schussek <bschussek@gmail.com>
  31  */
  32 abstract class Constraint
  33 {
  34     /**
  35      * The name of the group given to all constraints with no explicit group.
  36      */
  37     const DEFAULT_GROUP = 'Default';
  38
  39     /**
  40      * Marks a constraint that can be put onto classes.
  41      */
  42     const CLASS_CONSTRAINT = 'class';
  43
  44     /**
  45      * Marks a constraint that can be put onto properties.
  46      */
  47     const PROPERTY_CONSTRAINT = 'property';
  48
  49     /**
  50      * Maps error codes to the names of their constants.
  51      */
  52     protected static $errorNames = array();
  53
  54     /**
  55      * Domain-specific data attached to a constraint.
  56      *
  57      * @var mixed
  58      */
  59     public $payload;
  60
  61     /**
  62      * Returns the name of the given error code.
  63      *
  64      * @param string $errorCode The error code
  65      *
  66      * @return string The name of the error code
  67      *
  68      * @throws InvalidArgumentException If the error code does not exist
  69      */
  70     public static function getErrorName($errorCode)
  71     {
  72         if (!isset(static::$errorNames[$errorCode])) {
  73             throw new InvalidArgumentException(sprintf('The error code "%s" does not exist for constraint of type "%s".', $errorCode, \get_called_class()));
  74         }
  75
  76         return static::$errorNames[$errorCode];
  77     }
  78
  79     /**
  80      * Initializes the constraint with options.
  81      *
  82      * You should pass an associative array. The keys should be the names of
  83      * existing properties in this class. The values should be the value for these
  84      * properties.
  85      *
  86      * Alternatively you can override the method getDefaultOption() to return the
  87      * name of an existing property. If no associative array is passed, this
  88      * property is set instead.
  89      *
  90      * You can force that certain options are set by overriding
  91      * getRequiredOptions() to return the names of these options. If any
  92      * option is not set here, an exception is thrown.
  93      *
  94      * @param mixed $options The options (as associative array)
  95      *                       or the value for the default
  96      *                       option (any other type)
  97      *
  98      * @throws InvalidOptionsException       When you pass the names of non-existing
  99      *                                       options
 100      * @throws MissingOptionsException       When you don't pass any of the options
 101      *                                       returned by getRequiredOptions()
 102      * @throws ConstraintDefinitionException When you don't pass an associative
 103      *                                       array, but getDefaultOption() returns
 104      *                                       null
 105      */
 106     public function __construct($options = null)
 107     {
 108         $invalidOptions = array();
 109         $missingOptions = array_flip((array) $this->getRequiredOptions());
 110         $knownOptions = get_object_vars($this);
 111
 112         // The "groups" option is added to the object lazily
 113         $knownOptions['groups'] = true;
 114
 115         if (\is_array($options) && \count($options) >= 1 && isset($options['value']) && !property_exists($this, 'value')) {
 116             $options[$this->getDefaultOption()] = $options['value'];
 117             unset($options['value']);
 118         }
 119
 120         if (\is_array($options)) {
 121             reset($options);
 122         }
 123         if (\is_array($options) && \count($options) > 0 && \is_string(key($options))) {
 124             foreach ($options as $option => $value) {
 125                 if (array_key_exists($option, $knownOptions)) {
 126                     $this->$option = $value;
 127                     unset($missingOptions[$option]);
 128                 } else {
 129                     $invalidOptions[] = $option;
 130                 }
 131             }
 132         } elseif (null !== $options && !(\is_array($options) && 0 === \count($options))) {
 133             $option = $this->getDefaultOption();
 134
 135             if (null === $option) {
 136                 throw new ConstraintDefinitionException(sprintf('No default option is configured for constraint %s', \get_class($this)));
 137             }
 138
 139             if (array_key_exists($option, $knownOptions)) {
 140                 $this->$option = $options;
 141                 unset($missingOptions[$option]);
 142             } else {
 143                 $invalidOptions[] = $option;
 144             }
 145         }
 146
 147         if (\count($invalidOptions) > 0) {
 148             throw new InvalidOptionsException(sprintf('The options "%s" do not exist in constraint %s', implode('", "', $invalidOptions), \get_class($this)), $invalidOptions);
 149         }
 150
 151         if (\count($missingOptions) > 0) {
 152             throw new MissingOptionsException(sprintf('The options "%s" must be set for constraint %s', implode('", "', array_keys($missingOptions)), \get_class($this)), array_keys($missingOptions));
 153         }
 154     }
 155
 156     /**
 157      * Sets the value of a lazily initialized option.
 158      *
 159      * Corresponding properties are added to the object on first access. Hence
 160      * this method will be called at most once per constraint instance and
 161      * option name.
 162      *
 163      * @param string $option The option name
 164      * @param mixed  $value  The value to set
 165      *
 166      * @throws InvalidOptionsException If an invalid option name is given
 167      */
 168     public function __set($option, $value)
 169     {
 170         if ('groups' === $option) {
 171             $this->groups = (array) $value;
 172
 173             return;
 174         }
 175
 176         throw new InvalidOptionsException(sprintf('The option "%s" does not exist in constraint %s', $option, \get_class($this)), array($option));
 177     }
 178
 179     /**
 180      * Returns the value of a lazily initialized option.
 181      *
 182      * Corresponding properties are added to the object on first access. Hence
 183      * this method will be called at most once per constraint instance and
 184      * option name.
 185      *
 186      * @param string $option The option name
 187      *
 188      * @return mixed The value of the option
 189      *
 190      * @throws InvalidOptionsException If an invalid option name is given
 191      *
 192      * @internal this method should not be used or overwritten in userland code
 193      */
 194     public function __get($option)
 195     {
 196         if ('groups' === $option) {
 197             $this->groups = array(self::DEFAULT_GROUP);
 198
 199             return $this->groups;
 200         }
 201
 202         throw new InvalidOptionsException(sprintf('The option "%s" does not exist in constraint %s', $option, \get_class($this)), array($option));
 203     }
 204
 205     /**
 206      * @param string $option The option name
 207      *
 208      * @return bool
 209      */
 210     public function __isset($option)
 211     {
 212         return 'groups' === $option;
 213     }
 214
 215     /**
 216      * Adds the given group if this constraint is in the Default group.
 217      *
 218      * @param string $group
 219      */
 220     public function addImplicitGroupName($group)
 221     {
 222         if (\in_array(self::DEFAULT_GROUP, $this->groups) && !\in_array($group, $this->groups)) {
 223             $this->groups[] = $group;
 224         }
 225     }
 226
 227     /**
 228      * Returns the name of the default option.
 229      *
 230      * Override this method to define a default option.
 231      *
 232      * @return string
 233      *
 234      * @see __construct()
 235      */
 236     public function getDefaultOption()
 237     {
 238     }
 239
 240     /**
 241      * Returns the name of the required options.
 242      *
 243      * Override this method if you want to define required options.
 244      *
 245      * @return array
 246      *
 247      * @see __construct()
 248      */
 249     public function getRequiredOptions()
 250     {
 251         return array();
 252     }
 253
 254     /**
 255      * Returns the name of the class that validates this constraint.
 256      *
 257      * By default, this is the fully qualified name of the constraint class
 258      * suffixed with "Validator". You can override this method to change that
 259      * behaviour.
 260      *
 261      * @return string
 262      */
 263     public function validatedBy()
 264     {
 265         return \get_class($this).'Validator';
 266     }
 267
 268     /**
 269      * Returns whether the constraint can be put onto classes, properties or
 270      * both.
 271      *
 272      * This method should return one or more of the constants
 273      * Constraint::CLASS_CONSTRAINT and Constraint::PROPERTY_CONSTRAINT.
 274      *
 275      * @return string|array One or more constant values
 276      */
 277     public function getTargets()
 278     {
 279         return self::PROPERTY_CONSTRAINT;
 280     }
 281
 282     /**
 283      * Optimizes the serialized value to minimize storage space.
 284      *
 285      * @return array The properties to serialize
 286      *
 287      * @internal This method may be replaced by an implementation of
 288      *           {@link \Serializable} in the future. Please don't use or
 289      *           overwrite it.
 290      */
 291     public function __sleep()
 292     {
 293         // Initialize "groups" option if it is not set
 294         $this->groups;
 295
 296         return array_keys(get_object_vars($this));
 297     }
 298 }