Assert provides functions for assorting preconditions (such as parameter types) and postconditions. More...

Static Public Member Functions
static	precondition ( $condition, $description)
	Checks a precondition, that is, throws a PreconditionException if $condition is false.

static	parameter ( $condition, $name, $description)
	Checks a parameter, that is, throws a ParameterAssertionException if $condition is false.

static	parameterType ( $types, $value, $name)
	Checks an parameter's type, that is, throws a InvalidArgumentException if $value is not of $type.

static	parameterKeyType ( $type, $value, $name)

static	parameterElementType ( $types, $value, $name)
	Checks the type of all elements of an parameter, assuming the parameter is an array, that is, throws a ParameterElementTypeException if any elements in $value are not of $type.

static	nonEmptyString ( $value, $name)

static	postcondition ( $condition, $description)
	Checks a postcondition, that is, throws a PostconditionException if $condition is false.

static	invariant ( $condition, $description)
	Checks an invariant, that is, throws a InvariantException if $condition is false.

Detailed Description

Assert provides functions for assorting preconditions (such as parameter types) and postconditions.

It is intended as a safer alternative to PHP's assert() function.

Note that assertions evaluate expressions and add function calls, so using assertions may have a negative impact on performance when used in performance hotspots. The idea if this class is to have a neat tool for assertions if and when they are needed. It is not recommended to place assertions all over the code indiscriminately.

For more information, see the README file.

Since: 0.1.0

@license MIT

Author: Daniel Kinzler; Thiemo Kreuz

Copyright: Wikimedia Deutschland e.V.

Member Function Documentation

◆ invariant()

static Wikimedia\Assert\Assert::invariant	(		$condition,
			$description )

static

Checks an invariant, that is, throws a InvariantException if $condition is false.

This is very similar Assert::postcondition() but is intended for use throughout the code.

Note: The $condition is expected to be falsifiable. If you are trying to indicate that a code path is unreachable, use ‘throw new UnreachableException( 'why this code is unreachable’ ) instead ofAssert::invariant( false, '…' )`. Code checking tools will complain about the latter.; This is intended for double checking in the implementation of complex algorithms. Note however that it should not be used in performance hotspots, since evaluating $condition and calling invariant() costs time.

Since: 0.1.0

Parameters

bool	$condition
string	$description	The message to include in the exception if the condition fails.

Exceptions

InvariantException @phan-assert-true-condition $condition

◆ nonEmptyString()

static Wikimedia\Assert\Assert::nonEmptyString	(		$value,
			$name )

static

Since: 0.3.0

Parameters

string	$value
string	$name

Exceptions

ParameterTypeException if $value is not a non-empty string. @phan-assert non-empty-string $value

◆ parameter()

static Wikimedia\Assert\Assert::parameter	(	$condition,
		$name,
		$description )

static

Checks a parameter, that is, throws a ParameterAssertionException if $condition is false.

This is similar to Assert::precondition().

Note: This is intended for checking parameters in constructors and setters. Checking parameters in every function call is not recommended, since it may have a negative impact on performance.

Since: 0.1.0

Parameters

bool	$condition
string	$name	The name of the parameter that was checked.
string	$description	The message to include in the exception if the condition fails.

Exceptions

ParameterAssertionException if $condition is not true. @phan-assert-true-condition $condition

◆ parameterElementType()

static Wikimedia\Assert\Assert::parameterElementType	(	$types,
		$value,
		$name )

static

Checks the type of all elements of an parameter, assuming the parameter is an array, that is, throws a ParameterElementTypeException if any elements in $value are not of $type.

Note: This is intended for checking parameters in constructors and setters. Checking parameters in every function call is not recommended, since it may have a negative impact on performance.

Since: 0.1.0

Parameters

string \| string[]	$types	The elements' expected type. Can be the name of a native type or a class or interface. Multiple types can be given in an array (or a string separated by a pipe character ("\|"), for compatibility with versions before 0.5.0).
array	$value	The parameter's actual value. If this is not an array, a ParameterTypeException is raised.
string	$name	The name of the parameter that was checked.

Exceptions

ParameterTypeException	If $value is not an array.
ParameterElementTypeException	If an element of $value is not of type (or, for objects, is not an instance of) $type.

◆ parameterKeyType()

static Wikimedia\Assert\Assert::parameterKeyType	(	$type,
		$value,
		$name )

static

Since: 0.3.0

Parameters

string	$type	Either "integer" or "string". Mixing "integer\|string" is not supported because this is PHP's default anyway. It is of no value to check this.
array	$value	The parameter's actual value. If this is not an array, a ParameterTypeException is raised.
string	$name	The name of the parameter that was checked.

Exceptions

ParameterTypeException if one of the keys in the array $value is not of type $type.

◆ parameterType()

static Wikimedia\Assert\Assert::parameterType	(	$types,
		$value,
		$name )

static

Checks an parameter's type, that is, throws a InvalidArgumentException if $value is not of $type.

This is really a special case of Assert::precondition().

Note: This is intended for checking parameters in constructors and setters. Checking parameters in every function call is not recommended, since it may have a negative impact on performance.; If possible, type hints should be used instead of calling this function. It is intended for cases where type hints to not work, e.g. for checking union types.

Since: 0.1.0

Parameters

string \| string[]	$types	The parameter's expected type. Can be the name of a native type or a class or interface, or a list of such names. For compatibility with versions before 0.4.0, multiple types can also be given separated by pipe characters ("\|").
mixed	$value	The parameter's actual value.
string	$name	The name of the parameter that was checked.

Exceptions

ParameterTypeException if $value is not of type (or, for objects, is not an instance of) $type.

◆ postcondition()

static Wikimedia\Assert\Assert::postcondition	(		$condition,
			$description )

static

Checks a postcondition, that is, throws a PostconditionException if $condition is false.

This is very similar Assert::invariant() but is intended for use only after a computation is complete.

Note: This is intended for double checking in the implementation of complex algorithms. Note however that it should not be used in performance hotspots, since evaluating $condition and calling postcondition() costs time.

Since: 0.1.0

Parameters

bool	$condition
string	$description	The message to include in the exception if the condition fails.

Exceptions

PostconditionException @phan-assert-true-condition $condition

◆ precondition()

static Wikimedia\Assert\Assert::precondition	(		$condition,
			$description )

static

Checks a precondition, that is, throws a PreconditionException if $condition is false.

For checking call parameters, use Assert::parameter() instead.

This is provided for completeness, most preconditions should be covered by Assert::parameter() and related assertions.

See also: parameter()

Note: This is intended mostly for checking preconditions in constructors and setters, or before using parameters in complex computations. Checking preconditions in every function call is not recommended, since it may have a negative impact on performance.

Since: 0.1.0

Parameters

bool	$condition
string	$description	The message to include in the exception if the condition fails.

Exceptions

PreconditionException if $condition is not true. @phan-assert-true-condition $condition

The documentation for this class was generated from the following file:

src/Assert.php

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ invariant()

◆ nonEmptyString()

◆ parameter()

◆ parameterElementType()

◆ parameterKeyType()

◆ parameterType()

◆ postcondition()

◆ precondition()