Chris@0: Webmozart Assert
Chris@0: ================
Chris@0: 
Chris@12: [![Build Status](https://travis-ci.org/webmozart/assert.svg?branch=master)](https://travis-ci.org/webmozart/assert)
Chris@0: [![Build status](https://ci.appveyor.com/api/projects/status/lyg83bcsisrr94se/branch/master?svg=true)](https://ci.appveyor.com/project/webmozart/assert/branch/master)
Chris@0: [![Latest Stable Version](https://poser.pugx.org/webmozart/assert/v/stable.svg)](https://packagist.org/packages/webmozart/assert)
Chris@0: [![Total Downloads](https://poser.pugx.org/webmozart/assert/downloads.svg)](https://packagist.org/packages/webmozart/assert)
Chris@0: 
Chris@0: Latest release: [1.2.0](https://packagist.org/packages/webmozart/assert#1.2.0)
Chris@0: 
Chris@0: PHP >= 5.3.9
Chris@0: 
Chris@0: This library contains efficient assertions to test the input and output of
Chris@0: your methods. With these assertions, you can greatly reduce the amount of coding
Chris@0: needed to write a safe implementation.
Chris@0: 
Chris@0: All assertions in the [`Assert`] class throw an `\InvalidArgumentException` if 
Chris@0: they fail.
Chris@0: 
Chris@0: FAQ
Chris@0: ---
Chris@0: 
Chris@0: **What's the difference to [beberlei/assert]?**
Chris@0: 
Chris@0: This library is heavily inspired by Benjamin Eberlei's wonderful [assert package],
Chris@0: but fixes a usability issue with error messages that can't be fixed there without
Chris@0: breaking backwards compatibility.
Chris@0: 
Chris@0: This package features usable error messages by default. However, you can also 
Chris@0: easily write custom error messages:
Chris@0: 
Chris@0: ```
Chris@0: Assert::string($path, 'The path is expected to be a string. Got: %s');
Chris@0: ```
Chris@0: 
Chris@0: In [beberlei/assert], the ordering of the `%s` placeholders is different for 
Chris@0: every assertion. This package, on the contrary, provides consistent placeholder 
Chris@0: ordering for all assertions:
Chris@0: 
Chris@0: * `%s`: The tested value as string, e.g. `"/foo/bar"`.
Chris@0: * `%2$s`, `%3$s`, ...: Additional assertion-specific values, e.g. the
Chris@0:   minimum/maximum length, allowed values, etc.
Chris@0:   
Chris@0: Check the source code of the assertions to find out details about the additional
Chris@0: available placeholders.
Chris@0: 
Chris@0: Installation
Chris@0: ------------
Chris@0: 
Chris@0: Use [Composer] to install the package:
Chris@0: 
Chris@0: ```
Chris@0: $ composer require webmozart/assert
Chris@0: ```
Chris@0: 
Chris@0: Example
Chris@0: -------
Chris@0: 
Chris@0: ```php
Chris@0: use Webmozart\Assert\Assert;
Chris@0: 
Chris@0: class Employee
Chris@0: {
Chris@0:     public function __construct($id)
Chris@0:     {
Chris@0:         Assert::integer($id, 'The employee ID must be an integer. Got: %s');
Chris@0:         Assert::greaterThan($id, 0, 'The employee ID must be a positive integer. Got: %s');
Chris@0:     }
Chris@0: }
Chris@0: ```
Chris@0: 
Chris@0: If you create an employee with an invalid ID, an exception is thrown:
Chris@0: 
Chris@0: ```php
Chris@0: new Employee('foobar');
Chris@0: // => InvalidArgumentException: 
Chris@0: //    The employee ID must be an integer. Got: string
Chris@0: 
Chris@0: new Employee(-10);
Chris@0: // => InvalidArgumentException: 
Chris@0: //    The employee ID must be a positive integer. Got: -10
Chris@0: ```
Chris@0: 
Chris@0: Assertions
Chris@0: ----------
Chris@0: 
Chris@0: The [`Assert`] class provides the following assertions:
Chris@0: 
Chris@0: ### Type Assertions
Chris@0: 
Chris@12: Method                                                   | Description
Chris@12: -------------------------------------------------------- | --------------------------------------------------
Chris@12: `string($value, $message = '')`                          | Check that a value is a string
Chris@12: `stringNotEmpty($value, $message = '')`                  | Check that a value is a non-empty string
Chris@12: `integer($value, $message = '')`                         | Check that a value is an integer
Chris@12: `integerish($value, $message = '')`                      | Check that a value casts to an integer
Chris@12: `float($value, $message = '')`                           | Check that a value is a float
Chris@12: `numeric($value, $message = '')`                         | Check that a value is numeric
Chris@12: `natural($value, $message= ''')`                         | Check that a value is a non-negative integer
Chris@12: `boolean($value, $message = '')`                         | Check that a value is a boolean
Chris@12: `scalar($value, $message = '')`                          | Check that a value is a scalar
Chris@12: `object($value, $message = '')`                          | Check that a value is an object
Chris@12: `resource($value, $type = null, $message = '')`          | Check that a value is a resource
Chris@12: `isCallable($value, $message = '')`                      | Check that a value is a callable
Chris@12: `isArray($value, $message = '')`                         | Check that a value is an array
Chris@12: `isTraversable($value, $message = '')`  (deprecated)     | Check that a value is an array or a `\Traversable`
Chris@12: `isIterable($value, $message = '')`                      | Check that a value is an array or a `\Traversable`
Chris@12: `isCountable($value, $message = '')`                     | Check that a value is an array or a `\Countable`
Chris@12: `isInstanceOf($value, $class, $message = '')`            | Check that a value is an `instanceof` a class
Chris@12: `isInstanceOfAny($value, array $classes, $message = '')` | Check that a value is an `instanceof` a at least one class on the array of classes
Chris@12: `notInstanceOf($value, $class, $message = '')`           | Check that a value is not an `instanceof` a class
Chris@12: `isArrayAccessible($value, $message = '')`               | Check that a value can be accessed as an array
Chris@0: 
Chris@0: ### Comparison Assertions
Chris@0: 
Chris@0: Method                                          | Description
Chris@0: ----------------------------------------------- | --------------------------------------------------
Chris@0: `true($value, $message = '')`                   | Check that a value is `true`
Chris@0: `false($value, $message = '')`                  | Check that a value is `false`
Chris@0: `null($value, $message = '')`                   | Check that a value is `null`
Chris@0: `notNull($value, $message = '')`                | Check that a value is not `null`
Chris@0: `isEmpty($value, $message = '')`                | Check that a value is `empty()`
Chris@0: `notEmpty($value, $message = '')`               | Check that a value is not `empty()`
Chris@0: `eq($value, $value2, $message = '')`            | Check that a value equals another (`==`)
Chris@0: `notEq($value, $value2, $message = '')`         | Check that a value does not equal another (`!=`)
Chris@0: `same($value, $value2, $message = '')`          | Check that a value is identical to another (`===`)
Chris@0: `notSame($value, $value2, $message = '')`       | Check that a value is not identical to another (`!==`)
Chris@0: `greaterThan($value, $value2, $message = '')`   | Check that a value is greater than another
Chris@0: `greaterThanEq($value, $value2, $message = '')` | Check that a value is greater than or equal to another
Chris@0: `lessThan($value, $value2, $message = '')`      | Check that a value is less than another
Chris@0: `lessThanEq($value, $value2, $message = '')`    | Check that a value is less than or equal to another
Chris@0: `range($value, $min, $max, $message = '')`      | Check that a value is within a range
Chris@0: `oneOf($value, array $values, $message = '')`   | Check that a value is one of a list of values
Chris@0: 
Chris@0: ### String Assertions
Chris@0: 
Chris@0: You should check that a value is a string with `Assert::string()` before making
Chris@0: any of the following assertions.
Chris@0: 
Chris@0: Method                                              | Description
Chris@12: --------------------------------------------------- | -----------------------------------------------------------------
Chris@0: `contains($value, $subString, $message = '')`       | Check that a string contains a substring
Chris@12: `notContains($value, $subString, $message = '')`    | Check that a string does not contains a substring
Chris@0: `startsWith($value, $prefix, $message = '')`        | Check that a string has a prefix
Chris@0: `startsWithLetter($value, $message = '')`           | Check that a string starts with a letter
Chris@0: `endsWith($value, $suffix, $message = '')`          | Check that a string has a suffix
Chris@0: `regex($value, $pattern, $message = '')`            | Check that a string matches a regular expression
Chris@17: `notRegex($value, $pattern, $message = '')`         | Check that a string does not match a regular expression
Chris@0: `alpha($value, $message = '')`                      | Check that a string contains letters only
Chris@0: `digits($value, $message = '')`                     | Check that a string contains digits only
Chris@0: `alnum($value, $message = '')`                      | Check that a string contains letters and digits only
Chris@0: `lower($value, $message = '')`                      | Check that a string contains lowercase characters only
Chris@0: `upper($value, $message = '')`                      | Check that a string contains uppercase characters only
Chris@0: `length($value, $length, $message = '')`            | Check that a string has a certain number of characters
Chris@0: `minLength($value, $min, $message = '')`            | Check that a string has at least a certain number of characters
Chris@0: `maxLength($value, $max, $message = '')`            | Check that a string has at most a certain number of characters
Chris@0: `lengthBetween($value, $min, $max, $message = '')`  | Check that a string has a length in the given range
Chris@0: `uuid($value, $message = '')`                       | Check that a string is a valid UUID
Chris@17: `ip($value, $message = '')`                         | Check that a string is a valid IP (either IPv4 or IPv6)
Chris@17: `ipv4($value, $message = '')`                       | Check that a string is a valid IPv4
Chris@17: `ipv6($value, $message = '')`                       | Check that a string is a valid IPv6
Chris@12: `notWhitespaceOnly($value, $message = '')`          | Check that a string contains at least one non-whitespace character
Chris@0: 
Chris@0: ### File Assertions
Chris@0: 
Chris@0: Method                              | Description
Chris@0: ----------------------------------- | --------------------------------------------------
Chris@0: `fileExists($value, $message = '')` | Check that a value is an existing path
Chris@0: `file($value, $message = '')`       | Check that a value is an existing file
Chris@0: `directory($value, $message = '')`  | Check that a value is an existing directory
Chris@0: `readable($value, $message = '')`   | Check that a value is a readable path
Chris@0: `writable($value, $message = '')`   | Check that a value is a writable path
Chris@0: 
Chris@0: ### Object Assertions
Chris@0: 
Chris@0: Method                                                | Description
Chris@0: ----------------------------------------------------- | --------------------------------------------------
Chris@0: `classExists($value, $message = '')`                  | Check that a value is an existing class name
Chris@0: `subclassOf($value, $class, $message = '')`           | Check that a class is a subclass of another
Chris@17: `interfaceExists($value, $message = '')`              | Check that a value is an existing interface name
Chris@0: `implementsInterface($value, $class, $message = '')`  | Check that a class implements an interface
Chris@0: `propertyExists($value, $property, $message = '')`    | Check that a property exists in a class/object
Chris@0: `propertyNotExists($value, $property, $message = '')` | Check that a property does not exist in a class/object
Chris@0: `methodExists($value, $method, $message = '')`        | Check that a method exists in a class/object
Chris@0: `methodNotExists($value, $method, $message = '')`     | Check that a method does not exist in a class/object
Chris@0: 
Chris@0: ### Array Assertions
Chris@0: 
Chris@12: Method                                             | Description
Chris@12: -------------------------------------------------- | ------------------------------------------------------------------
Chris@12: `keyExists($array, $key, $message = '')`           | Check that a key exists in an array
Chris@12: `keyNotExists($array, $key, $message = '')`        | Check that a key does not exist in an array
Chris@12: `count($array, $number, $message = '')`            | Check that an array contains a specific number of elements
Chris@12: `minCount($array, $min, $message = '')`            | Check that an array contains at least a certain number of elements
Chris@12: `maxCount($array, $max, $message = '')`            | Check that an array contains at most a certain number of elements
Chris@12: `countBetween($array, $min, $max, $message = '')`  | Check that an array has a count in the given range
Chris@17: `isList($array, $message = '')`                    | Check that an array is a non-associative list
Chris@17: `isMap($array, $message = '')`                     | Check that an array is associative and has strings as keys
Chris@0: 
Chris@0: ### Function Assertions
Chris@0: 
Chris@0: Method                                      | Description
Chris@0: ------------------------------------------- | -----------------------------------------------------------------------------------------------------
Chris@0: `throws($closure, $class, $message = '')`   | Check that a function throws a certain exception. Subclasses of the exception class will be accepted.
Chris@0: 
Chris@0: ### Collection Assertions
Chris@0: 
Chris@0: All of the above assertions can be prefixed with `all*()` to test the contents
Chris@0: of an array or a `\Traversable`:
Chris@0: 
Chris@0: ```php
Chris@0: Assert::allIsInstanceOf($employees, 'Acme\Employee');
Chris@0: ```
Chris@0: 
Chris@0: ### Nullable Assertions
Chris@0: 
Chris@0: All of the above assertions can be prefixed with `nullOr*()` to run the
Chris@0: assertion only if it the value is not `null`:
Chris@0: 
Chris@0: ```php
Chris@0: Assert::nullOrString($middleName, 'The middle name must be a string or null. Got: %s');
Chris@0: ```
Chris@0: 
Chris@0: Authors
Chris@0: -------
Chris@0: 
Chris@0: * [Bernhard Schussek] a.k.a. [@webmozart]
Chris@0: * [The Community Contributors]
Chris@0: 
Chris@0: Contribute
Chris@0: ----------
Chris@0: 
Chris@0: Contributions to the package are always welcome!
Chris@0: 
Chris@0: * Report any bugs or issues you find on the [issue tracker].
Chris@0: * You can grab the source code at the package's [Git repository].
Chris@0: 
Chris@0: Support
Chris@0: -------
Chris@0: 
Chris@0: If you are having problems, send a mail to bschussek@gmail.com or shout out to
Chris@0: [@webmozart] on Twitter.
Chris@0: 
Chris@0: License
Chris@0: -------
Chris@0: 
Chris@0: All contents of this package are licensed under the [MIT license].
Chris@0: 
Chris@0: [beberlei/assert]: https://github.com/beberlei/assert
Chris@0: [assert package]: https://github.com/beberlei/assert
Chris@0: [Composer]: https://getcomposer.org
Chris@0: [Bernhard Schussek]: http://webmozarts.com
Chris@0: [The Community Contributors]: https://github.com/webmozart/assert/graphs/contributors
Chris@12: [issue tracker]: https://github.com/webmozart/assert/issues
Chris@0: [Git repository]: https://github.com/webmozart/assert
Chris@0: [@webmozart]: https://twitter.com/webmozart
Chris@0: [MIT license]: LICENSE
Chris@0: [`Assert`]: src/Assert.php