[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4   * Assert
   5   *
   6   * LICENSE
   7   *
   8   * This source file is subject to the MIT license that is bundled
   9   * with this package in the file LICENSE.txt.
  10   * If you did not receive a copy of the license and are unable to
  11   * obtain it through the world-wide-web, please send an email
  12   * to [email protected] so I can send you a copy immediately.
  13   */
  14  
  15  namespace Assert;
  16  
  17  use LogicException;
  18  
  19  /**
  20   * Chaining builder for assertions.
  21   *
  22   * @author Benjamin Eberlei <[email protected]>
  23   *
  24   * @method AssertionChain alnum(string|callable $message = null, string $propertyPath = null) Assert that value is alphanumeric.
  25   * @method AssertionChain base64(string|callable $message = null, string $propertyPath = null) Assert that a constant is defined.
  26   * @method AssertionChain between(mixed $lowerLimit, mixed $upperLimit, string|callable $message = null, string $propertyPath = null) Assert that a value is greater or equal than a lower limit, and less than or equal to an upper limit.
  27   * @method AssertionChain betweenExclusive(mixed $lowerLimit, mixed $upperLimit, string|callable $message = null, string $propertyPath = null) Assert that a value is greater than a lower limit, and less than an upper limit.
  28   * @method AssertionChain betweenLength(int $minLength, int $maxLength, string|callable $message = null, string $propertyPath = null, string $encoding = 'utf8') Assert that string length is between min and max lengths.
  29   * @method AssertionChain boolean(string|callable $message = null, string $propertyPath = null) Assert that value is php boolean.
  30   * @method AssertionChain choice(array $choices, string|callable $message = null, string $propertyPath = null) Assert that value is in array of choices.
  31   * @method AssertionChain choicesNotEmpty(array $choices, string|callable $message = null, string $propertyPath = null) Determines if the values array has every choice as key and that this choice has content.
  32   * @method AssertionChain classExists(string|callable $message = null, string $propertyPath = null) Assert that the class exists.
  33   * @method AssertionChain contains(string $needle, string|callable $message = null, string $propertyPath = null, string $encoding = 'utf8') Assert that string contains a sequence of chars.
  34   * @method AssertionChain count(int $count, string|callable $message = null, string $propertyPath = null) Assert that the count of countable is equal to count.
  35   * @method AssertionChain date(string $format, string|callable $message = null, string $propertyPath = null) Assert that date is valid and corresponds to the given format.
  36   * @method AssertionChain defined(string|callable $message = null, string $propertyPath = null) Assert that a constant is defined.
  37   * @method AssertionChain digit(string|callable $message = null, string $propertyPath = null) Validates if an integer or integerish is a digit.
  38   * @method AssertionChain directory(string|callable $message = null, string $propertyPath = null) Assert that a directory exists.
  39   * @method AssertionChain e164(string|callable $message = null, string $propertyPath = null) Assert that the given string is a valid E164 Phone Number.
  40   * @method AssertionChain email(string|callable $message = null, string $propertyPath = null) Assert that value is an email address (using input_filter/FILTER_VALIDATE_EMAIL).
  41   * @method AssertionChain endsWith(string $needle, string|callable $message = null, string $propertyPath = null, string $encoding = 'utf8') Assert that string ends with a sequence of chars.
  42   * @method AssertionChain eq(mixed $value2, string|callable $message = null, string $propertyPath = null) Assert that two values are equal (using ==).
  43   * @method AssertionChain eqArraySubset(mixed $value2, string|callable $message = null, string $propertyPath = null) Assert that the array contains the subset.
  44   * @method AssertionChain extensionLoaded(string|callable $message = null, string $propertyPath = null) Assert that extension is loaded.
  45   * @method AssertionChain extensionVersion(string $operator, mixed $version, string|callable $message = null, string $propertyPath = null) Assert that extension is loaded and a specific version is installed.
  46   * @method AssertionChain false(string|callable $message = null, string $propertyPath = null) Assert that the value is boolean False.
  47   * @method AssertionChain file(string|callable $message = null, string $propertyPath = null) Assert that a file exists.
  48   * @method AssertionChain float(string|callable $message = null, string $propertyPath = null) Assert that value is a php float.
  49   * @method AssertionChain greaterOrEqualThan(mixed $limit, string|callable $message = null, string $propertyPath = null) Determines if the value is greater or equal than given limit.
  50   * @method AssertionChain greaterThan(mixed $limit, string|callable $message = null, string $propertyPath = null) Determines if the value is greater than given limit.
  51   * @method AssertionChain implementsInterface(string $interfaceName, string|callable $message = null, string $propertyPath = null) Assert that the class implements the interface.
  52   * @method AssertionChain inArray(array $choices, string|callable $message = null, string $propertyPath = null) Assert that value is in array of choices. This is an alias of Assertion::choice().
  53   * @method AssertionChain integer(string|callable $message = null, string $propertyPath = null) Assert that value is a php integer.
  54   * @method AssertionChain integerish(string|callable $message = null, string $propertyPath = null) Assert that value is a php integer'ish.
  55   * @method AssertionChain interfaceExists(string|callable $message = null, string $propertyPath = null) Assert that the interface exists.
  56   * @method AssertionChain ip(int $flag = null, string|callable $message = null, string $propertyPath = null) Assert that value is an IPv4 or IPv6 address.
  57   * @method AssertionChain ipv4(int $flag = null, string|callable $message = null, string $propertyPath = null) Assert that value is an IPv4 address.
  58   * @method AssertionChain ipv6(int $flag = null, string|callable $message = null, string $propertyPath = null) Assert that value is an IPv6 address.
  59   * @method AssertionChain isArray(string|callable $message = null, string $propertyPath = null) Assert that value is an array.
  60   * @method AssertionChain isArrayAccessible(string|callable $message = null, string $propertyPath = null) Assert that value is an array or an array-accessible object.
  61   * @method AssertionChain isCallable(string|callable $message = null, string $propertyPath = null) Determines that the provided value is callable.
  62   * @method AssertionChain isCountable(string|callable $message = null, string $propertyPath = null) Assert that value is countable.
  63   * @method AssertionChain isInstanceOf(string $className, string|callable $message = null, string $propertyPath = null) Assert that value is instance of given class-name.
  64   * @method AssertionChain isJsonString(string|callable $message = null, string $propertyPath = null) Assert that the given string is a valid json string.
  65   * @method AssertionChain isObject(string|callable $message = null, string $propertyPath = null) Determines that the provided value is an object.
  66   * @method AssertionChain isResource(string|callable $message = null, string $propertyPath = null) Assert that value is a resource.
  67   * @method AssertionChain isTraversable(string|callable $message = null, string $propertyPath = null) Assert that value is an array or a traversable object.
  68   * @method AssertionChain keyExists(string|int $key, string|callable $message = null, string $propertyPath = null) Assert that key exists in an array.
  69   * @method AssertionChain keyIsset(string|int $key, string|callable $message = null, string $propertyPath = null) Assert that key exists in an array/array-accessible object using isset().
  70   * @method AssertionChain keyNotExists(string|int $key, string|callable $message = null, string $propertyPath = null) Assert that key does not exist in an array.
  71   * @method AssertionChain length(int $length, string|callable $message = null, string $propertyPath = null, string $encoding = 'utf8') Assert that string has a given length.
  72   * @method AssertionChain lessOrEqualThan(mixed $limit, string|callable $message = null, string $propertyPath = null) Determines if the value is less or equal than given limit.
  73   * @method AssertionChain lessThan(mixed $limit, string|callable $message = null, string $propertyPath = null) Determines if the value is less than given limit.
  74   * @method AssertionChain max(mixed $maxValue, string|callable $message = null, string $propertyPath = null) Assert that a number is smaller as a given limit.
  75   * @method AssertionChain maxCount(int $count, string|callable $message = null, string $propertyPath = null) Assert that the countable have at most $count elements.
  76   * @method AssertionChain maxLength(int $maxLength, string|callable $message = null, string $propertyPath = null, string $encoding = 'utf8') Assert that string value is not longer than $maxLength chars.
  77   * @method AssertionChain methodExists(mixed $object, string|callable $message = null, string $propertyPath = null) Determines that the named method is defined in the provided object.
  78   * @method AssertionChain min(mixed $minValue, string|callable $message = null, string $propertyPath = null) Assert that a value is at least as big as a given limit.
  79   * @method AssertionChain minCount(int $count, string|callable $message = null, string $propertyPath = null) Assert that the countable have at least $count elements.
  80   * @method AssertionChain minLength(int $minLength, string|callable $message = null, string $propertyPath = null, string $encoding = 'utf8') Assert that a string is at least $minLength chars long.
  81   * @method AssertionChain noContent(string|callable $message = null, string $propertyPath = null) Assert that value is empty.
  82   * @method AssertionChain notBlank(string|callable $message = null, string $propertyPath = null) Assert that value is not blank.
  83   * @method AssertionChain notContains(string $needle, string|callable $message = null, string $propertyPath = null, string $encoding = 'utf8') Assert that string does not contains a sequence of chars.
  84   * @method AssertionChain notEmpty(string|callable $message = null, string $propertyPath = null) Assert that value is not empty.
  85   * @method AssertionChain notEmptyKey(string|int $key, string|callable $message = null, string $propertyPath = null) Assert that key exists in an array/array-accessible object and its value is not empty.
  86   * @method AssertionChain notEq(mixed $value2, string|callable $message = null, string $propertyPath = null) Assert that two values are not equal (using ==).
  87   * @method AssertionChain notInArray(array $choices, string|callable $message = null, string $propertyPath = null) Assert that value is not in array of choices.
  88   * @method AssertionChain notIsInstanceOf(string $className, string|callable $message = null, string $propertyPath = null) Assert that value is not instance of given class-name.
  89   * @method AssertionChain notNull(string|callable $message = null, string $propertyPath = null) Assert that value is not null.
  90   * @method AssertionChain notRegex(string $pattern, string|callable $message = null, string $propertyPath = null) Assert that value does not match a regex.
  91   * @method AssertionChain notSame(mixed $value2, string|callable $message = null, string $propertyPath = null) Assert that two values are not the same (using ===).
  92   * @method AssertionChain null(string|callable $message = null, string $propertyPath = null) Assert that value is null.
  93   * @method AssertionChain numeric(string|callable $message = null, string $propertyPath = null) Assert that value is numeric.
  94   * @method AssertionChain objectOrClass(string|callable $message = null, string $propertyPath = null) Assert that the value is an object, or a class that exists.
  95   * @method AssertionChain phpVersion(mixed $version, string|callable $message = null, string $propertyPath = null) Assert on PHP version.
  96   * @method AssertionChain propertiesExist(array $properties, string|callable $message = null, string $propertyPath = null) Assert that the value is an object or class, and that the properties all exist.
  97   * @method AssertionChain propertyExists(string $property, string|callable $message = null, string $propertyPath = null) Assert that the value is an object or class, and that the property exists.
  98   * @method AssertionChain range(mixed $minValue, mixed $maxValue, string|callable $message = null, string $propertyPath = null) Assert that value is in range of numbers.
  99   * @method AssertionChain readable(string|callable $message = null, string $propertyPath = null) Assert that the value is something readable.
 100   * @method AssertionChain regex(string $pattern, string|callable $message = null, string $propertyPath = null) Assert that value matches a regex.
 101   * @method AssertionChain same(mixed $value2, string|callable $message = null, string $propertyPath = null) Assert that two values are the same (using ===).
 102   * @method AssertionChain satisfy(callable $callback, string|callable $message = null, string $propertyPath = null) Assert that the provided value is valid according to a callback.
 103   * @method AssertionChain scalar(string|callable $message = null, string $propertyPath = null) Assert that value is a PHP scalar.
 104   * @method AssertionChain startsWith(string $needle, string|callable $message = null, string $propertyPath = null, string $encoding = 'utf8') Assert that string starts with a sequence of chars.
 105   * @method AssertionChain string(string|callable $message = null, string $propertyPath = null) Assert that value is a string.
 106   * @method AssertionChain subclassOf(string $className, string|callable $message = null, string $propertyPath = null) Assert that value is subclass of given class-name.
 107   * @method AssertionChain true(string|callable $message = null, string $propertyPath = null) Assert that the value is boolean True.
 108   * @method AssertionChain uniqueValues(string|callable $message = null, string $propertyPath = null) Assert that values in array are unique (using strict equality).
 109   * @method AssertionChain url(string|callable $message = null, string $propertyPath = null) Assert that value is an URL.
 110   * @method AssertionChain uuid(string|callable $message = null, string $propertyPath = null) Assert that the given string is a valid UUID.
 111   * @method AssertionChain version(string $operator, string $version2, string|callable $message = null, string $propertyPath = null) Assert comparison of two versions.
 112   * @method AssertionChain writeable(string|callable $message = null, string $propertyPath = null) Assert that the value is something writeable.
 113   */
 114  class AssertionChain
 115  {
 116      /**
 117       * @var mixed
 118       */
 119      private $value;
 120  
 121      /**
 122       * @var string|callable|null
 123       */
 124      private $defaultMessage;
 125  
 126      /**
 127       * @var string|null
 128       */
 129      private $defaultPropertyPath;
 130  
 131      /**
 132       * Return each assertion as always valid.
 133       *
 134       * @var bool
 135       */
 136      private $alwaysValid = false;
 137  
 138      /**
 139       * Perform assertion on every element of array or traversable.
 140       *
 141       * @var bool
 142       */
 143      private $all = false;
 144  
 145      /** @var string|Assertion Class to use for assertion calls */
 146      private $assertionClassName = 'Assert\Assertion';
 147  
 148      /**
 149       * AssertionChain constructor.
 150       *
 151       * @param mixed $value
 152       * @param string|callable|null $defaultMessage
 153       */
 154      public function __construct($value, $defaultMessage = null, string $defaultPropertyPath = null)
 155      {
 156          $this->value = $value;
 157          $this->defaultMessage = $defaultMessage;
 158          $this->defaultPropertyPath = $defaultPropertyPath;
 159      }
 160  
 161      /**
 162       * Call assertion on the current value in the chain.
 163       *
 164       * @param string $methodName
 165       * @param array $args
 166       */
 167      public function __call($methodName, $args): AssertionChain
 168      {
 169          if (true === $this->alwaysValid) {
 170              return $this;
 171          }
 172  
 173          try {
 174              $method = new \ReflectionMethod($this->assertionClassName, $methodName);
 175          } catch (\ReflectionException $exception) {
 176              throw new \RuntimeException("Assertion '".$methodName."' does not exist.");
 177          }
 178  
 179          \array_unshift($args, $this->value);
 180          $params = $method->getParameters();
 181  
 182          foreach ($params as $idx => $param) {
 183              if (isset($args[$idx])) {
 184                  continue;
 185              }
 186  
 187              switch ($param->getName()) {
 188                  case 'message':
 189                      $args[$idx] = $this->defaultMessage;
 190                      break;
 191                  case 'propertyPath':
 192                      $args[$idx] = $this->defaultPropertyPath;
 193                      break;
 194              }
 195          }
 196  
 197          if ($this->all) {
 198              $methodName = 'all'.$methodName;
 199          }
 200  
 201          \call_user_func_array([$this->assertionClassName, $methodName], $args);
 202  
 203          return $this;
 204      }
 205  
 206      /**
 207       * Switch chain into validation mode for an array of values.
 208       */
 209      public function all(): AssertionChain
 210      {
 211          $this->all = true;
 212  
 213          return $this;
 214      }
 215  
 216      /**
 217       * Switch chain into mode allowing nulls, ignoring further assertions.
 218       */
 219      public function nullOr(): AssertionChain
 220      {
 221          if (null === $this->value) {
 222              $this->alwaysValid = true;
 223          }
 224  
 225          return $this;
 226      }
 227  
 228      /**
 229       * @param string $className
 230       *
 231       * @return $this
 232       */
 233      public function setAssertionClassName($className): AssertionChain
 234      {
 235          if (!\is_string($className)) {
 236              throw new LogicException('Exception class name must be passed as a string');
 237          }
 238  
 239          if (Assertion::class !== $className && !\is_subclass_of($className, Assertion::class)) {
 240              throw new LogicException($className.' is not (a subclass of) '.Assertion::class);
 241          }
 242  
 243          $this->assertionClassName = $className;
 244  
 245          return $this;
 246      }
 247  }