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=1.2.0)](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 `boolean($value, $message = '')`                | Check that a value is a boolean
 101 `scalar($value, $message = '')`                 | Check that a value is a scalar
 102 `object($value, $message = '')`                 | Check that a value is an object
 103 `resource($value, $type = null, $message = '')` | Check that a value is a resource
 104 `isCallable($value, $message = '')`             | Check that a value is a callable
 105 `isArray($value, $message = '')`                | Check that a value is an array
 106 `isTraversable($value, $message = '')`          | Check that a value is an array or a `\Traversable`
 107 `isInstanceOf($value, $class, $message = '')`   | Check that a value is an `instanceof` a class
 108 `notInstanceOf($value, $class, $message = '')`  | Check that a value is not an `instanceof` a class
 109
 110 ### Comparison Assertions
 111
 112 Method                                          | Description
 113 ----------------------------------------------- | --------------------------------------------------
 114 `true($value, $message = '')`                   | Check that a value is `true`
 115 `false($value, $message = '')`                  | Check that a value is `false`
 116 `null($value, $message = '')`                   | Check that a value is `null`
 117 `notNull($value, $message = '')`                | Check that a value is not `null`
 118 `isEmpty($value, $message = '')`                | Check that a value is `empty()`
 119 `notEmpty($value, $message = '')`               | Check that a value is not `empty()`
 120 `eq($value, $value2, $message = '')`            | Check that a value equals another (`==`)
 121 `notEq($value, $value2, $message = '')`         | Check that a value does not equal another (`!=`)
 122 `same($value, $value2, $message = '')`          | Check that a value is identical to another (`===`)
 123 `notSame($value, $value2, $message = '')`       | Check that a value is not identical to another (`!==`)
 124 `greaterThan($value, $value2, $message = '')`   | Check that a value is greater than another
 125 `greaterThanEq($value, $value2, $message = '')` | Check that a value is greater than or equal to another
 126 `lessThan($value, $value2, $message = '')`      | Check that a value is less than another
 127 `lessThanEq($value, $value2, $message = '')`    | Check that a value is less than or equal to another
 128 `range($value, $min, $max, $message = '')`      | Check that a value is within a range
 129 `oneOf($value, array $values, $message = '')`   | Check that a value is one of a list of values
 130
 131 ### String Assertions
 132
 133 You should check that a value is a string with `Assert::string()` before making
 134 any of the following assertions.
 135
 136 Method                                              | Description
 137 --------------------------------------------------- | --------------------------------------------------
 138 `contains($value, $subString, $message = '')`       | Check that a string contains a substring
 139 `startsWith($value, $prefix, $message = '')`        | Check that a string has a prefix
 140 `startsWithLetter($value, $message = '')`           | Check that a string starts with a letter
 141 `endsWith($value, $suffix, $message = '')`          | Check that a string has a suffix
 142 `regex($value, $pattern, $message = '')`            | Check that a string matches a regular expression
 143 `alpha($value, $message = '')`                      | Check that a string contains letters only
 144 `digits($value, $message = '')`                     | Check that a string contains digits only
 145 `alnum($value, $message = '')`                      | Check that a string contains letters and digits only
 146 `lower($value, $message = '')`                      | Check that a string contains lowercase characters only
 147 `upper($value, $message = '')`                      | Check that a string contains uppercase characters only
 148 `length($value, $length, $message = '')`            | Check that a string has a certain number of characters
 149 `minLength($value, $min, $message = '')`            | Check that a string has at least a certain number of characters
 150 `maxLength($value, $max, $message = '')`            | Check that a string has at most a certain number of characters
 151 `lengthBetween($value, $min, $max, $message = '')`  | Check that a string has a length in the given range
 152 `uuid($value, $message = '')`                       | Check that a string is a valid UUID
 153
 154 ### File Assertions
 155
 156 Method                              | Description
 157 ----------------------------------- | --------------------------------------------------
 158 `fileExists($value, $message = '')` | Check that a value is an existing path
 159 `file($value, $message = '')`       | Check that a value is an existing file
 160 `directory($value, $message = '')`  | Check that a value is an existing directory
 161 `readable($value, $message = '')`   | Check that a value is a readable path
 162 `writable($value, $message = '')`   | Check that a value is a writable path
 163
 164 ### Object Assertions
 165
 166 Method                                                | Description
 167 ----------------------------------------------------- | --------------------------------------------------
 168 `classExists($value, $message = '')`                  | Check that a value is an existing class name
 169 `subclassOf($value, $class, $message = '')`           | Check that a class is a subclass of another
 170 `implementsInterface($value, $class, $message = '')`  | Check that a class implements an interface
 171 `propertyExists($value, $property, $message = '')`    | Check that a property exists in a class/object
 172 `propertyNotExists($value, $property, $message = '')` | Check that a property does not exist in a class/object
 173 `methodExists($value, $method, $message = '')`        | Check that a method exists in a class/object
 174 `methodNotExists($value, $method, $message = '')`     | Check that a method does not exist in a class/object
 175
 176 ### Array Assertions
 177
 178 Method                                      | Description
 179 ------------------------------------------- | --------------------------------------------------
 180 `keyExists($array, $key, $message = '')`    | Check that a key exists in an array
 181 `keyNotExists($array, $key, $message = '')` | Check that a key does not exist in an array
 182 `count($array, $number, $message = '')`     | Check that an array contains a specific number of elements
 183
 184 ### Function Assertions
 185
 186 Method                                      | Description
 187 ------------------------------------------- | -----------------------------------------------------------------------------------------------------
 188 `throws($closure, $class, $message = '')`   | Check that a function throws a certain exception. Subclasses of the exception class will be accepted.
 189
 190 ### Collection Assertions
 191
 192 All of the above assertions can be prefixed with `all*()` to test the contents
 193 of an array or a `\Traversable`:
 194
 195 ```php
 196 Assert::allIsInstanceOf($employees, 'Acme\Employee');
 197 ```
 198
 199 ### Nullable Assertions
 200
 201 All of the above assertions can be prefixed with `nullOr*()` to run the
 202 assertion only if it the value is not `null`:
 203
 204 ```php
 205 Assert::nullOrString($middleName, 'The middle name must be a string or null. Got: %s');
 206 ```
 207
 208 Authors
 209 -------
 210
 211 * [Bernhard Schussek] a.k.a. [@webmozart]
 212 * [The Community Contributors]
 213
 214 Contribute
 215 ----------
 216
 217 Contributions to the package are always welcome!
 218
 219 * Report any bugs or issues you find on the [issue tracker].
 220 * You can grab the source code at the package's [Git repository].
 221
 222 Support
 223 -------
 224
 225 If you are having problems, send a mail to bschussek@gmail.com or shout out to
 226 [@webmozart] on Twitter.
 227
 228 License
 229 -------
 230
 231 All contents of this package are licensed under the [MIT license].
 232
 233 [beberlei/assert]: https://github.com/beberlei/assert
 234 [assert package]: https://github.com/beberlei/assert
 235 [Composer]: https://getcomposer.org
 236 [Bernhard Schussek]: http://webmozarts.com
 237 [The Community Contributors]: https://github.com/webmozart/assert/graphs/contributors
 238 [issue tracker]: https://github.com/webmozart/assert
 239 [Git repository]: https://github.com/webmozart/assert
 240 [@webmozart]: https://twitter.com/webmozart
 241 [MIT license]: LICENSE
 242 [`Assert`]: src/Assert.php