To

Coerce loose input into clean typed values: integers, strings, floats, ids, filenames, paths, dates, times, domains and email addresses. Every function takes a value of any shape and returns a predictable, sanitised result.

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

Classes

To - static functions that coerce loose input into clean typed values.

To

Each function takes a value of any type and returns a sanitised value of a specific type. Number functions can clamp to a range, the null variants pass null through, and the name, path, date and time functions strip anything that does not fit their format.

ArrayOfID

To::ArrayOfID($array)

Convert an array into a list of ids, trimming and coercing each item; a non-array gives an empty array.

Name	Type	Description
`$array`	`mixed`	The array of values to convert to ids.

Returns array A list of id integers.

Boolean

To::Boolean($value)

Coerce a value to true or false, recognising the strings '1', 'true', '0', 'false' and blank, and treating an integer as false only when it is zero.

Name	Type	Description
`$value`	`mixed`	The value to interpret as a boolean.

Returns bool True or false.

DatabaseName

To::DatabaseName($name)

Reduce a value to a safe database name, keeping only allowed characters and stripping any leading digits.

Name	Type	Description
`$name`	`mixed`	The value to reduce to a database name.

Returns string A safe database name.

DatabaseNameOrNull

To::DatabaseNameOrNull($value)

Coerce a value to a database name, or return null when the value is null.

Name	Type	Description
`$value`	`mixed`	The value to reduce, or null.

Returns string|null A database name, or null.

Date

To::Date($str)

Return the value as a YYYY-MM-DD date string, or '0000-00-00' when it does not match that format.

Name	Type	Description
`$str`	`mixed`	The value to read as a date.

Returns string A YYYY-MM-DD date, or the zero date.

DomainName

To::DomainName($domain)

Reduce a value to a lowercase domain name, returning empty when it contains a double dot or starts or ends with a dot.

Name	Type	Description
`$domain`	`mixed`	The value to reduce to a domain name.

Returns string A lowercase domain name, or empty.

Email

To::Email($email)

Reduce a value to an email address, keeping only allowed characters; returns null when it does not have exactly one at sign.

Name	Type	Description
`$email`	`mixed`	The value to reduce to an email address.

Returns string|null An email address, or null.

Filename

To::Filename($filename, $allow_files_starting_with_dot = false)

Reduce a value to a safe filename, keeping only allowed characters; a name starting with a dot is rejected unless allowed.

Name	Type	Description
`$filename`	`mixed`	The value to reduce to a filename.
`$allow_files_starting_with_dot`	`bool`	When true, a leading dot is permitted.

Returns string A safe filename, or empty.

FilenameOrNull

To::FilenameOrNull($filename, $allow_special = false)

Coerce a value to a filename, or return null when the value is null.

Name	Type	Description
`$filename`	`mixed`	The value to reduce, or null.
`$allow_special`	`bool`	Reserved flag; default false.

Returns string|null A filename, or null.

FilePath

To::FilePath($path)

Normalise a value into a clean slash-separated file path, honouring a drive letter, resolving '..' segments and keeping a leading network prefix.

Name	Type	Description
`$path`	`mixed`	The value to normalise into a file path.

Returns string A clean file path, or empty.

Float

To::Float($float)

Coerce a value to a floating point number.

Name	Type	Description
`$float`	`mixed`	The value to convert to a float.

Returns float The floating point value.

FloatStr

To::FloatStr($float, $allow_array = false)

Format a value as a float string that always shows a decimal point; an array becomes '0.0' unless arrays are allowed, in which case each value is formatted.

Name	Type	Description
`$float`	`mixed`	The value to format as a float string.
`$allow_array`	`bool`	When true, an array is formatted item by item.

Returns string|array A float string, or an array of them.

FloatStrArr

To::FloatStrArr($floats)

Format every value in an array as a float string, preserving the keys.

Name	Type	Description
`$floats`	`mixed`	The array of values to format.

Returns array An array of float strings.

ID

To::ID($id, bool $allowZero = true)

Coerce a value to a non-negative id integer; when zero is not allowed the minimum is one.

Name	Type	Description
`$id`	`mixed`	The value to convert to an id.
`$allowZero`	`bool`	When true, zero is permitted; otherwise the minimum is one.

Returns int An id integer.

IDOrNull

To::IDOrNull($str)

Coerce a value to an id, or return null when the value is null.

Name	Type	Description
`$str`	`mixed`	The value to convert, or null.

Returns int|null An id integer, or null.

Int

To::Int($num, int|null $min = null, int|null $max = null)

Coerce a value to an integer, optionally clamped to a minimum and maximum.

Name	Type	Description
`$num`	`mixed`	The value to convert to an integer.
`$min`	`int\|null`	The lowest allowed value, or null for no minimum.
`$max`	`int\|null`	The highest allowed value, or null for no maximum.

Returns int The clamped integer.

Integer

To::Integer($num, int|null $min = null, int|null $max = null)

Coerce a value to an integer, optionally clamped to a minimum and maximum.

Name	Type	Description
`$num`	`mixed`	The value to convert to an integer.
`$min`	`int\|null`	The lowest allowed value, or null for no minimum.
`$max`	`int\|null`	The highest allowed value, or null for no maximum.

Returns int The clamped integer.

IntOrNull

To::IntOrNull($num, int|null $min = null, int|null $max = null)

Coerce a value to an integer within a range, or return null when it is null or falls outside the range.

Name	Type	Description
`$num`	`mixed`	The value to convert, or null.
`$min`	`int\|null`	The lowest allowed value, or null for no minimum.
`$max`	`int\|null`	The highest allowed value, or null for no maximum.

Returns int|null The integer, or null.

Num

To::Num($num, int|null $min = null, int|null $max = null)

Coerce a value to an integer, optionally clamped to a minimum and maximum.

Name	Type	Description
`$num`	`mixed`	The value to convert to an integer.
`$min`	`int\|null`	The lowest allowed value, or null for no minimum.
`$max`	`int\|null`	The highest allowed value, or null for no maximum.

Returns int The clamped integer.

NumOptional

To::NumOptional(string $string): int|null

Return the integer a string holds exactly, checking with standard PHP rather than a regex, or null when it holds no integer.

Name	Type	Description
`$string`	`string`	The string to read an integer from.

Returns int|null The integer, or null.

NumOrNull

To::NumOrNull($num, int|null $min = null, int|null $max = null)

Coerce a value to an integer within a range, or return null when it is null or falls outside the range.

Name	Type	Description
`$num`	`mixed`	The value to convert, or null.
`$min`	`int\|null`	The lowest allowed value, or null for no minimum.
`$max`	`int\|null`	The highest allowed value, or null for no maximum.

Returns int|null The integer, or null.

NumStr

To::NumStr($num, int|null $min = null, int|null $max = null)

Coerce a value to a clamped integer and return it as a string.

Name	Type	Description
`$num`	`mixed`	The value to convert to an integer string.
`$min`	`int\|null`	The lowest allowed value, or null for no minimum.
`$max`	`int\|null`	The highest allowed value, or null for no maximum.

Returns string The clamped integer as a string.

OneOf

To::OneOf($value, $allowed_values, $default_value = null)

Return the value when it matches one of the allowed values; otherwise the given default, or the first allowed value when no default is given.

Name	Type	Description
`$value`	`string`	The value to check against the allowed list.
`$allowed_values`	`mixed`	An array, or a comma separated string, of allowed values.
`$default_value`	`mixed`	The value returned when there is no match; null uses the first allowed value.

Returns mixed An allowed value, the default, or null.

Str

To::Str($text, $string_booleans = false)

Coerce a value to a string; an Enum yields its value, and when requested true and false become 'true' and 'false'.

Name	Type	Description
`$text`	`mixed`	The value to convert to a string.
`$string_booleans`	`bool`	When true, booleans render as the words 'true' and 'false'.

Returns string The string value.

StrFormatted

To::StrFormatted($text)

Render a value as readable text, spelling out true, false and null, and formatting an array as its keys and values.

Name	Type	Description
`$text`	`mixed`	The value to render as readable text.

Returns string A readable string.

StrOrNull

To::StrOrNull($str, $convert_blank_string_to_null = false)

Coerce a value to a string, or return null when it is null; a blank string may optionally be turned into null.

Name	Type	Description
`$str`	`mixed`	The value to convert, or null.
`$convert_blank_string_to_null`	`bool`	When true, an empty string becomes null.

Returns string|null The string, or null.

Time

To::Time($str)

Return the value as an HH:MM time string, or '00:00' when it does not match that format.

Name	Type	Description
`$str`	`mixed`	The value to read as a time.

Returns string An HH:MM time, or the zero time.

TrueFalse

To::TrueFalse($bool)

Coerce any value to a strict true or false boolean.

Name	Type	Description
`$bool`	`mixed`	The value to interpret as a boolean.

Returns bool True or false.

UrlName

To::UrlName($urlname, $lower_case = false)

Reduce a value to a URL friendly name segment, turning spaces into hyphens, keeping allowed characters and collapsing repeated hyphens and dots.

Name	Type	Description
`$urlname`	`mixed`	The value to reduce to a URL name.
`$lower_case`	`bool`	When true, the result is lowercased.

Returns string A URL friendly name.

UrlPath

To::UrlPath($path, $lower_case = false)

Reduce a value to a clean slash-separated URL path, cleaning each segment as a URL name and keeping a leading network prefix.

Name	Type	Description
`$path`	`mixed`	The value to reduce to a URL path.
`$lower_case`	`bool`	When true, each segment is lowercased.

Returns string A clean URL path.