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