Assert

Guard functions that verify a value has an expected type or form. Each static function takes a value and throws an exception when the check fails, so callers can state their assumptions up front and stop bad input from travelling further.

This page is a pure reference. For how the framework fits together, see the Guide.

Classes

Assert - static guard functions that check a value and throw when it fails.

Assert

The main class: static functions that each check a value against an expected type or form and throw an exception when the check fails, listed alphabetically. When the ASSERT_ENABLED constant is false the checks return without doing anything.

Constants

Constant	Value	Description
`Assert::ASSERT_ENABLED`	`true`	Whether assertions are enabled; when false each check returns without acting.

Functions

Arr ArrOrNull ArrayDataOf ArrayDataOfOrNull ArrayOf ArrayOfArray ArrayOfFloat ArrayOfID ArrayOfNum ArrayOfStr ArrayOfStrOrNum ArrayOfUniqueStr ArrayWithFields Check DatabaseName DatabaseNameOrNull Date DateOrNull DomainName DomainNameOrNull Each EmailAddress FilePath Filename FilenameOrNull Float FloatOrNull GDImage HtmlAttributeName ID IDOrNull Instance_Of InstanceOrNull Is NotNull Num NumOrNull Obj ObjOrNull OneOf OneOfNum OptionalIs PHPClassName Sha1 Str StrContaining StrEndsWith StrOrArray StrOrNull StrOrNum ThrowException TrueFalse TrueFalseOrNull Url UrlName UrlNameOrNull UrlOrNull UrlPath UrlPathOrNull

Arr

Assert::Arr(&$array, $check_function = null)

Assert that the value is an array, and optionally that every item passes the given check callback called with the key and value.

Name	Type	Description
`&$array`		The value to check is an array.
`$check_function`		An optional callback called with each key and value; each must return true.

ArrOrNull

Assert::ArrOrNull(&$array = null, $check_function = null)

Assert that the value is null or an array.

Name	Type	Description
`&$array`		The value to check is null or an array.
`$check_function`		An optional check callback.

ArrayDataOf

Assert::ArrayDataOf(ArrayData $array, $class_name)

Assert that every item in an ArrayData is an instance of the named class.

Name	Type	Description
`$array`	`ArrayData`	The ArrayData whose items are checked.
`$class_name`		The class name every item must be an instance of.

ArrayDataOfOrNull

Assert::ArrayDataOfOrNull(ArrayData $array = null, $class_name)

Assert that the ArrayData is null, or that every item is an instance of the named class.

Name	Type	Description
`$array`	`ArrayData`	The ArrayData whose items are checked, or null.
`$class_name`		The class name every item must be an instance of.

ArrayOf

Assert::ArrayOf(&$array, $class_name)

Assert that the value is an array and every item is an instance of the named class.

Name	Type	Description
`&$array`		The array whose items are checked.
`$class_name`		The class name every item must be an instance of.

ArrayOfArray

Assert::ArrayOfArray(array &$array, $count_items_in_subarrays = null)

Assert that the value is an array whose every item is itself an array, optionally each with a fixed item count.

Name	Type	Description
`&$array`	`array`	The array whose items must each be arrays.
`$count_items_in_subarrays`		An optional required item count for each sub-array.

ArrayOfFloat

Assert::ArrayOfFloat(&$array, $min = null, $max = null, $elementCount = null)

Assert that the value is an array of floats, optionally within a range and of a fixed length.

Name	Type	Description
`&$array`		The array of floats to check.
`$min`		An optional minimum each value must not be below.
`$max`		An optional maximum each value must not exceed.
`$elementCount`		An optional exact number of elements.

ArrayOfID

Assert::ArrayOfID(&$array, $allow_zero = false, $elementCount = null)

Assert that the value is an array of ids, optionally allowing zero and requiring a fixed length.

Name	Type	Description
`&$array`		The array of ids to check.
`$allow_zero`		Whether zero is a permitted id value.
`$elementCount`		An optional exact number of elements.

ArrayOfNum

Assert::ArrayOfNum(&$array, $min = null, $max = null, $allow_numerical_string = false, $elementCount = null)

Assert that the value is an array of numbers, optionally within a range, allowing numeric strings, and of a fixed length.

Name	Type	Description
`&$array`		The array of numbers to check.
`$min`		An optional minimum each value must not be below.
`$max`		An optional maximum each value must not exceed.
`$allow_numerical_string`		Whether numeric strings are accepted as numbers.
`$elementCount`		An optional exact number of elements.

ArrayOfStr

Assert::ArrayOfStr(&$array)

Assert that the value is an array and every item is a string.

Name	Type	Description
`&$array`		The array of strings to check.

ArrayOfStrOrNum

Assert::ArrayOfStrOrNum(&$array)

Assert that the value is an array and every item is a string or a number.

Name	Type	Description
`&$array`		The array of strings or numbers to check.

ArrayOfUniqueStr

Assert::ArrayOfUniqueStr(array &$array)

Assert that the value is an array of strings with no duplicate items.

Name	Type	Description
`&$array`	`array`	The array of unique strings to check.

ArrayWithFields

Assert::ArrayWithFields(array &$array, $fields, $allow_extra_fields_not_in_list = false)

Assert that the array contains each of the named comma-separated fields, optionally allowing extra fields not in the list.

Name	Type	Description
`&$array`	`array`	The array to check for the required fields.
`$fields`		A comma-separated list of field names that must be present.
`$allow_extra_fields_not_in_list`		Whether fields beyond the list are permitted.

Check

Assert::Check($bool, $failure_message = '')

Assert that a boolean flag is true, throwing with the given failure message when it is not.

Name	Type	Description
`$bool`		The boolean flag that must be true.
`$failure_message`		A message included in the thrown exception on failure.

DatabaseName

Assert::DatabaseName($name, $allow_all_numeric = false, $allow_blank = false)

Assert that the value is a valid database name of lower-case letters, digits and underscores, not starting with a digit.

Name	Type	Description
`$name`		The database name to check.
`$allow_all_numeric`		Whether an all-numeric name is permitted.
`$allow_blank`		Whether an empty name is permitted.

DatabaseNameOrNull

Assert::DatabaseNameOrNull(&$name)

Assert that the value is null or a valid database name.

Name	Type	Description
`&$name`		The database name to check, or null.

Date

Assert::Date(&$date)

Assert that the value is a date.

Name	Type	Description
`&$date`		The value to check is a date.

DateOrNull

Assert::DateOrNull(&$date)

Assert that the value is null or a date.

Name	Type	Description
`&$date`		The value to check is null or a date.

DomainName

Assert::DomainName(&$name)

Assert that the value is a valid domain name.

Name	Type	Description
`&$name`		The domain name to check.

DomainNameOrNull

Assert::DomainNameOrNull(&$domain)

Assert that the value is null or a valid domain name.

Name	Type	Description
`&$domain`		The domain name to check, or null.

Each

Assert::Each(array &$array, Closure $check_function)

Assert that the value is an array and every item passes the given check closure.

Name	Type	Description
`&$array`	`array`	The array whose items are checked.
`$check_function`	`Closure`	A closure called with each item that must return true.

EmailAddress

Assert::EmailAddress(string &$email)

Assert that the value is a valid email address.

Name	Type	Description
`&$email`	`string`	The email address to check.

FilePath

Assert::FilePath(&$name)

Assert that the value is a string that matches a normalised file path.

Name	Type	Description
`&$name`		The file path to check.

Filename

Assert::Filename(&$name, $allow_files_starting_with_dot = false)

Assert that the value is a valid filename, optionally allowing names that start with a dot.

Name	Type	Description
`&$name`		The filename to check.
`$allow_files_starting_with_dot`		Whether a leading dot is permitted.

FilenameOrNull

Assert::FilenameOrNull(&$name)

Assert that the value is null or a valid filename.

Name	Type	Description
`&$name`		The filename to check, or null.

Float

Assert::Float($float, $min = null, $max = null)

Assert that the value is a float, optionally within a minimum and maximum range.

Name	Type	Description
`$float`		The value to check is a float.
`$min`		An optional minimum the value must not be below.
`$max`		An optional maximum the value must not exceed.

FloatOrNull

Assert::FloatOrNull($float)

Assert that the value is null or a float.

Name	Type	Description
`$float`		The value to check is null or a float.

GDImage

Assert::GDImage($image)

Assert that the value is a GD image resource.

Name	Type	Description
`$image`		The value to check is a GD image resource.

HtmlAttributeName

Assert::HtmlAttributeName($name, $allow_colon = false)

Assert that the value is a valid HTML attribute name, optionally allowing a single well-formed colon.

Name	Type	Description
`$name`		The HTML attribute name to check.
`$allow_colon`		Whether a colon separating two non-empty parts is permitted.

ID

Assert::ID(&$id, $allow_zero = false)

Assert that the value is a non-negative id number, optionally allowing zero.

Name	Type	Description
`&$id`		The id to check.
`$allow_zero`		Whether zero is a permitted id value.

IDOrNull

Assert::IDOrNull(&$id, $allow_zero = false)

Assert that the value is null or a valid id.

Name	Type	Description
`&$id`		The id to check, or null.
`$allow_zero`		Whether zero is a permitted id value.

Instance_Of

Assert::Instance_Of(&$item, $class_name)

Assert that the value is an instance of the named class.

Name	Type	Description
`&$item`		The value to check.
`$class_name`		The class name the value must be an instance of.

InstanceOrNull

Assert::InstanceOrNull(&$item, $class_name)

Assert that the value is null or an instance of the named class.

Name	Type	Description
`&$item`		The value to check, or null.
`$class_name`		The class name the value must be an instance of.

Is

Assert::Is(&$item, $class_name)

Assert that the value is an instance of the named class, where the class name is a valid database name.

Name	Type	Description
`&$item`		The value to check.
`$class_name`		The class name the value must be an instance of.

NotNull

Assert::NotNull($value)

Assert that the value is not null.

Name	Type	Description
`$value`		The value that must not be null.

Num

Assert::Num($num, $min = null, $max = null, $allow_numerical_string = false)

Assert that the value is an integer, optionally within a range and optionally allowing a numeric string.

Name	Type	Description
`$num`		The value to check is an integer.
`$min`		An optional minimum the value must not be below.
`$max`		An optional maximum the value must not exceed.
`$allow_numerical_string`		Whether a numeric string is accepted and converted to an integer.

NumOrNull

Assert::NumOrNull(&$num, $min = null, $max = null)

Assert that the value is null or an integer, optionally within a range.

Name	Type	Description
`&$num`		The value to check is null or an integer.
`$min`		An optional minimum the value must not be below.
`$max`		An optional maximum the value must not exceed.

Obj

Assert::Obj(&$value)

Assert that the value is an object.

Name	Type	Description
`&$value`		The value to check is an object.

ObjOrNull

Assert::ObjOrNull(&$value)

Assert that the value is null or an object.

Name	Type	Description
`&$value`		The value to check is null or an object.

OneOf

Assert::OneOf(&$value, $allowed_values)

Assert that the string value is one of the allowed values, given as an array or a comma-separated string.

Name	Type	Description
`&$value`		The string value that must appear in the allowed list.
`$allowed_values`		An array or comma-separated string of allowed values.

OneOfNum

Assert::OneOfNum(&$value, $allowed_values)

Assert that the numeric value is one of the allowed values, given as an array or a comma-separated string.

Name	Type	Description
`&$value`		The numeric value that must appear in the allowed list.
`$allowed_values`		An array or comma-separated string of allowed values.

OptionalIs

Assert::OptionalIs(&$item, $class_name)

Assert that the value is null, or an instance of the named class.

Name	Type	Description
`&$item`		The value to check, or null.
`$class_name`		The class name the value must be an instance of.

PHPClassName

Assert::PHPClassName($name)

Assert that the value is a valid PHP class name, checked as a database name.

Name	Type	Description
`$name`		The class name to check.

Sha1

Assert::Sha1(&$str)

Assert that the value is a 40-character lower-case hexadecimal SHA1 string.

Name	Type	Description
`&$str`		The SHA1 string to check.

Str

Assert::Str(&$string, $allowed_chars = null, $allow_blank = true, $maxLength = null)

Assert that the value is a string (or an integer), optionally restricted to a set of allowed characters, optionally non-blank, and optionally within a maximum length.

Name	Type	Description
`&$string`		The value to check is a string.
`$allowed_chars`		An optional set of characters the string may contain.
`$allow_blank`		Whether an empty string is permitted.
`$maxLength`		An optional maximum length.

StrContaining

Assert::StrContaining($str, $substr)

Assert that the string contains the given substring.

Name	Type	Description
`$str`		The string to search within.
`$substr`		The substring that must be present.

StrEndsWith

Assert::StrEndsWith($str, $ends_with)

Assert that the string ends with the given suffix.

Name	Type	Description
`$str`		The string to check.
`$ends_with`		The suffix the string must end with.

StrOrArray

Assert::StrOrArray(&$value)

Assert that the value is a string or an array.

Name	Type	Description
`&$value`		The value to check is a string or an array.

StrOrNull

Assert::StrOrNull(&$string)

Assert that the value is null or a string.

Name	Type	Description
`&$string`		The value to check is null or a string.

StrOrNum

Assert::StrOrNum(&$string_or_number)

Assert that the value is a string or a number.

Name	Type	Description
`&$string_or_number`		The value to check is a string or a number.

ThrowException

Assert::ThrowException($message = 'EXCEPTION (UNSPECIFIED ERROR)')

Throw an exception with the given message.

Name	Type	Description
`$message`		The message for the thrown exception.

TrueFalse

Assert::TrueFalse(&$bool)

Assert that the value is exactly true or false.

Name	Type	Description
`&$bool`		The value to check is a boolean.

TrueFalseOrNull

Assert::TrueFalseOrNull($value)

Assert that the value is null, true or false.

Name	Type	Description
`$value`		The value to check is null or a boolean.

Url

Assert::Url(&$url)

Assert that the value is a valid URL.

Name	Type	Description
`&$url`		The URL to check.

UrlName

Assert::UrlName(&$name, $lower_case = false)

Assert that the value is a non-empty valid URL name, optionally required to be lower case.

Name	Type	Description
`&$name`		The URL name to check.
`$lower_case`		Whether the name must be lower case.

UrlNameOrNull

Assert::UrlNameOrNull(&$name, $lower_case = false)

Assert that the value is null or a valid URL name.

Name	Type	Description
`&$name`		The URL name to check, or null.
`$lower_case`		Whether the name must be lower case.

UrlOrNull

Assert::UrlOrNull(&$url)

Assert that the value is null or a valid URL.

Name	Type	Description
`&$url`		The URL to check, or null.

UrlPath

Assert::UrlPath(&$path, $lower_case = false)

Assert that the value is a valid URL path, optionally required to be lower case.

Name	Type	Description
`&$path`		The URL path to check.
`$lower_case`		Whether the path must be lower case.

UrlPathOrNull

Assert::UrlPathOrNull(&$url_path)

Assert that the value is null or a valid URL path.

Name	Type	Description
`&$url_path`		The URL path to check, or null.