Download the PHP package respect/assertion without Composer

Respect\Assertion

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.

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:

• beberlei/assert
• webmozart/assert

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:

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:

Custom exceptions

Instead of throwing Validation exceptions, you can use your exceptions:

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.

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.

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.

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 not null with 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:

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:

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():

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.

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():

For convenience, you might also use the that()->nullOr():

not*(): inverting assertions

You can execute assertions with the not prefix, which will assert the opposite of the prefixed assertion:

If you need to invert more than a few rules, it might be easier to use thatNot() and that()->not():

key*(): asserting a key in an array

You can use keyPresent to check whether a key is present in an array.

You can use keyNotPresent to check whether a key is present in an array.

Also, with the key prefix it will assert the value of the array that contains the specified key.

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():

If you want to perform multiple key assertions to the same input, you can use that()->key():

property*(): asserting a property in an object

We'll use the object below as input in the examples that follow.

You can use propertyPresent to check whether a property is present in an object.

You can use propertyNotPresent to check whether a property is not present in an object.

With the property prefix, you can make assertions with the value of a specific object's property.

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():

If you want to perform multiple key assertions to the same input, you can use that()->property():

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:

The length prefix can also be used with arrays and instances of Countable:

This library also allows you to use the not prefix after the length prefix:

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:

The max prefix can be used with any iterable value:

This library also allows you to use the not prefix after the max prefix:

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:

The min prefix can be used with any iterable value:

This library also allows you to use the not prefix after the min prefix: