annotate vendor/symfony/validator/Constraint.php @ 19:fa3358dc1485 tip

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