Security
Reference for the Security module: type and value checks used in place of plain assertions when the check must stay active even when running online in release mode. Each check validates its input, throws on failure, and returns the value on success so it can be used inline. Every function is listed with its signature, parameters and return type.
This page is a pure reference. For how the framework fits together, see the Guide.
Security- type and value checks that throw on failure and return the value on success.
Security
Static check functions covering strings, numbers, arrays, ids, urls, filenames, hex hashes, class instances and more. A check validates its argument, calls Fail (which throws) when the argument is not valid, and returns the validated value otherwise.
Constants
| Constant | Value | Description |
|---|---|---|
Security::ASSERT_ENABLED | true | Flag controlling whether assertions are enabled. |
Any
Security::Any($value): mixed
Accept any value and return it unchanged.
| Name | Type | Description |
|---|---|---|
$value | mixed | The value to pass through. |
Returns mixed The value unchanged.
Arr
Security::Arr(&$array, callable $check_function = null)
Check the value is an array; with a check function, apply it to each item of a zero-indexed list and return the results.
| Name | Type | Description |
|---|---|---|
$array | mixed | The value that must be an array. |
$check_function | callable | Optional function applied to each item; keys must be sequential from zero. |
Returns The array, or the array of checked items when a check function is given.
ArrOrNull
Security::ArrOrNull(&$array = null, callable $check_function = null)
Check the value is an array, or leave it when it is null.
| Name | Type | Description |
|---|---|---|
$array | mixed | The array to check, or null. |
$check_function | callable | Optional function applied to each item. |
Returns The array, or null.
ArrayDataOf
Security::ArrayDataOf(ArrayData $array, $class_name)
Check every item of an ArrayData is an instance of the named class.
| Name | Type | Description |
|---|---|---|
$array | ArrayData | The collection to check. |
$class_name | string | The class every item must be an instance of. |
Returns The ArrayData.
ArrayDataOfOrNull
Security::ArrayDataOfOrNull(ArrayData $array = null, $class_name)
Check every item of an ArrayData is an instance of the named class, or leave it when it is null.
| Name | Type | Description |
|---|---|---|
$array | ArrayData | The collection to check, or null. |
$class_name | string | The class every item must be an instance of. |
Returns The ArrayData, or null.
ArrayOf
Security::ArrayOf($class_name)
Return a check function that checks a value is an array whose every item is an instance of the named class.
| Name | Type | Description |
|---|---|---|
$class_name | string | The class every item must be an instance of. |
Returns A closure that checks and returns the array.
ArrayOfArray
Security::ArrayOfArray(array &$array, $count_items_in_subarrays = null)
Check the value is an array whose every item is an array, optionally each with a fixed number of items.
| Name | Type | Description |
|---|---|---|
$array | array | The array of arrays to check. |
$count_items_in_subarrays | int | Optional required item count for each sub-array. |
Returns The array.
ArrayOfFilePath
Security::ArrayOfFilePath(&$array, $allow_files_starting_with_dot = false, $elementCount = null)
Check the value is an array of file paths, optionally of a fixed length.
| Name | Type | Description |
|---|---|---|
$array | array | The array of file paths to check. |
$allow_files_starting_with_dot | bool | Whether to allow file names beginning with a dot. |
$elementCount | int | Optional required number of elements. |
Returns The array.
ArrayOfFloat
Security::ArrayOfFloat(&$array, $min = null, $max = null, $elementCount = null)
Check the value is an array of floats, each within an optional range, optionally of a fixed length.
| Name | Type | Description |
|---|---|---|
$array | array | The array of floats to check. |
$min | float | Optional minimum for each value. |
$max | float | Optional maximum for each value. |
$elementCount | int | Optional required number of elements. |
Returns The array.
ArrayOfID
Security::ArrayOfID(&$array, $allow_zero = false, $elementCount = null)
Check the value is an array of ids, optionally of a fixed length.
| Name | Type | Description |
|---|---|---|
$array | array | The array of ids to check. |
$allow_zero | bool | Whether zero is a valid id. |
$elementCount | int | Optional required number of elements. |
Returns The array.
ArrayOfNum
Security::ArrayOfNum(&$array, $min = null, $max = null, $allow_numerical_string = false, $elementCount = null)
Check the value is an array of integers, each within an optional range, optionally of a fixed length.
| Name | Type | Description |
|---|---|---|
$array | array | The array of numbers to check. |
$min | int | Optional minimum for each value. |
$max | int | Optional maximum for each value. |
$allow_numerical_string | bool | Whether numeric strings are accepted as numbers. |
$elementCount | int | Optional required number of elements. |
Returns The array.
ArrayOfObject
Security::ArrayOfObject(array &$array)
Check the value is an array whose every item is an object.
| Name | Type | Description |
|---|---|---|
$array | array | The array of objects to check. |
Returns The array.
ArrayOfStr
Security::ArrayOfStr(&$array)
Check the value is an array whose every item is a string.
| Name | Type | Description |
|---|---|---|
$array | array | The array of strings to check. |
Returns The array.
ArrayOfStrOrNum
Security::ArrayOfStrOrNum(&$array)
Check the value is an array whose every item is a string or a number.
| Name | Type | Description |
|---|---|---|
$array | array | The array of strings or numbers to check. |
Returns The array.
ArrayOfUniqueStr
Security::ArrayOfUniqueStr(array &$array)
Check the value is an array of strings with no repeated value.
| Name | Type | Description |
|---|---|---|
$array | array | The array of strings that must all be unique. |
Returns The array.
ArrayWithFields
Security::ArrayWithFields(array &$array, $fields, $allow_extra_fields_not_in_list = false)
Check an array contains each of a comma-separated list of keys.
| Name | Type | Description |
|---|---|---|
$array | array | The array to check. |
$fields | string | A comma-separated list of required field names. |
$allow_extra_fields_not_in_list | bool | Whether extra keys beyond the list are allowed. |
Returns The array.
Callback
Security::Callback($callback)
Check the value is callable.
| Name | Type | Description |
|---|---|---|
$callback | mixed | The value that must be callable. |
Returns The callback.
CallbackOrNull
Security::CallbackOrNull($callback)
Check the value is callable, or return null when it is null.
| Name | Type | Description |
|---|---|---|
$callback | mixed | The callable to check, or null. |
Returns The callback, or null.
Check
Security::Check($condition, $failure_message = '')
Fail with the message when the boolean condition is not true.
| Name | Type | Description |
|---|---|---|
$condition | bool | The condition that must be true. |
$failure_message | string | The message used on failure; a backtrace is used when blank. |
Returns true when the condition holds.
DatabaseName
Security::DatabaseName($name, $allow_all_numeric = false, $allow_blank = false, $allow_dots = false)
Check the value is a safe database identifier, lowercased, of letters, digits and underscores.
| Name | Type | Description |
|---|---|---|
$name | string | The name to check. |
$allow_all_numeric | bool | Whether an all-numeric name is allowed. |
$allow_blank | bool | Whether an empty name is allowed. |
$allow_dots | bool | Whether dot-separated parts are allowed, each checked separately. |
Returns The lowercased name.
DatabaseNameOrNull
Security::DatabaseNameOrNull(&$name)
Check the value is a safe database identifier, or leave it when it is null.
| Name | Type | Description |
|---|---|---|
$name | string | The name to check, or null. |
Returns The name, or null.
Date
Security::Date(&$date)
Check the value is a valid date.
| Name | Type | Description |
|---|---|---|
$date | mixed | The value that must be a date. |
Returns The date.
DateOrNull
Security::DateOrNull(&$date)
Check the value is a valid date, or leave it when it is null.
| Name | Type | Description |
|---|---|---|
$date | mixed | The value that must be a date, or null. |
Returns The date, or null.
DictionaryOf
Security::DictionaryOf($value_type)
Return a check function that checks an array is a string-keyed map whose values are all a string or an instance of the named class.
| Name | Type | Description |
|---|---|---|
$value_type | string | The value type: 'string', 'str', or a class name. |
Returns A closure that checks and returns the map.
DomainName
Security::DomainName(&$name)
Check the value is a valid domain name.
| Name | Type | Description |
|---|---|---|
$name | string | The domain name to check. |
Returns The domain name.
DomainNameOrNull
Security::DomainNameOrNull(&$domain)
Check the value is a valid domain name, or leave it when it is null.
| Name | Type | Description |
|---|---|---|
$domain | string | The domain name to check, or null. |
Returns The domain name, or null.
Each
Security::Each(array &$array, Closure $check_function)
Check every item of an array passes the given check function.
| Name | Type | Description |
|---|---|---|
$array | array | The array to check. |
$check_function | Closure | A function returning true for a valid item. |
Returns The array.
EmailAddress
Security::EmailAddress(&$email)
Check the value is a valid email address.
| Name | Type | Description |
|---|---|---|
$email | string | The email address to check. |
Returns The email address.
EmailAddressOrNull
Security::EmailAddressOrNull(&$email)
Check the value is a valid email address, or leave it when it is null.
| Name | Type | Description |
|---|---|---|
$email | string | The email address to check, or null. |
Returns The email address, or null.
Equal
Security::Equal($a, $b)
Check two values are equal, comparing by JSON when they are not identical.
| Name | Type | Description |
|---|---|---|
$a | mixed | The first value. |
$b | mixed | The value it must equal. |
Returns The first value.
Fail
Security::Fail($msg)
Throw an exception with the given message.
| Name | Type | Description |
|---|---|---|
$msg | string | The failure message for the thrown exception. |
Returns Nothing; always throws.
Filename
Security::Filename(&$name, $allow_files_starting_with_dot = false)
Check the value is a safe file name.
| Name | Type | Description |
|---|---|---|
$name | string | The file name to check. |
$allow_files_starting_with_dot | bool | Whether a name beginning with a dot is allowed. |
Returns The file name.
FilenameOrNull
Security::FilenameOrNull(&$name)
Check the value is a safe file name, or leave it when it is null.
| Name | Type | Description |
|---|---|---|
$name | string | The file name to check, or null. |
Returns The file name, or null.
FilePath
Security::FilePath(&$name)
Check the value is a safe file path, normalising backslashes to forward slashes.
| Name | Type | Description |
|---|---|---|
$name | string | The file path to check. |
Returns The normalised file path.
Float
Security::Float($float, $min = null, $max = null)
Check the value is a float within an optional range.
| Name | Type | Description |
|---|---|---|
$float | float | The value that must be a float. |
$min | float | Optional minimum. |
$max | float | Optional maximum. |
Returns The float.
FloatOrNull
Security::FloatOrNull($float)
Check the value is a float, or leave it when it is null.
| Name | Type | Description |
|---|---|---|
$float | float | The value that must be a float, or null. |
Returns The float, or null.
GDImage
Security::GDImage($image)
Check the value is a GD image resource.
| Name | Type | Description |
|---|---|---|
$image | resource | The value that must be a GD image resource. |
Returns The image resource.
Hex32
Security::Hex32(&$str)
Check the value is a 32-character lowercase hexadecimal string.
| Name | Type | Description |
|---|---|---|
$str | string | The hex string to check. |
Returns The string.
Hex32OrNull
Security::Hex32OrNull(&$str)
Check the value is a 32-character hex string, or leave it when it is null.
| Name | Type | Description |
|---|---|---|
$str | string | The hex string to check, or null. |
Returns The string, or null.
Hex64
Security::Hex64(&$str)
Check the value is a 64-character lowercase hexadecimal string.
| Name | Type | Description |
|---|---|---|
$str | string | The hex string to check. |
Returns The string.
Hex64OrNull
Security::Hex64OrNull(&$str)
Check the value is a 64-character hex string, or leave it when it is null.
| Name | Type | Description |
|---|---|---|
$str | string | The hex string to check, or null. |
Returns The string, or null.
HtmlAttributeName
Security::HtmlAttributeName($name, $allow_colon = false)
Check the value is a valid HTML attribute name, optionally allowing a single colon separator.
| Name | Type | Description |
|---|---|---|
$name | string | The attribute name to check. |
$allow_colon | bool | Whether a colon-separated name is allowed. |
Returns The attribute name.
ID
Security::ID($id, $allow_zero = false)
Check the value is a non-negative integer id.
| Name | Type | Description |
|---|---|---|
$id | int | The id to check. |
$allow_zero | bool | Whether zero is a valid id. |
Returns The id.
IDOrNull
Security::IDOrNull(&$id, $allow_zero = false)
Check the value is a valid id, or leave it when it is null.
| Name | Type | Description |
|---|---|---|
$id | int | The id to check, or null. |
$allow_zero | bool | Whether zero is a valid id. |
Returns The id, or null.
InstanceOrNull
Security::InstanceOrNull(&$item, $class_name)
Check the value is an instance of the named class, or leave it when it is null.
| Name | Type | Description |
|---|---|---|
$item | object | The value to check, or null. |
$class_name | string | The class the value must be an instance of. |
Returns The item, or null.
Instance_Of
Security::Instance_Of(&$item, $class_name)
Check the value is an instance of the named class.
| Name | Type | Description |
|---|---|---|
$item | object | The value to check. |
$class_name | string | The class the value must be an instance of. |
Returns The item.
Is
Security::Is(&$item, $class_name)
Check the value is a non-null instance of the named class.
| Name | Type | Description |
|---|---|---|
$item | object | The value to check. |
$class_name | string | The class the value must be an instance of. |
Returns The item.
NotEqual
Security::NotEqual($a, $b)
Check two values are not equal, comparing by JSON.
| Name | Type | Description |
|---|---|---|
$a | mixed | The first value. |
$b | mixed | The value it must not equal. |
Returns The first value.
NotNull
Security::NotNull($value)
Check the value is not null.
| Name | Type | Description |
|---|---|---|
$value | mixed | The value that must not be null. |
Returns The value.
Null
Security::Null($a)
Check the value is null.
| Name | Type | Description |
|---|---|---|
$a | mixed | The value that must be null. |
Returns The value.
Num
Security::Num($num, $min = null, $max = null, $allow_numerical_string = false)
Check the value is an integer within an optional range, optionally accepting numeric strings.
| Name | Type | Description |
|---|---|---|
$num | int | The value that must be an integer. |
$min | int | Optional minimum. |
$max | int | Optional maximum. |
$allow_numerical_string | bool | Whether a numeric string is accepted and converted. |
Returns The integer.
NumOrNull
Security::NumOrNull(&$num, $min = null, $max = null)
Check the value is an integer within an optional range, or leave it when it is null.
| Name | Type | Description |
|---|---|---|
$num | int | The value that must be an integer, or null. |
$min | int | Optional minimum. |
$max | int | Optional maximum. |
Returns The integer, or null.
Object
Security::Object()
Return a check function that checks a value is an object.
Returns A closure that checks and returns the object.
OneOf
Security::OneOf(&$value, $allowed_values)
Check a string is one of a set of allowed values, given as an array or a comma-separated string.
| Name | Type | Description |
|---|---|---|
$value | string | The string that must be in the allowed set. |
$allowed_values | array|string | The allowed values, as an array or comma-separated string. |
Returns The value.
OneOfNum
Security::OneOfNum(&$value, $allowed_values)
Check a number is one of a set of allowed values, given as an array or a comma-separated string.
| Name | Type | Description |
|---|---|---|
$value | int | The number that must be in the allowed set. |
$allowed_values | array|string | The allowed values, as an array or comma-separated string. |
Returns The value.
PHPClassName
Security::PHPClassName($name)
Check the value is a valid PHP class name.
| Name | Type | Description |
|---|---|---|
$name | string | The class name to check. |
Returns The class name.
PhoneNumber
Security::PhoneNumber(&$phone)
Check the value is a phone number in E.164 (+xxxxx) or 00-prefixed form.
| Name | Type | Description |
|---|---|---|
$phone | string | The phone number to check. |
Returns The phone number.
PhoneNumberOrNull
Security::PhoneNumberOrNull(&$phone)
Check the value is a valid phone number, or leave it when it is null.
| Name | Type | Description |
|---|---|---|
$phone | string | The phone number to check, or null. |
Returns The phone number, or null.
Sha1
Security::Sha1(&$str)
Check the value is a 40-character lowercase hexadecimal SHA-1 string.
| Name | Type | Description |
|---|---|---|
$str | string | The hex string to check. |
Returns The string.
StdClass
Security::StdClass($value): stdClass
Check the value is a stdClass object.
| Name | Type | Description |
|---|---|---|
$value | mixed | The value that must be a stdClass. |
Returns stdClass The object.
StdClassProperty
Security::StdClassProperty($stdClass, $propertyName): mixed
Check a stdClass has the named property and return its value.
| Name | Type | Description |
|---|---|---|
$stdClass | stdClass | The object to read. |
$propertyName | string | The property that must exist. |
Returns mixed The property value.
StorageBucketName
Security::StorageBucketName($name)
Check the value is a valid storage bucket name of lowercase letters, digits, underscores and hyphens.
| Name | Type | Description |
|---|---|---|
$name | string | The bucket name to check. |
Returns The lowercased bucket name.
Str
Security::Str($string, $allowed_chars = null, $allow_blank = true, $maxLength = null): string
Check the value is a string, optionally restricted to allowed characters, a maximum length, and non-blank.
| Name | Type | Description |
|---|---|---|
$string | string | The value that must be a string; integers are accepted and cast. |
$allowed_chars | string | Optional set of characters the string may contain. |
$allow_blank | bool | Whether an empty string is allowed. |
$maxLength | int | Optional maximum length. |
Returns string The string.
StrContaining
Security::StrContaining($str, $substr)
Check a string contains the given substring.
| Name | Type | Description |
|---|---|---|
$str | string | The string to check. |
$substr | string | The substring it must contain. |
Returns The string.
StrEndsWith
Security::StrEndsWith($str, $ends_with)
Check a string ends with the given suffix.
| Name | Type | Description |
|---|---|---|
$str | string | The string to check. |
$ends_with | string | The suffix it must end with. |
Returns The string.
StrOrArray
Security::StrOrArray(&$value)
Check the value is a string or an array.
| Name | Type | Description |
|---|---|---|
$value | mixed | The value that must be a string or array. |
Returns The value.
StrOrNull
Security::StrOrNull(&$string)
Check the value is a string, or leave it when it is null.
| Name | Type | Description |
|---|---|---|
$string | string | The value that must be a string, or null. |
Returns The string, or null.
StrOrNum
Security::StrOrNum(&$string_or_number)
Check the value is a string or a number.
| Name | Type | Description |
|---|---|---|
$string_or_number | mixed | The value that must be a string or number. |
Returns The value.
TrueFalse
Security::TrueFalse(&$bool)
Check the value is a boolean true or false.
| Name | Type | Description |
|---|---|---|
$bool | bool | The value that must be true or false. |
Returns true or false.
TrueFalseOrNull
Security::TrueFalseOrNull($value)
Check the value is true, false or null.
| Name | Type | Description |
|---|---|---|
$value | bool | The value that must be true, false or null. |
Returns The value.
Url
Security::Url($url)
Check the value is a valid url.
| Name | Type | Description |
|---|---|---|
$url | string | The url to check. |
Returns The url.
UrlName
Security::UrlName(&$name, $lower_case = false)
Check the value is a non-empty url name segment, optionally lowercased.
| Name | Type | Description |
|---|---|---|
$name | string | The url name to check. |
$lower_case | bool | Whether the name must be lowercase. |
Returns The url name.
UrlNameOrNull
Security::UrlNameOrNull(&$name, $lower_case = false)
Check the value is a valid url name, or leave it when it is null.
| Name | Type | Description |
|---|---|---|
$name | string | The url name to check, or null. |
$lower_case | bool | Whether the name must be lowercase. |
Returns The url name, or null.
UrlOrNull
Security::UrlOrNull(&$url)
Check the value is a valid url, or return null when it is null.
| Name | Type | Description |
|---|---|---|
$url | string | The url to check, or null. |
Returns The url, or null.
UrlPath
Security::UrlPath(&$path, $lower_case = false)
Check the value is a safe url path, optionally with a query string, optionally lowercased.
| Name | Type | Description |
|---|---|---|
$path | string | The url path to check. |
$lower_case | bool | Whether to lowercase the path. |
Returns The url path.
UrlPathOrNull
Security::UrlPathOrNull(&$url_path)
Check the value is a safe url path, or leave it when it is null.
| Name | Type | Description |
|---|---|---|
$url_path | string | The url path to check, or null. |
Returns The url path, or null.