Webmozart Assert

You can prefix any assertion with all*() to test every element within an array or a \Traversable object.

Assert::allIsInstanceOf($employees, 'Acme\\Employee');

You can prefix any assertion with nullOr*() to run the assertion only if the value is not null. This is useful for optional parameters.

Assert::nullOrString($middleName, 'The middle name must be a string or null. Got: %s');

Install the package using Composer to add efficient assertions to your project for testing method inputs and outputs.

composer require webmozart/assert

You can provide custom error messages to assertions. The library uses consistent placeholder ordering:

• %s: The tested value as a string (e.g., "/foo/bar").
• %2$s, %3$s, etc.: Additional assertion-specific values, such as minimum/maximum length or allowed values.

Example:

Assert::string($path, 'The path is expected to be a string. Got: %s');

Webmozart Assert functions are annotated to support Psalm's assertion syntax. To enable type inference for return types in Psalm (available in version 2.x), you must enable the native Psalm plugin.

vendor/bin/psalm-plugin enable webmozart/assert

To avoid unnecessary computation when an assertion passes, you can provide a callable as the message argument. The callable is only executed if the assertion fails.

Assert::string($value, fn() => expensiveMessage());

Import the Webmozart\\Assert\\\Assert class to perform assertions. If an assertion fails, a Webmozart\\Assert\\\InvalidArgumentException is thrown.

use Webmozart\\Assert\\\Assert;

class Employee
{
    public function __construct($id)
    {
        Assert::integer($id, 'The employee ID must be an integer. Got: %s');
        Assert::greaterThan($id, 0, 'The employee ID must be a positive integer. Got: %s');
    }
}

You can extend the Assert class to change its behavior or add your own assertions by overriding specific protected or public methods.

Methods you can override:

• public static function __callStatic($name, $arguments): Used to 'create' the nullOr and all versions of assertions.
• protected static function valueToString($value): Used for error messages to convert a value to a string.
• protected static function typeToString($value): Used for error messages to convert a value to a string representing its type.
• protected static function strlen($value): Used to calculate string length (uses mb_strlen if available).
• protected static function reportInvalidArgument($message): Called when an assertion fails. You can use this to throw custom exceptions or log errors.