Download the PHP package fabstract/assert without Composer

Assert

This library introduces a set of methods to check if a variable or variables obey some restrictions. These methods are especially useful for checking method parameters. All methods throw AssertionExceptionInterface should one or more assertions fail.

Imagine you write a function that adds two numbers and returns the result, like this:

Here you can just write some assertions to make sure your function gets valid parameters, or do not run at all otherwise.

The main benefit of using this library is to get meaningful exception messages. Consider below:

Imagine addToArray function gets passed new stdClass() as its first parameter. Without assertion, PHP will generate following message:

 PHP Fatal error:  Illegal offset type

but with assertion, you will get this message:

Variable with name "key" is expected to be valid array index, given stdClass.

which is way more meaningful.

By using assertion methods, you can prevent getting Trying to get property of non object messages almost %100 of the time, thus debug a lot easier.

Installation

Note: PHP 7.1 or higher is required.

1. Install composer.
2. Run composer require fabstract/assert.

Functions

• General operations
  • isObject($value, [$name])
  • isNotNull($value, [$name])
  • isEqualTo($value, $expected, [$name])
  • isNotEqualTo($value, $expected, [$name])
  • isTypeExists($value, [$name])
  • isClassExists($value, [$name])
  • isInterfaceExists($value, [$name])
  • isMethodExists($object_or_class_name, $method, [$name])
  • isInArray($value, $allowed_value_list, [$type_strict], [$name])
• Type checkers
  • isCallable($value, [$name])
  • isString($value, [$name])
  • isBoolean($value, [$name])
  • isInt($value, [$name])
  • isStringOrInt($value, [$name])
  • isIntOrFloat($value, [$name])
  • isFloat($value, [$name])
  • isValidArrayIndex($value, [$name])
  • isArray($value, [$name])
  • isNumeric($value, [$name])
  • isType($value, $type, [$name])
  • isInstanceOf($value, $type, [$name])
  • isOneOfTypes($value, $type_list, [$name])
  • isImplements($value, $interface, [$name])
  • isChildOf($value, $parent, [$name])
• String operations
  • isNotEmptyString($value, [$accept_blanks], [$name])
  • startsWith($value, $starts_with, [$name])
  • isRegexMatches($value, $regex_pattern, [$name])
  • isRegexPattern($value, [$name])
  • isNotNullOrWhiteSpace($value, [$name])
  • isInStringArray($value, $allowed_string_list, [$name])
• Array operations
  • isNotEmptyArray($value, [$name])
  • isArrayOfType($value, $type, [$name])
  • isArrayOfString($value, [$name])
  • isSequentialArray($value, [$accept_empty], [$name])
• Int operations
  • isPositiveInt($value, [$name])
  • isNotNegativeInt($value, [$name])
• Number operations
  • isPositiveNumber($value, [$allow_string], [$name])
  • isNotNegativeNumber($value, [$allow_string], [$name])

General operations

isObject($value, $name = null)

Checks if given $value is object. Throws exception if fails.

Optional parameter $name is used for exceptions. See exceptions for more info.

isNotNull($value, $name = null)

Checks if given $value is not null. Throws exception if fails.

Optional parameter $name is used for exceptions. See exceptions for more info.

isEqualTo($value, $excepted, $name = null)

Checks if given $value is equal to $expected. Throws exception if fails.

This method is type safe, meaning that it will fail when $value is integer 1 and $expected is string '1'.

Optional parameter $name is used for exceptions. See exceptions for more info.

isNotEqualTo($value, $expected, $name = null)

Checks if given $value is NOT equal to $expected. Throws exception if fails.

This method is type safe, meaning that it will NOT fail when $value is integer 1 and $expected is string '1'.

Optional parameter $name is used for exceptions. See exceptions for more info.

isTypeExists($value, $name = null)

Checks if there is a class or interface named $value. Throws exception if fails.

Optional parameter $name is used for exceptions. See exceptions for more info.

isClassExists($value, $name = null)

Checks if there is a class named $value. Throws exception if fails.

Optional parameter $name is used for exceptions. See exceptions for more info.

isInterfaceExists($value, $name = null)

Checks if there is an interface named $value. Throws exception if fails.

Optional parameter $name is used for exceptions. See exceptions for more info.

isMethodExists($object_or_class_name, $method, $name = null)

Checks if there is a method called $method inside $object_or_class_name. Throws exception if fails.

Optional parameter $name is used for exceptions. See exceptions for more info.

Works with instances as well:

isInArray($value, $allowed_value_list, $type_strict = false, $name = null)

Checks if given $value is in given array $allowed_value_list. Throws exception if fails.

Optional parameter $name is used for exceptions. See exceptions for more info.

Type Checkers

isCallable($value, $name = null)

Checks if given $value is callable. Throws exception if fails.

This does not throw for closures, built-in php functions, public instance methods and public static methods. It will throw exception for protected and private instance and static methods.

Optional parameter $name is used for exceptions. See exceptions for more info.

Works with instances as well:

isString($value, $name = null)

Checks if given $value is string. Throws exception if fails.

Optional parameter $name is used for exceptions. See exceptions for more info.

isBoolean($value, $name = null)

Checks if given $value is boolean, that is true or false. Throws exception if fails.

Optional parameter $name is used for exceptions. See exceptions for more info.

isInt($value, $name = null)

Checks if given $value is int. Throws exception if fails.

This method is type safe, meaning that it will fail when $value is string '1'.

Optional parameter $name is used for exceptions. See exceptions for more info.

isStringOrInt($value, $name = null)

Checks if given $value is string or int. Throws exception if fails.

Optional parameter $name is used for exceptions. See exceptions for more info.

isIntOrFloat($value, $name = null)

Checks if given $value is int or float. Throws exception if fails.

Optional parameter $name is used for exceptions. See exceptions for more info.

isFloat($value, $name = null)

Checks if given $value is float. Throws exception if fails.

Optional parameter $name is used for exceptions. See exceptions for more info.

isValidArrayIndex($value, $name = null)

Checks if given $value can be used as array index. Throws exception if fails.

Note: Remember that in PHP, only strings and integers can be index. Floats and null are also valid indexes but they get converted to integer or string first.

Optional parameter $name is used for exceptions. See exceptions for more info.

isArray($value, $name = null)

Checks if given $value is array. Throws exception if fails.

Optional parameter $name is used for exceptions. See exceptions for more info

isNumeric($value, $name = null)

Checks if given $value is numeric value. Throws exception if fails.

Valid values are integers, floats and numeric strings.

Optional parameter $name is used for exceptions. See exceptions for more info.

isType($value, $type, $name = null)

Checks if given $value is instance of $type. Throws exception if fails.

This method works for classes and interfaces, and their children.

Note that null values always throw.Traits also fails since traits are not types.

Optional parameter $name is used for exceptions. See exceptions for more info.

isInstanceOf($value, $type, $name = null)

See isType($value, $type, [$name]).

isOneOfTypes($value, $type_list, $name = null)

Checks if given $value is instance of one of types from $type_list. Throws exception if fails.

Optional parameter $name is used for exceptions. See exceptions for more info.

isImplements($value, $interface, $name = null)

Checks if given $value implements given $interface. Throws exception if fails.

Optional parameter $name is used for exceptions. See exceptions for more info.

isChildOf($value, $parent, $name = null)

Checks if given $value is child of $parent. Throws exception if fails.

Note that $value and $parent are the same, this method still throws.

Optional parameter $name is used for exceptions. See exceptions for more info.

Works with interfaces and child interfaces too.

String operations

isNotEmptyString($value, $accept_blanks = false, $name = null)

Checks if given $value is empty string or not. Throws exception if fails.

Optional parameter $accept_blanks determines whether blank strings are allowed or not.

Optional parameter $name is used for exceptions. See exceptions for more info.

startsWith($value, $starts_with, $name = null)

Checks if given $value starts with given $starts_with. Throws exception if fails.

Note that $starts_with can be empty string, and if it is then no string value can generate an exception.

Also note that this method is case-sensitive.

Optional parameter $name is used for exceptions. See exceptions for more info.

isRegexMatches($value, $regex_pattern, $name = null)

Checks if given $value matches given $regex_pattern. Throws exception if fails.

Note that if $regex_pattern is not a valid regex pattern, again exception will be thrown.

Optional parameter $name is used for exceptions. See exceptions for more info.

isRegexPattern($value, $name = null)

Checks if given $value is a valid regex pattern. Throws exception if fails.

Optional parameter $name is used for exceptions. See exceptions for more info.

isNotNullOrWhiteSpace($value, $name = null)

See isNotEmptyString($value, [$accept_blanks], [$name]).

isInStringArray($value, $allowed_string_list, $name = null)

Checks if given $value is in $allowed_string_list. Throws exception if fails.

Optional parameter $name is used for exceptions. See exceptions for more info.

Array operations

isNotEmptyArray($value, $name = null)

Checks if given $value is not an empty array. Throws exception if fails.

Optional parameter $name is used for exceptions. See exceptions for more info.

isArrayOfType($value, $type, $name = null)

Checks if given $value is an array of given $type. Throws exception if fails.

Optional parameter $name is used for exceptions. See exceptions for more info.

isArrayOfString($value, $name = null)

Checks if given $value is an array of string. Throws exception if fails.

Optional parameter $name is used for exceptions. See exceptions for more info.

isSequentialArray($value, $accept_empty = true, $name = null)

Checks if given $value is a sequential array. Throws exception if fails.

Sequential array is an array whose keys start from 0, and increments by 1.

Optional parameter $accept_empty is used to decide whether to accept empty arrays or not.

Optional parameter $name is used for exceptions. See exceptions for more info.

Int operations

isPositiveInt($value, $name = null)

Checks if given $value is a positive integer. Throws exception if fails.

Optional parameter $name is used for exceptions. See exceptions for more info.

isNotNegativeInt($value, $name = null)

Checks if given $value is an integer, but not a negative integer. Throws exception if fails.

Note that this method will throw exception if $value is not an integer.

Optional parameter $name is used for exceptions. See exceptions for more info.

Number operations

isPositiveNumber($value, $allow_string = false, $name = null)

Checks if given $value is a positive number. Throws exception if fails.

Optional parameter $allow_string determines whether strings are treated as numbers.

Optional parameter $name is used for exceptions. See exceptions for more info.

isNotNegativeNumber($value, $allow_string = false, $name = null)

Checks if given $value is a number, but not a negative number. Throws exception if fails.

Note that this method will throw exception if $value is not a number.

Optional parameter $allow_string determines whether strings are treated as numbers.

Optional parameter $name is used for exceptions. See exceptions for more info.

Exceptions

Variable names

The optional parameter $name at the end of every method is used for better exception messages. Consider following:

Now imagine running this function with following parameters:

This code, when executed, will produce the following:

Fabstract\Component\Assert\AssertionException: Variable is expected to be int, given string (no name was provided).

However, if $name parameter is provided like this:

Then exception message will be more helpful:

Fabstract\Component\Assert\AssertionException: Variable with name "divisor" is expected to be int, given string.

Extending exceptions

Another usage of exceptions is extending them.

By default, every failed assertion will cause Assert::generateException() method to be called. Note that this method is protected, and all methods that throw exception do it like this:

This means that if a custom Assert class is created by extending Fabstract's Assert class, it is possible to make all methods throw a custom exception, by overriding generateException method alone:

Now this will produce following:

MyCustomAssertionException: Variable with name "divisor" is expected to be int, given string.

You can comfortably create classes that extend Assert for your libraries, and use try-catch blocks to find which library throws assertion exceptions by separating them by their classes.