README.md — Booking for Appointments and Events Calendar – Amelia 1.2.32

ameliabooking / vendor / webmozart / assert / README.md

ameliabooking / vendor / webmozart / assert Last commit date

src 6 years ago .editorconfig 6 years ago CHANGELOG.md 6 years ago LICENSE 7 years ago README.md 6 years ago composer.json 6 years ago psalm.xml 6 years ago

README.md

284 lines

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