www.aleph1.co.uk Git - yaffs-website/blob - vendor/webmozart/assert/README.md

   1 Webmozart Assert
   2 ================
   3
   4 [![Build Status](https://travis-ci.org/webmozart/assert.svg?branch=master)](https://travis-ci.org/webmozart/assert)
   5 [![Build status](https://ci.appveyor.com/api/projects/status/lyg83bcsisrr94se/branch/master?svg=true)](https://ci.appveyor.com/project/webmozart/assert/branch/master)
   6 [![Latest Stable Version](https://poser.pugx.org/webmozart/assert/v/stable.svg)](https://packagist.org/packages/webmozart/assert)
   7 [![Total Downloads](https://poser.pugx.org/webmozart/assert/downloads.svg)](https://packagist.org/packages/webmozart/assert)
   8 [![Dependency Status](https://www.versioneye.com/php/webmozart:assert/1.2.0/badge.svg)](https://www.versioneye.com/php/webmozart:assert/1.2.0)
   9
  10 Latest release: [1.2.0](https://packagist.org/packages/webmozart/assert#1.2.0)
  11
  12 PHP >= 5.3.9
  13
  14 This library contains efficient assertions to test the input and output of
  15 your methods. With these assertions, you can greatly reduce the amount of coding
  16 needed to write a safe implementation.
  17
  18 All assertions in the [`Assert`] class throw an `\InvalidArgumentException` if
  19 they fail.
  20
  21 FAQ
  22 ---
  23
  24 **What's the difference to [beberlei/assert]?**
  25
  26 This library is heavily inspired by Benjamin Eberlei's wonderful [assert package],
  27 but fixes a usability issue with error messages that can't be fixed there without
  28 breaking backwards compatibility.
  29
  30 This package features usable error messages by default. However, you can also
  31 easily write custom error messages:
  32
  33 ```
  34 Assert::string($path, 'The path is expected to be a string. Got: %s');
  35 ```
  36
  37 In [beberlei/assert], the ordering of the `%s` placeholders is different for
  38 every assertion. This package, on the contrary, provides consistent placeholder
  39 ordering for all assertions:
  40
  41 * `%s`: The tested value as string, e.g. `"/foo/bar"`.
  42 * `%2$s`, `%3$s`, ...: Additional assertion-specific values, e.g. the
  43   minimum/maximum length, allowed values, etc.
  44
  45 Check the source code of the assertions to find out details about the additional
  46 available placeholders.
  47
  48 Installation
  49 ------------
  50
  51 Use [Composer] to install the package:
  52
  53 ```
  54 $ composer require webmozart/assert
  55 ```
  56
  57 Example
  58 -------
  59
  60 ```php
  61 use Webmozart\Assert\Assert;
  62
  63 class Employee
  64 {
  65     public function __construct($id)
  66     {
  67         Assert::integer($id, 'The employee ID must be an integer. Got: %s');
  68         Assert::greaterThan($id, 0, 'The employee ID must be a positive integer. Got: %s');
  69     }
  70 }
  71 ```
  72
  73 If you create an employee with an invalid ID, an exception is thrown:
  74
  75 ```php
  76 new Employee('foobar');
  77 // => InvalidArgumentException:
  78 //    The employee ID must be an integer. Got: string
  79
  80 new Employee(-10);
  81 // => InvalidArgumentException:
  82 //    The employee ID must be a positive integer. Got: -10
  83 ```
  84
  85 Assertions
  86 ----------
  87
  88 The [`Assert`] class provides the following assertions:
  89
  90 ### Type Assertions
  91
  92 Method                                                   | Description
  93 -------------------------------------------------------- | --------------------------------------------------
  94 `string($value, $message = '')`                          | Check that a value is a string
  95 `stringNotEmpty($value, $message = '')`                  | Check that a value is a non-empty string
  96 `integer($value, $message = '')`                         | Check that a value is an integer
  97 `integerish($value, $message = '')`                      | Check that a value casts to an integer
  98 `float($value, $message = '')`                           | Check that a value is a float
  99 `numeric($value, $message = '')`                         | Check that a value is numeric
 100 `natural($value, $message= ''')`                         | Check that a value is a non-negative integer
 101 `boolean($value, $message = '')`                         | Check that a value is a boolean
 102 `scalar($value, $message = '')`                          | Check that a value is a scalar
 103 `object($value, $message = '')`                          | Check that a value is an object
 104 `resource($value, $type = null, $message = '')`          | Check that a value is a resource
 105 `isCallable($value, $message = '')`                      | Check that a value is a callable
 106 `isArray($value, $message = '')`                         | Check that a value is an array
 107 `isTraversable($value, $message = '')`  (deprecated)     | Check that a value is an array or a `\Traversable`
 108 `isIterable($value, $message = '')`                      | Check that a value is an array or a `\Traversable`
 109 `isCountable($value, $message = '')`                     | Check that a value is an array or a `\Countable`
 110 `isInstanceOf($value, $class, $message = '')`            | Check that a value is an `instanceof` a class
 111 `isInstanceOfAny($value, array $classes, $message = '')` | Check that a value is an `instanceof` a at least one class on the array of classes
 112 `notInstanceOf($value, $class, $message = '')`           | Check that a value is not an `instanceof` a class
 113 `isArrayAccessible($value, $message = '')`               | Check that a value can be accessed as an array
 114
 115 ### Comparison Assertions
 116
 117 Method                                          | Description
 118 ----------------------------------------------- | --------------------------------------------------
 119 `true($value, $message = '')`                   | Check that a value is `true`
 120 `false($value, $message = '')`                  | Check that a value is `false`
 121 `null($value, $message = '')`                   | Check that a value is `null`
 122 `notNull($value, $message = '')`                | Check that a value is not `null`
 123 `isEmpty($value, $message = '')`                | Check that a value is `empty()`
 124 `notEmpty($value, $message = '')`               | Check that a value is not `empty()`
 125 `eq($value, $value2, $message = '')`            | Check that a value equals another (`==`)
 126 `notEq($value, $value2, $message = '')`         | Check that a value does not equal another (`!=`)
 127 `same($value, $value2, $message = '')`          | Check that a value is identical to another (`===`)
 128 `notSame($value, $value2, $message = '')`       | Check that a value is not identical to another (`!==`)
 129 `greaterThan($value, $value2, $message = '')`   | Check that a value is greater than another
 130 `greaterThanEq($value, $value2, $message = '')` | Check that a value is greater than or equal to another
 131 `lessThan($value, $value2, $message = '')`      | Check that a value is less than another
 132 `lessThanEq($value, $value2, $message = '')`    | Check that a value is less than or equal to another
 133 `range($value, $min, $max, $message = '')`      | Check that a value is within a range
 134 `oneOf($value, array $values, $message = '')`   | Check that a value is one of a list of values
 135
 136 ### String Assertions
 137
 138 You should check that a value is a string with `Assert::string()` before making
 139 any of the following assertions.
 140
 141 Method                                              | Description
 142 --------------------------------------------------- | -----------------------------------------------------------------
 143 `contains($value, $subString, $message = '')`       | Check that a string contains a substring
 144 `notContains($value, $subString, $message = '')`    | Check that a string does not contains a substring
 145 `startsWith($value, $prefix, $message = '')`        | Check that a string has a prefix
 146 `startsWithLetter($value, $message = '')`           | Check that a string starts with a letter
 147 `endsWith($value, $suffix, $message = '')`          | Check that a string has a suffix
 148 `regex($value, $pattern, $message = '')`            | Check that a string matches a regular expression
 149 `alpha($value, $message = '')`                      | Check that a string contains letters only
 150 `digits($value, $message = '')`                     | Check that a string contains digits only
 151 `alnum($value, $message = '')`                      | Check that a string contains letters and digits only
 152 `lower($value, $message = '')`                      | Check that a string contains lowercase characters only
 153 `upper($value, $message = '')`                      | Check that a string contains uppercase characters only
 154 `length($value, $length, $message = '')`            | Check that a string has a certain number of characters
 155 `minLength($value, $min, $message = '')`            | Check that a string has at least a certain number of characters
 156 `maxLength($value, $max, $message = '')`            | Check that a string has at most a certain number of characters
 157 `lengthBetween($value, $min, $max, $message = '')`  | Check that a string has a length in the given range
 158 `uuid($value, $message = '')`                       | Check that a string is a valid UUID
 159 `notWhitespaceOnly($value, $message = '')`          | Check that a string contains at least one non-whitespace character
 160
 161 ### File Assertions
 162
 163 Method                              | Description
 164 ----------------------------------- | --------------------------------------------------
 165 `fileExists($value, $message = '')` | Check that a value is an existing path
 166 `file($value, $message = '')`       | Check that a value is an existing file
 167 `directory($value, $message = '')`  | Check that a value is an existing directory
 168 `readable($value, $message = '')`   | Check that a value is a readable path
 169 `writable($value, $message = '')`   | Check that a value is a writable path
 170
 171 ### Object Assertions
 172
 173 Method                                                | Description
 174 ----------------------------------------------------- | --------------------------------------------------
 175 `classExists($value, $message = '')`                  | Check that a value is an existing class name
 176 `subclassOf($value, $class, $message = '')`           | Check that a class is a subclass of another
 177 `implementsInterface($value, $class, $message = '')`  | Check that a class implements an interface
 178 `propertyExists($value, $property, $message = '')`    | Check that a property exists in a class/object
 179 `propertyNotExists($value, $property, $message = '')` | Check that a property does not exist in a class/object
 180 `methodExists($value, $method, $message = '')`        | Check that a method exists in a class/object
 181 `methodNotExists($value, $method, $message = '')`     | Check that a method does not exist in a class/object
 182
 183 ### Array Assertions
 184
 185 Method                                             | Description
 186 -------------------------------------------------- | ------------------------------------------------------------------
 187 `keyExists($array, $key, $message = '')`           | Check that a key exists in an array
 188 `keyNotExists($array, $key, $message = '')`        | Check that a key does not exist in an array
 189 `count($array, $number, $message = '')`            | Check that an array contains a specific number of elements
 190 `minCount($array, $min, $message = '')`            | Check that an array contains at least a certain number of elements
 191 `maxCount($array, $max, $message = '')`            | Check that an array contains at most a certain number of elements
 192 `countBetween($array, $min, $max, $message = '')`  | Check that an array has a count in the given range
 193
 194 ### Function Assertions
 195
 196 Method                                      | Description
 197 ------------------------------------------- | -----------------------------------------------------------------------------------------------------
 198 `throws($closure, $class, $message = '')`   | Check that a function throws a certain exception. Subclasses of the exception class will be accepted.
 199
 200 ### Collection Assertions
 201
 202 All of the above assertions can be prefixed with `all*()` to test the contents
 203 of an array or a `\Traversable`:
 204
 205 ```php
 206 Assert::allIsInstanceOf($employees, 'Acme\Employee');
 207 ```
 208
 209 ### Nullable Assertions
 210
 211 All of the above assertions can be prefixed with `nullOr*()` to run the
 212 assertion only if it the value is not `null`:
 213
 214 ```php
 215 Assert::nullOrString($middleName, 'The middle name must be a string or null. Got: %s');
 216 ```
 217
 218 Authors
 219 -------
 220
 221 * [Bernhard Schussek] a.k.a. [@webmozart]
 222 * [The Community Contributors]
 223
 224 Contribute
 225 ----------
 226
 227 Contributions to the package are always welcome!
 228
 229 * Report any bugs or issues you find on the [issue tracker].
 230 * You can grab the source code at the package's [Git repository].
 231
 232 Support
 233 -------
 234
 235 If you are having problems, send a mail to bschussek@gmail.com or shout out to
 236 [@webmozart] on Twitter.
 237
 238 License
 239 -------
 240
 241 All contents of this package are licensed under the [MIT license].
 242
 243 [beberlei/assert]: https://github.com/beberlei/assert
 244 [assert package]: https://github.com/beberlei/assert
 245 [Composer]: https://getcomposer.org
 246 [Bernhard Schussek]: http://webmozarts.com
 247 [The Community Contributors]: https://github.com/webmozart/assert/graphs/contributors
 248 [issue tracker]: https://github.com/webmozart/assert/issues
 249 [Git repository]: https://github.com/webmozart/assert
 250 [@webmozart]: https://twitter.com/webmozart
 251 [MIT license]: LICENSE
 252 [`Assert`]: src/Assert.php