respect / assertion
The power of Respect\Validation into an assertion library
Installs: 23 028
Dependents: 0
Suggesters: 0
Security: 0
Stars: 27
Watchers: 5
Forks: 1
Open Issues: 1
Requires
- php: ^8.1
- respect/stringifier: ^0.2.0
- respect/validation: ^2.2.4
- symfony/polyfill-mbstring: ^v1.27.0
Requires (Dev)
- malukenho/docheader: ^0.1.8
- phpstan/phpstan: ^1.10.7
- phpstan/phpstan-deprecation-rules: ^1.1.3
- phpstan/phpstan-phpunit: ^1.3.10
- phpunit/phpunit: ^10.0.17
- respect/coding-standard: ^4.0.0
- squizlabs/php_codesniffer: ^3.7.2
Suggests
- ext-mbstring: Multibyte String Functions
README
The power of Validation into an assertion library.
- More than 1.5k assertions
- Support for custom messages
- Support for custom exceptions
For a complete list of assertions, check all the mixin interfaces, and read Validation to understand how each rule/assertion works.
Installation
This package is available on Packagist, and you can install it using Composer.
composer require respect/assertion
Works on PHP 8.1 or above.
Another assertion library
There are PHP assertion libraries that a lot of people in the PHP the community use:
They are both straightforward to use and have a lot of assertions, so there would be no reason to create yet another one. On the other hand, they have fewer assertions than Validation does.
The main idea of Validation is to make it easy to create chain of validations, but when it can get verbose when you want to make a simple assertion.
This library offers a more straightforward assertion API for Validation, which means that you can use all Validation's rules plus your own rules.
Usage
The examples in the document will assume that this library is available in the
autoload and that the class Respect\Assertion\Assert is imported.
The Assert class can use any rule from Validation with the input as its
first argument:
// will throw an exception => 1 must be equals 5 Assert::equals(1, 5); // will throw an exception => "string" must be of type integer Assert::intType('string'); // will not throw an exception Assert::odd(5);
By default, it throws exceptions that are instances of ValidationException, which means you can catch InvalidArgumentException (or LogicException).
Custom messages
The exceptions that Assert throws are the same that Validation throws.
That allows you to customize the error messages using templates:
// will throw an exception => I was expecting 5, but you gave be 1 Assert::equals(1, 5, 'I was expecting {{compareTo}}, but you gave be {{input}}');
Custom exceptions
Instead of throwing Validation exceptions, you can use your exceptions:
// will throw the defined DomainException Assert::between(42, 1, 10, new DomainException('Something is not right'));
That can be very useful if you want to throw specific exceptions for your application. That was a great idea from Malukenho!
Chained assertions (that())
You can chain assertions using Assert::that($input), which allows you to
perform multiple assertions to the same input with less duplication.
// will throw an exception => I expected a positive number Assert::that(-1) ->intVal('The number {{input}} must be an integer') ->positive('The number must be positive') ->lessThan(4);
In the example above, as soon as any assertion fails, it will throw an exception. If you wish to chain validations and only check them all simultaneously, we suggest you use the API from Validation.
You can also customize a message or exception for the whole chain.
// will throw an exception => The number must be valid Assert::that(0, new DomainException('The number must be valid')) ->positive() ->greaterThan(5); // will throw an exception => But it is not greater than 5, though Assert::that(3, 'The number must be valid') ->positive() ->greaterThan(5, 'But it is not greater than 5, though');
Note that the customization on a specific assertion will overwrite the customization on the whole chain.
You can also apply the effect of the prefixes listed below to the whole chain.
// will throw an exception => 3 (the length of the input) must equal 4 Assert::that(['names' => ['Respect', 'Assertion'], 'options' => [1, 2, 3]]) ->all()->arrayType() ->key('names')->allStringType() ->key('options')->lengthEquals(4);
There are also some special methods that allow you to create a chain of assertions.
thatAll(): assert all elements in the input with the subsequent assertions.thatNot(): assert the input inverting the subsequent assertions.thatNullOr(): assert the input if it is notnullwith the subsequent assertions.thatKey(): assert a key from the input with the subsequent assertions.thatProperty(): assert a property from the input with the subsequent assertions.
Prefixes
With Assertion, you can use any Validation rule, but it also allows you to use them with prefixes that simplify some operations.
all*(): asserting all elements in an input
Assertions can be executed with the all prefix which will assert all elements
in the input with the prefixed assertion:
// will throw an exception => "3" (like all items of the input) must be of type integer Assert::allIntType([1, 2, '3']);
In some cases, you might want to perform multiple assertions to all elements. You
can use thatAll() chain of assertions that will assert all elements in the input
with the subsequent assertions:
// will throw an exception => 3 (like all items of the input) must be between 1 and 2 Assert::thatAll([1, 2, 2, 1, 3]) ->intVal() ->between(1, 2);
If you want to perform multiple assertions to all elements, but you also want to
perform other assertions to the input, you can that()->all():
// will throw an exception => 5 (the length of the input) must be less than 4 Assert::that([1, 2, 2, 1, 3]) ->arrayType() ->notEmpty() ->lengthGreaterThan(3) ->all()->intVal()->between(1, 2);
nullOr*(): asserting the value of an input or null
Assertions can be executed with the nullOr prefix which will assert only if
the value of the input it not null.
// will throw an exception => 42 must be negative Assert::nullOrNegative(42); // will not throw an exception Assert::nullOrNegative(null); // will throw an exception => 5 must be between 1 and 4 Assert::nullOrBetween(5, 1, 4); // will not throw an exception Assert::nullOrBetween(null, 1, 4);
In some cases, you might want to perform multiple assertions to a value in case
it is not null. In this case, you can use thatNullOr():
// will throw an exception => 6 must be a valid prime number Assert::thatNullOr(6) ->positive() ->between(1, 10) ->primeNumber(); // will not throw an exception Assert::thatNullOr(null) ->positive() ->between(1, 10) ->primeNumber();
For convenience, you might also use the that()->nullOr():
Assert::that(6) ->nullOr()->positive()->between(1, 10)->primeNumber();
not*(): inverting assertions
You can execute assertions with the not prefix, which will assert the opposite
of the prefixed assertion:
// will throw an exception => 2 must not be an even number Assert::notEven(2); // will throw an exception => 3 must not be in `{ 1, 2, 3, 4 }` Assert::notIn(3, [1, 2, 3, 4]);
If you need to invert more than a few rules, it might be easier to use thatNot()
and that()->not():
// will throw an exception => "1" must not be positive Assert::thatNot('1') ->intType() ->positive() ->between(1, 3); // will throw an exception => "1" must not be positive Assert::that('1') ->not()->intType()->positive()->between(1, 3);
key*(): asserting a key in an array
You can use keyPresent to check whether a key is present in an array.
// will throw an exception => bar must be present Assert::keyPresent(['foo' => true], 'bar');
You can use keyNotPresent to check whether a key is present in an array.
// will throw an exception => bar must not be present Assert::keyNotPresent(['bar' => 2], 'bar');
Also, with the key prefix it will assert the value of the array that contains
the specified key.
// will throw an exception => foo must equal 3 Assert::keyEquals(['foo' => 2], 'foo', 3); // will throw an exception => bar must be negative Assert::keyNegative(['bar' => 2], 'bar'); // will throw an exception => bar must not be of type integer Assert::keyNotIntType(['bar' => 2], 'bar'); // will throw an exception => baz must be present Assert::keyNegative(['foo' => 2], 'baz'); // will throw an exception => foo must exist Assert::keyExists(['foo' => '/path/to/file.txt'], 'foo');
Not that keyExists assertion, will assert whether the value of key foo exists
in the Filesystem.
If you want to perform multiple assertions to the key of an input, you can use
thatKey():
// will throw an exception => 9 (the length of the input) must be less than 4 Assert::thatKey(['foo' => 'my-string'], 'foo') ->stringType() ->startsWith('my-') ->lengthLessThan(4);
If you want to perform multiple key assertions to the same input, you can use
that()->key():
// will throw an exception => bar must be less than 40 Assert::that(['foo' => 'my-string', 'bar' => 42]) ->arrayType() ->key('foo')->stringType()->startsWith('my-') ->key('bar')->intType()->positive()->lessThan(40);
property*(): asserting a property in an object
We'll use the object below as input in the examples that follow.
$input = new stdClass(); $input->foo = 1;
You can use propertyPresent to check whether a property is present in an object.
// will throw an exception => Attribute bar must be present Assert::propertyPresent($input, 'bar');
You can use propertyNotPresent to check whether a property is not present in
an object.
// will throw an exception => Attribute foo must not be present Assert::propertyNotPresent($input, 'foo');
With the property prefix, you can make assertions with the value of a specific
object's property.
// will throw an exception => foo must equal 3 Assert::propertyEquals($input, 'foo', 3); // will throw an exception => foo must be negative Assert::propertyNegative($input, 'foo'); // will throw an exception => foo must not be of type integer Assert::propertyNotIntType($input, 'foo'); // will throw an exception => Attribute baz must be present Assert::propertyNegative($input, 'baz'); // will throw an exception => foo must exists Assert::propertyExists($input, 'foo');
Note that the propertyExists assertion will assert whether the value of
property foo exists in the FileSystem.
If you want to perform multiple assertions to a property of an object, you can
use thatProperty():
// will throw an exception => foo must be greater than 5 Assert::thatProperty($input, 'foo') ->intType() ->positive() ->greaterThan(5);
If you want to perform multiple key assertions to the same input, you can use
that()->property():
// will throw an exception => foo must be greater than 5 Assert::that($input) ->instance(stdClass::class) ->property('foo')->intType()->positive()->greaterThan(5);
length*(): asserting the length of an input
Assertions can be executed with the length prefix which will assert the length
of the input with the prefixed assertion:
// will throw an exception => 6 (the length of the input) must be between 10 and 15 Assert::lengthBetween('string', 10, 15);
The length prefix can also be used with arrays and instances of Countable:
// will throw an exception => 4 (the length of the input) must be an odd number Assert::lengthOdd([1, 2, 3, 4]); // will throw an exception => 3 (the length of the input) must be an even number Assert::lengthEven(new ArrayObject([1, 2, 3]));
This library also allows you to use the not prefix after the length prefix:
// will throw an exception => 2 (the length of the input) must not be multiple of 2 Assert::lengthNotMultiple([1, 2], 2);
max*(): asserting the maximum of an input
Assertions can be executed with the max prefix which will assert the maximum
value of the input with the prefixed assertion:
// will throw an exception => 3 (the maximum of the input) must be between 5 and 10 Assert::maxBetween([1, 2, 3], 5, 10);
The max prefix can be used with any iterable value:
// will throw an exception => 3 (the maximum of the input) must be an even number Assert::maxEven([1, 2, 3]); // will throw an exception => 60 (the maximum of the input) must be a valid perfect square Assert::maxPerfectSquare(new ArrayObject([45, 60, 20]));
This library also allows you to use the not prefix after the max prefix:
// will throw an exception => 23 (the maximum of the input) must not be positive Assert::maxNotPositive([23, 7, 20]);
min*(): asserting the minimum of an input
Assertions can be executed with the min prefix which will assert the minimum
value of the input with the prefixed assertion:
// will throw an exception => 1 (the minimum of the input) must be between 5 and 10 Assert::minBetween([1, 2, 3], 5, 10);
The min prefix can be used with any iterable value:
// will throw an exception => 1 (the minimum of the input) must be an even number Assert::minEven([1, 2, 3]); // will throw an exception => 20 (the minimum of the input) must be a valid perfect square Assert::minPerfectSquare(new ArrayObject([45, 60, 20]));
This library also allows you to use the not prefix after the min prefix:
// will throw an exception => 7 (the minimum of the input) must not be positive Assert::minNotPositive([23, 7, 20]);