param

Parameter
in package
implements IParameter, Stringable

Enable safe handling of untrusted data received as string, array, or null values.

Parameter is suitable to encapsulate a value received as a string or array (or NULL) such as query parameters from a web request or database query result. It is used to validate and safely convert inputs to a more useful type.

Table of Contents

Interfaces

IParameter
Enable safe handling of untrusted data received as string, array, or null values.
Stringable

Properties

$bAllowNull  : bool
$bFrozen  : bool
Whether this parameter is frozen (permanently immutable).
$bMutable  : bool
Whether this parameter can be modified after creation.
$bSet  : bool
Whether the value has been set.
$nuAllowArrayDepth  : int|null
$rKeys  : array<int, int|string>
Array keys for iteration support.
$xValue  : array<string|int, mixed>|string|null
The encapsulated value - can be a string, array, or null.

Methods

__construct()  : mixed
__toString()  : string
String representation of the parameter.
asArray()  : array<string|int, mixed>
Converts the parameter to an array.
asArrayOrNull()  : array<string|int, mixed>|null
Converts the parameter to an array or returns null.
asArrayOrString()  : array<string|int, mixed>|string
Returns the parameter as either an array or string.
asArrayRecursive()  : array<string|int, mixed>
Converts the parameter to an array with all nested IParameter objects unwrapped.
asArrayRecursiveOrNull()  : array<string|int, mixed>|null
Converts the parameter to a recursively unwrapped array or returns null.
asArrayRecursiveOrString()  : array<string|int, mixed>|string
Returns the parameter as either a recursively unwrapped array or string.
asBool()  : bool
Converts the parameter to a boolean value.
asBoolOrNull()  : bool|null
Converts the parameter to a boolean or returns null.
asConstant()  : string
Validates that the parameter matches a specific constant value.
asCurrency()  : int
Converts the parameter to a currency amount in cents.
asCurrencyOrEmpty()  : int|null
Converts the parameter to a currency amount or returns null for empty strings.
asCurrencyOrNull()  : int|null
Converts the parameter to a currency amount or returns null.
asDate()  : string
Converts the parameter to a date string in YYYY-MM-DD format.
asDateOrNull()  : string|null
asDateTime()  : string
Converts the parameter to a date-time string.
asDateTimeOrNull()  : string|null
asEmailAddress()  : string
Validates and returns the parameter as an email address.
asEmailAddressOrEmpty()  : string|null
asEmailAddressOrNull()  : string|null
asEmailUsername()  : string
Validates and returns the parameter as an email username (local part).
asEmailUsernameOrEmpty()  : string|null
asEmailUsernameOrNull()  : string|null
asExistingDirectory()  : string
Validates that the parameter is a path to an existing directory.
asExistingDirectoryOrEmpty()  : string|null
asExistingDirectoryOrNull()  : string|null
asExistingFilename()  : string
Validates that the parameter is a path to an existing file.
asExistingFilenameOrEmpty()  : string|null
asExistingFilenameOrNull()  : string|null
asFloat()  : float
Converts the parameter to a floating-point number.
asFloatOrEmpty()  : float|null
asFloatOrNull()  : float|null
asFloatRangeClosed()  : float
Validates that the parameter is a float within a closed range (exclusive).
asFloatRangeClosedOrEmpty()  : float|null
asFloatRangeClosedOrNull()  : float|null
asFloatRangeHalfClosed()  : float
Validates that the parameter is a float within a half-closed range [min, max).
asFloatRangeHalfClosedOrEmpty()  : float|null
asFloatRangeHalfClosedOrNull()  : float|null
asFloatRangeOpen()  : float
Validates that the parameter is a float within an open range [min, max].
asFloatRangeOpenOrEmpty()  : float|null
asFloatRangeOpenOrNull()  : float|null
asHostname()  : string
Validates and returns the parameter as a hostname.
asHostnameOrEmpty()  : string|null
asHostnameOrNull()  : string|null
asInt()  : int
Converts the parameter to an integer.
asIntOrEmpty()  : int|null
Returns the integer value or null for the empty string.
asIntOrNull()  : int|null
asIntRangeClosed()  : int
Validates that the parameter is an integer within a closed range (exclusive).
asIntRangeClosedOrEmpty()  : int|null
asIntRangeClosedOrNull()  : int|null
asIntRangeHalfClosed()  : int
Validates that the parameter is an integer within a half-closed range [min, max).
asIntRangeHalfClosedOrEmpty()  : int|null
asIntRangeHalfClosedOrNull()  : int|null
asIntRangeOpen()  : int
Validates that the parameter is an integer within an open range [min, max].
asIntRangeOpenOrEmpty()  : int|null
asIntRangeOpenOrNull()  : int|null
asIP()  : string
Validates and returns the parameter as an IP address (IPv4 or IPv6).
asIPOrEmpty()  : string|null
asIPOrNull()  : string|null
asIPv4()  : string
Validates and returns the parameter as an IPv4 address.
asIPv4OrEmpty()  : string|null
asIPv4OrNull()  : string|null
asIPv6()  : string
Validates and returns the parameter as an IPv6 address.
asIPv6OrEmpty()  : string|null
asIPv6OrNull()  : string|null
asJSON()  : string
Returns the parameter value as a JSON string.
asKeyword()  : string
Validates that the parameter matches one of the allowed keywords.
asKeywordOrEmpty()  : string|null
asKeywordOrNull()  : string|null
asMap()  : string
asMapOrEmpty()  : string|null
asMapOrNull()  : string|null
asNonexistentFilename()  : string
Validates that the parameter is a path that does not exist.
asNonexistentFilenameOrEmpty()  : string|null
asNonexistentFilenameOrNull()  : string|null
asPositiveFloat()  : float
Validates that the parameter is a positive floating-point number (> 0).
asPositiveFloatOrEmpty()  : float|null
asPositiveFloatOrNull()  : float|null
asPositiveInt()  : int
Validates that the parameter is a positive integer (> 0).
asPositiveIntOrEmpty()  : int|null
asPositiveIntOrNull()  : int|null
asRoundedFloat()  : float
Converts the parameter to a float rounded to the specified precision.
asRoundedFloatOrEmpty()  : float|null
asRoundedFloatOrNull()  : float|null
asRoundedInt()  : int
Converts the parameter to an integer after rounding to the specified precision.
asRoundedIntOrEmpty()  : int|null
asRoundedIntOrNull()  : int|null
asString()  : string
Returns the parameter value as a string.
asStringOrNull()  : string|null
asTime()  : string
Converts the parameter to a time string in HH:MM:SS format.
asTimeOrNull()  : string|null
asTimeStamp()  : int
Converts the parameter to a Unix timestamp.
asTimeStampOrNull()  : int|null
asUnsignedFloat()  : float
Validates that the parameter is a non-negative floating-point number (>= 0).
asUnsignedFloatOrEmpty()  : float|null
asUnsignedFloatOrNull()  : float|null
asUnsignedInt()  : int
Validates that the parameter is a non-negative integer (>= 0).
asUnsignedIntOrEmpty()  : int|null
asUnsignedIntOrNull()  : int|null
coerce()  : IParameter|null
current()  : Parameter
Returns the current parameter during array iteration.
getValue()  : array<string|int, mixed>|string|null
Returns the raw value stored in this parameter.
has()  : bool
Checks if the parameter array has the specified key.
indexOrDefault()  : Parameter
Returns a parameter for the given key, or a parameter with the default value.
indexOrNull()  : Parameter|null
Returns a parameter for the given key, or null if the key doesn't exist.
is()  : bool
Compares this parameter's value with another value for equality.
isArray()  : bool
Checks if this parameter contains an array value.
isBool()  : bool
Checks if this parameter can be converted to a boolean.
isEmpty()  : bool
Checks if this parameter is empty (null, empty string, or empty array).
isEmptyString()  : bool
Checks if this parameter is an empty string.
isFrozen()  : bool
Checks if this parameter is frozen (permanently immutable).
isMutable()  : bool
Checks if this parameter is currently mutable.
isNull()  : bool
Checks if this parameter contains a null value.
isSet()  : bool
Checks if this parameter has been set with a value.
isString()  : bool
Checks if this parameter contains a string value.
jsonSerialize()  : array<string|int, mixed>|string|null
Returns the value for JSON serialization.
key()  : int|string
Returns the current key during array iteration.
new()  : static
Creates a new parameter with the same configuration but different value.
next()  : void
Advances the internal pointer during array iteration.
offsetExists()  : bool
Checks whether an offset exists (ArrayAccess interface).
offsetGet()  : Parameter
Returns the value at the specified offset (ArrayAccess interface).
offsetSet()  : void
Sets the value at the specified offset (ArrayAccess interface).
offsetUnset()  : void
Unsets the value at the specified offset (ArrayAccess interface).
rewind()  : void
Resets the internal pointer to the beginning during array iteration.
valid()  : bool
Checks if the current position is valid during array iteration.
_freeze()  : void
Freezes this parameter, making it permanently immutable.
_mutate()  : void
Changes the mutability state of this parameter.
_set()  : void
Sets the value of this parameter.
checkArray()  : void
Validates that this parameter contains an array value.
child()  : Parameter
Creates a child parameter with inherited configuration.
unwrap()  : array<string|int, mixed>
Recursively unwraps nested IParameter objects into plain arrays.

Properties

$bAllowNull read-only

private bool $bAllowNull = true

$bFrozen

Whether this parameter is frozen (permanently immutable).

private bool $bFrozen = false

$bMutable

Whether this parameter can be modified after creation.

private bool $bMutable = false

$bSet

Whether the value has been set.

private bool $bSet = false

$nuAllowArrayDepth read-only

private int|null $nuAllowArrayDepth = null

$rKeys

Array keys for iteration support.

private array<int, int|string> $rKeys = []

$xValue

The encapsulated value - can be a string, array, or null.

private array<string|int, mixed>|string|null $xValue

Methods

__construct()

public __construct(array<string|int, mixed>|string|IParameter|null $xValue[, bool $bAllowNull = true ][, int|null $nuAllowArrayDepth = null ]) : mixed
Parameters
$xValue : array<string|int, mixed>|string|IParameter|null

The value to encapsulate.

$bAllowNull : bool = true

If true, null is allowed as a value. If false, an exception is thrown when null is encountered.

$nuAllowArrayDepth : int|null = null

If not null, the maximum levels of array nesting that are allowed. 0 means arrays are not allowed, 1 means flat arrays are allowed, 2 means arrays of arrays are allowed, etc.

__toString()

String representation of the parameter.

public __toString() : string
Tags
throws
TypeError

If the parameter is not a string

Return values
string —

The parameter value as a string

asArray()

Converts the parameter to an array.

public asArray([string|null $i_nstError = null ]) : array<string|int, mixed>
Parameters
$i_nstError : string|null = null

Optional custom error message

Tags
throws
TypeError

If the parameter is not an array

Return values
array<string|int, mixed> —

The parameter value as an array

asArrayOrNull()

Converts the parameter to an array or returns null.

public asArrayOrNull() : array<string|int, mixed>|null
Tags
throws
TypeError

If the parameter is neither an array nor null

Return values
array<string|int, mixed>|null —

The parameter value as an array, or null if the parameter is null

asArrayOrString()

Returns the parameter as either an array or string.

public asArrayOrString() : array<string|int, mixed>|string
Tags
throws
TypeError

If the parameter is neither an array nor convertible to string

Return values
array<string|int, mixed>|string —

The parameter value as an array if it's an array, otherwise as a string

asArrayRecursive()

Converts the parameter to an array with all nested IParameter objects unwrapped.

public asArrayRecursive([string|null $i_nstError = null ]) : array<string|int, mixed>
Parameters
$i_nstError : string|null = null

Optional custom error message

Tags
throws
TypeError

If the parameter is not an array

Return values
array<string|int, mixed> —

The parameter value as an array with all IParameter objects converted to their values

asArrayRecursiveOrNull()

Converts the parameter to a recursively unwrapped array or returns null.

public asArrayRecursiveOrNull() : array<string|int, mixed>|null
Tags
throws
TypeError

If the parameter is neither an array nor null

Return values
array<string|int, mixed>|null —

The recursively unwrapped array, or null if the parameter is null

asArrayRecursiveOrString()

Returns the parameter as either a recursively unwrapped array or string.

public asArrayRecursiveOrString() : array<string|int, mixed>|string
Tags
throws
TypeError

If the parameter is neither an array nor convertible to string

Return values
array<string|int, mixed>|string —

The recursively unwrapped array if it's an array, otherwise as a string

asBool()

Converts the parameter to a boolean value.

public asBool() : bool

Note: This method treats null as false. If you need to distinguish between null and false, use asBoolOrNull() instead.

Tags
throws
ParseException

If the parameter cannot be parsed as a boolean

Return values
bool —

The parameter value as a boolean

asBoolOrNull()

Converts the parameter to a boolean or returns null.

public asBoolOrNull() : bool|null

Unlike the other asTypeOrNull() methods, asBoolOrNull() really only changes how a null value is handled; asBoolOrNull() returns null, whereas asBool() coerces null to false. So asBoolOrNull() is more of a tri-bool.

Tags
throws
ParseException

If the parameter cannot be parsed as a boolean

Return values
bool|null —

The parameter value as a boolean, or null if the parameter is null

asConstant()

Validates that the parameter matches a specific constant value.

public asConstant(string $i_stConstant) : string
Parameters
$i_stConstant : string

The expected constant value

Tags
throws
ParseException

If the parameter does not match the constant value

Return values
string —

The parameter value (which matches the constant)

asCurrency()

Converts the parameter to a currency amount in cents.

public asCurrency() : int
Tags
throws
ParseException

If the parameter cannot be parsed as a currency amount

Return values
int —

The currency amount in cents (e.g., $1.23 becomes 123)

asCurrencyOrEmpty()

Converts the parameter to a currency amount or returns null for empty strings.

public asCurrencyOrEmpty() : int|null
Tags
throws
ParseException

If the parameter is not a valid currency amount or empty

Return values
int|null —

The currency amount in cents, or null if the parameter is an empty string

asCurrencyOrNull()

Converts the parameter to a currency amount or returns null.

public asCurrencyOrNull() : int|null
Tags
throws
ParseException

If the parameter is not a valid currency amount or null

Return values
int|null —

The currency amount in cents, or null if the parameter is null

asDate()

Converts the parameter to a date string in YYYY-MM-DD format.

public asDate() : string
Tags
throws
ParseException

If the parameter cannot be parsed as a valid date

Return values
string —

The date in YYYY-MM-DD format

asDateOrNull()

public asDateOrNull() : string|null
Return values
string|null

asDateTime()

Converts the parameter to a date-time string.

public asDateTime() : string
Tags
throws
ParseException

If the parameter cannot be parsed as a valid date-time

Return values
string —

The date and time in a standard format

asDateTimeOrNull()

public asDateTimeOrNull() : string|null
Return values
string|null

asEmailAddress()

Validates and returns the parameter as an email address.

public asEmailAddress() : string
Tags
throws
ParseException

If the parameter is not a valid email address

Return values
string —

The validated email address

asEmailAddressOrEmpty()

public asEmailAddressOrEmpty() : string|null
Return values
string|null

asEmailAddressOrNull()

public asEmailAddressOrNull() : string|null
Return values
string|null

asEmailUsername()

Validates and returns the parameter as an email username (local part).

public asEmailUsername() : string
Tags
throws
ParseException

If the parameter is not a valid email username

Return values
string —

The validated email username (part before @)

asEmailUsernameOrEmpty()

public asEmailUsernameOrEmpty() : string|null
Return values
string|null

asEmailUsernameOrNull()

public asEmailUsernameOrNull() : string|null
Return values
string|null

asExistingDirectory()

Validates that the parameter is a path to an existing directory.

public asExistingDirectory() : string
Tags
throws
ParseException

If the parameter is not a path to an existing directory

Return values
string —

The validated directory path

asExistingDirectoryOrEmpty()

public asExistingDirectoryOrEmpty() : string|null
Return values
string|null

asExistingDirectoryOrNull()

public asExistingDirectoryOrNull() : string|null
Return values
string|null

asExistingFilename()

Validates that the parameter is a path to an existing file.

public asExistingFilename() : string
Tags
throws
ParseException

If the parameter is not a path to an existing file

Return values
string —

The validated file path

asExistingFilenameOrEmpty()

public asExistingFilenameOrEmpty() : string|null
Return values
string|null

asExistingFilenameOrNull()

public asExistingFilenameOrNull() : string|null
Return values
string|null

asFloat()

Converts the parameter to a floating-point number.

public asFloat() : float
Tags
throws
ParseException

If the parameter cannot be parsed as a number

Return values
float —

The parameter value as a float

asFloatOrEmpty()

public asFloatOrEmpty() : float|null
Return values
float|null

asFloatOrNull()

public asFloatOrNull() : float|null
Return values
float|null

asFloatRangeClosed()

Validates that the parameter is a float within a closed range (exclusive).

public asFloatRangeClosed(float $i_fMin, float $i_fMax) : float
Parameters
$i_fMin : float

The minimum allowed value (exclusive)

$i_fMax : float

The maximum allowed value (exclusive)

Tags
throws
ParseException

If the parameter is not a number within the specified range

Return values
float —

The parameter value as a float

asFloatRangeClosedOrEmpty()

public asFloatRangeClosedOrEmpty(float $i_fMin, float $i_fMax) : float|null
Parameters
$i_fMin : float
$i_fMax : float
Return values
float|null

asFloatRangeClosedOrNull()

public asFloatRangeClosedOrNull(float $i_fMin, float $i_fMax) : float|null
Parameters
$i_fMin : float
$i_fMax : float
Return values
float|null

asFloatRangeHalfClosed()

Validates that the parameter is a float within a half-closed range [min, max).

public asFloatRangeHalfClosed(float $i_fMin, float $i_fMax) : float
Parameters
$i_fMin : float

The minimum allowed value (inclusive)

$i_fMax : float

The maximum allowed value (exclusive)

Tags
throws
ParseException

If the parameter is not a number within the specified range

Return values
float —

The parameter value as a float

asFloatRangeHalfClosedOrEmpty()

public asFloatRangeHalfClosedOrEmpty(float $i_fMin, float $i_fMax) : float|null
Parameters
$i_fMin : float
$i_fMax : float
Return values
float|null

asFloatRangeHalfClosedOrNull()

public asFloatRangeHalfClosedOrNull(float $i_fMin, float $i_fMax) : float|null
Parameters
$i_fMin : float
$i_fMax : float
Return values
float|null

asFloatRangeOpen()

Validates that the parameter is a float within an open range [min, max].

public asFloatRangeOpen(float $i_fMin, float $i_fMax) : float
Parameters
$i_fMin : float

The minimum allowed value (inclusive)

$i_fMax : float

The maximum allowed value (inclusive)

Tags
throws
ParseException

If the parameter is not a number within the specified range

Return values
float —

The parameter value as a float

asFloatRangeOpenOrEmpty()

public asFloatRangeOpenOrEmpty(float $i_fMin, float $i_fMax) : float|null
Parameters
$i_fMin : float
$i_fMax : float
Return values
float|null

asFloatRangeOpenOrNull()

public asFloatRangeOpenOrNull(float $i_fMin, float $i_fMax) : float|null
Parameters
$i_fMin : float
$i_fMax : float
Return values
float|null

asHostname()

Validates and returns the parameter as a hostname.

public asHostname() : string
Tags
throws
ParseException

If the parameter is not a valid hostname

Return values
string —

The validated hostname

asHostnameOrEmpty()

public asHostnameOrEmpty() : string|null
Return values
string|null

asHostnameOrNull()

public asHostnameOrNull() : string|null
Return values
string|null

asInt()

Converts the parameter to an integer.

public asInt() : int
Tags
throws
ParseException

If the parameter cannot be parsed as an integer

Return values
int —

The parameter value as an integer

asIntOrEmpty()

Returns the integer value or null for the empty string.

public asIntOrEmpty() : int|null
Return values
int|null

asIntOrNull()

public asIntOrNull() : int|null
Return values
int|null

asIntRangeClosed()

Validates that the parameter is an integer within a closed range (exclusive).

public asIntRangeClosed(int $i_iMin, int $i_iMax) : int
Parameters
$i_iMin : int

The minimum allowed value (exclusive)

$i_iMax : int

The maximum allowed value (exclusive)

Tags
throws
ParseException

If the parameter is not an integer within the specified range

Return values
int —

The parameter value as an integer

asIntRangeClosedOrEmpty()

public asIntRangeClosedOrEmpty(int $i_iMin, int $i_iMax) : int|null
Parameters
$i_iMin : int
$i_iMax : int
Return values
int|null

asIntRangeClosedOrNull()

public asIntRangeClosedOrNull(int $i_iMin, int $i_iMax) : int|null
Parameters
$i_iMin : int
$i_iMax : int
Return values
int|null

asIntRangeHalfClosed()

Validates that the parameter is an integer within a half-closed range [min, max).

public asIntRangeHalfClosed(int $i_iMin, int $i_iMax) : int
Parameters
$i_iMin : int

The minimum allowed value (inclusive)

$i_iMax : int

The maximum allowed value (exclusive)

Tags
throws
ParseException

If the parameter is not an integer within the specified range

Return values
int —

The parameter value as an integer

asIntRangeHalfClosedOrEmpty()

public asIntRangeHalfClosedOrEmpty(int $i_iMin, int $i_iMax) : int|null
Parameters
$i_iMin : int
$i_iMax : int
Return values
int|null

asIntRangeHalfClosedOrNull()

public asIntRangeHalfClosedOrNull(int $i_iMin, int $i_iMax) : int|null
Parameters
$i_iMin : int
$i_iMax : int
Return values
int|null

asIntRangeOpen()

Validates that the parameter is an integer within an open range [min, max].

public asIntRangeOpen(int $i_iMin, int $i_iMax) : int
Parameters
$i_iMin : int

The minimum allowed value (inclusive)

$i_iMax : int

The maximum allowed value (inclusive)

Tags
throws
ParseException

If the parameter is not an integer within the specified range

Return values
int —

The parameter value as an integer

asIntRangeOpenOrEmpty()

public asIntRangeOpenOrEmpty(int $i_iMin, int $i_iMax) : int|null
Parameters
$i_iMin : int
$i_iMax : int
Return values
int|null

asIntRangeOpenOrNull()

public asIntRangeOpenOrNull(int $i_iMin, int $i_iMax) : int|null
Parameters
$i_iMin : int
$i_iMax : int
Return values
int|null

asIP()

Validates and returns the parameter as an IP address (IPv4 or IPv6).

public asIP() : string
Tags
throws
ParseException

If the parameter is not a valid IP address

Return values
string —

The validated IP address

asIPOrEmpty()

public asIPOrEmpty() : string|null
Return values
string|null

asIPOrNull()

public asIPOrNull() : string|null
Return values
string|null

asIPv4()

Validates and returns the parameter as an IPv4 address.

public asIPv4() : string
Tags
throws
ParseException

If the parameter is not a valid IPv4 address

Return values
string —

The validated IPv4 address

asIPv4OrEmpty()

public asIPv4OrEmpty() : string|null
Return values
string|null

asIPv4OrNull()

public asIPv4OrNull() : string|null
Return values
string|null

asIPv6()

Validates and returns the parameter as an IPv6 address.

public asIPv6() : string
Tags
throws
ParseException

If the parameter is not a valid IPv6 address

Return values
string —

The validated IPv6 address

asIPv6OrEmpty()

public asIPv6OrEmpty() : string|null
Return values
string|null

asIPv6OrNull()

public asIPv6OrNull() : string|null
Return values
string|null

asJSON()

Returns the parameter value as a JSON string.

public asJSON() : string

This is primarily intended for debugging purposes.

Tags
throws
JsonException

If the value cannot be encoded as JSON

Return values
string —

The parameter value encoded as JSON

asKeyword()

Validates that the parameter matches one of the allowed keywords.

public asKeyword(array<int, string> $i_rKeywords) : string
Parameters
$i_rKeywords : array<int, string>

List of allowable keywords

Tags
throws
ParseException

If the parameter does not match any of the allowed keywords

Return values
string —

The parameter value (which matches one of the keywords)

asKeywordOrEmpty()

public asKeywordOrEmpty(array<int, string> $i_rKeywords) : string|null
Parameters
$i_rKeywords : array<int, string>

List of allowable keywords.

Return values
string|null

asKeywordOrNull()

public asKeywordOrNull(array<int, string> $i_rKeywords) : string|null
Parameters
$i_rKeywords : array<int, string>

List of allowable keywords.

Return values
string|null

asMap()

public asMap(array<string, mixed> $i_rMap) : string
Parameters
$i_rMap : array<string, mixed>
Return values
string —

The mapped value for the key specified by this parameter.

asMapOrEmpty()

public asMapOrEmpty(array<string, mixed> $i_rMap) : string|null
Parameters
$i_rMap : array<string, mixed>
Return values
string|null —

The mapped value for the key specified by this parameter, or null if the parameter is the empty string.

asMapOrNull()

public asMapOrNull(array<string, mixed> $i_rMap) : string|null
Parameters
$i_rMap : array<string, mixed>
Return values
string|null —

The mapped value for the key specified by this parameter, or null.

asNonexistentFilename()

Validates that the parameter is a path that does not exist.

public asNonexistentFilename() : string
Tags
throws
ParseException

If the parameter is a path to an existing file or directory

Return values
string —

The validated path

asNonexistentFilenameOrEmpty()

public asNonexistentFilenameOrEmpty() : string|null
Return values
string|null

asNonexistentFilenameOrNull()

public asNonexistentFilenameOrNull() : string|null
Return values
string|null

asPositiveFloat()

Validates that the parameter is a positive floating-point number (> 0).

public asPositiveFloat() : float
Tags
throws
ParseException

If the parameter is not a positive number

Return values
float —

The parameter value as a positive float

asPositiveFloatOrEmpty()

public asPositiveFloatOrEmpty() : float|null
Return values
float|null

asPositiveFloatOrNull()

public asPositiveFloatOrNull() : float|null
Return values
float|null

asPositiveInt()

Validates that the parameter is a positive integer (> 0).

public asPositiveInt() : int
Tags
throws
ParseException

If the parameter is not a positive integer

Return values
int —

The parameter value as a positive integer

asPositiveIntOrEmpty()

public asPositiveIntOrEmpty() : int|null
Return values
int|null

asPositiveIntOrNull()

public asPositiveIntOrNull() : int|null
Return values
int|null

asRoundedFloat()

Converts the parameter to a float rounded to the specified precision.

public asRoundedFloat([int $i_iPrecision = 0 ]) : float
Parameters
$i_iPrecision : int = 0

Number of decimal places to round to (default: 0)

Tags
throws
ParseException

If the parameter cannot be parsed as a number

Return values
float —

The rounded float value

asRoundedFloatOrEmpty()

public asRoundedFloatOrEmpty([int $i_iPrecision = 0 ]) : float|null
Parameters
$i_iPrecision : int = 0
Return values
float|null

asRoundedFloatOrNull()

public asRoundedFloatOrNull([int $i_iPrecision = 0 ]) : float|null
Parameters
$i_iPrecision : int = 0
Return values
float|null

asRoundedInt()

Converts the parameter to an integer after rounding to the specified precision.

public asRoundedInt([int $i_iPrecision = 0 ]) : int
Parameters
$i_iPrecision : int = 0

Number of decimal places before rounding (default: 0)

Tags
throws
ParseException

If the parameter cannot be parsed as a number

Return values
int —

The rounded integer value

asRoundedIntOrEmpty()

public asRoundedIntOrEmpty([int $i_iPrecision = 0 ]) : int|null
Parameters
$i_iPrecision : int = 0
Return values
int|null

asRoundedIntOrNull()

public asRoundedIntOrNull([int $i_iPrecision = 0 ]) : int|null
Parameters
$i_iPrecision : int = 0
Return values
int|null

asString()

Returns the parameter value as a string.

public asString() : string
Tags
throws
TypeError

If the parameter is not a string (e.g., if it's an array)

Return values
string —

The parameter value as a string

asStringOrNull()

public asStringOrNull() : string|null
Return values
string|null

asTime()

Converts the parameter to a time string in HH:MM:SS format.

public asTime() : string
Tags
throws
ParseException

If the parameter cannot be parsed as a valid time

Return values
string —

The time in HH:MM:SS format

asTimeOrNull()

public asTimeOrNull() : string|null
Return values
string|null

asTimeStamp()

Converts the parameter to a Unix timestamp.

public asTimeStamp() : int
Tags
throws
ParseException

If the parameter cannot be parsed as a valid timestamp

Return values
int —

The Unix timestamp

asTimeStampOrNull()

public asTimeStampOrNull() : int|null
Return values
int|null

asUnsignedFloat()

Validates that the parameter is a non-negative floating-point number (>= 0).

public asUnsignedFloat() : float
Tags
throws
ParseException

If the parameter is not a non-negative number

Return values
float —

The parameter value as a non-negative float

asUnsignedFloatOrEmpty()

public asUnsignedFloatOrEmpty() : float|null
Return values
float|null

asUnsignedFloatOrNull()

public asUnsignedFloatOrNull() : float|null
Return values
float|null

asUnsignedInt()

Validates that the parameter is a non-negative integer (>= 0).

public asUnsignedInt() : int
Tags
throws
ParseException

If the parameter is not a non-negative integer

Return values
int —

The parameter value as a non-negative integer

asUnsignedIntOrEmpty()

public asUnsignedIntOrEmpty() : int|null
Return values
int|null

asUnsignedIntOrNull()

public asUnsignedIntOrNull() : int|null
Return values
int|null

coerce()

public static coerce(mixed $i_xValue) : IParameter|null
Parameters
$i_xValue : mixed
Return values
IParameter|null —

Makes sure a value is a Parameter or null. Useful for handling arbitrary default values while passing through Parameter values unmodified.

current()

Returns the current parameter during array iteration.

public current() : Parameter
Tags
throws
TypeError

If this parameter is not an array

Return values
Parameter —

The current parameter

getValue()

Returns the raw value stored in this parameter.

public getValue() : array<string|int, mixed>|string|null
Return values
array<string|int, mixed>|string|null —

The raw parameter value

has()

Checks if the parameter array has the specified key.

public has(int|string $key) : bool
Parameters
$key : int|string

The key to check for

Tags
throws
TypeError

If this parameter is not an array

Return values
bool —

True if the key exists, false otherwise

indexOrDefault()

Returns a parameter for the given key, or a parameter with the default value.

public indexOrDefault(int|string $key, array<string|int, mixed>|string|null $default) : Parameter
Parameters
$key : int|string

The array key to access

$default : array<string|int, mixed>|string|null

The default value if the key doesn't exist

Tags
throws
TypeError

If this parameter is not an array

Return values
Parameter —

A Parameter containing either the key's value or the default

indexOrNull()

Returns a parameter for the given key, or null if the key doesn't exist.

public indexOrNull(int|string $key) : Parameter|null
Parameters
$key : int|string

The array key to access

Tags
throws
TypeError

If this parameter is not an array

Return values
Parameter|null —

A Parameter for the key's value, or null if the key doesn't exist

is()

Compares this parameter's value with another value for equality.

public is(array<string|int, mixed>|int|string|float|bool|IParameter|null $i_xValue) : bool

This method handles type-aware comparisons including boolean validation, recursive array comparison, and proper null handling.

Parameters
$i_xValue : array<string|int, mixed>|int|string|float|bool|IParameter|null

The value to compare against

Return values
bool —

True if the values are equal, false otherwise

isArray()

Checks if this parameter contains an array value.

public isArray() : bool
Return values
bool —

True if the parameter is an array, false otherwise

isBool()

Checks if this parameter can be converted to a boolean.

public isBool() : bool
Return values
bool —

True if the parameter can be parsed as a boolean, false otherwise

isEmpty()

Checks if this parameter is empty (null, empty string, or empty array).

public isEmpty() : bool
Return values
bool —

True if the parameter is empty, false otherwise

isEmptyString()

Checks if this parameter is an empty string.

public isEmptyString() : bool
Return values
bool —

True if the parameter is an empty string, false otherwise

isFrozen()

Checks if this parameter is frozen (permanently immutable).

public isFrozen() : bool
Return values
bool —

True if the parameter is frozen, false otherwise

isMutable()

Checks if this parameter is currently mutable.

public isMutable() : bool
Return values
bool —

True if the parameter can be modified, false otherwise

isNull()

Checks if this parameter contains a null value.

public isNull() : bool
Return values
bool —

True if the parameter is null, false otherwise

isSet()

Checks if this parameter has been set with a value.

public isSet() : bool
Return values
bool —

Always returns true for immutable parameters

isString()

Checks if this parameter contains a string value.

public isString() : bool
Return values
bool —

True if the parameter is a string, false otherwise

jsonSerialize()

Returns the value for JSON serialization.

public jsonSerialize() : array<string|int, mixed>|string|null
Return values
array<string|int, mixed>|string|null —

The value suitable for JSON encoding

key()

Returns the current key during array iteration.

public key() : int|string
Tags
throws
TypeError

If this parameter is not an array

Return values
int|string —

The current array key

new()

Creates a new parameter with the same configuration but different value.

public new(array<string|int, mixed>|bool|float|int|string|IParameter|null $xValue) : static
Parameters
$xValue : array<string|int, mixed>|bool|float|int|string|IParameter|null

The value for the new parameter

Return values
static —

A new parameter instance with the same configuration

next()

Advances the internal pointer during array iteration.

public next() : void
Tags
throws
TypeError

If this parameter is not an array

offsetExists()

Checks whether an offset exists (ArrayAccess interface).

public offsetExists(mixed $offset) : bool
Parameters
$offset : mixed

The offset to check (must be int or string)

Tags
suppress

PhanTypeMismatchDeclaredParamNullable

throws
InvalidArgumentException

If the offset is not an integer or string

throws
TypeError

If this parameter is not an array

Return values
bool —

True if the offset exists, false otherwise

offsetGet()

Returns the value at the specified offset (ArrayAccess interface).

public offsetGet(mixed $offset) : Parameter
Parameters
$offset : mixed

The offset to retrieve (must be int or string)

Tags
suppress

PhanTypeMismatchDeclaredParamNullable

throws
InvalidArgumentException

If the offset is not an integer or string

throws
OutOfBoundsException

If the offset does not exist

throws
TypeError

If this parameter is not an array

Return values
Parameter —

The parameter at the specified offset

offsetSet()

Sets the value at the specified offset (ArrayAccess interface).

public offsetSet(mixed $offset, mixed $value) : void

Always throws LogicException since Parameters are immutable.

Parameters
$offset : mixed

The offset to set (must be int or string)

$value : mixed

The value to set

Tags
suppress

PhanTypeMismatchDeclaredParamNullable

throws
LogicException

Always thrown since Parameter is immutable

offsetUnset()

Unsets the value at the specified offset (ArrayAccess interface).

public offsetUnset(mixed $offset) : void

Always throws LogicException since Parameters are immutable.

Parameters
$offset : mixed

The offset to unset (must be int or string)

Tags
suppress

PhanTypeMismatchDeclaredParamNullable

throws
LogicException

Always thrown since Parameter is immutable

rewind()

Resets the internal pointer to the beginning during array iteration.

public rewind() : void
Tags
throws
TypeError

If this parameter is not an array

valid()

Checks if the current position is valid during array iteration.

public valid() : bool
Tags
throws
TypeError

If this parameter is not an array

Return values
bool —

True if the current position is valid, false otherwise

_freeze()

Freezes this parameter, making it permanently immutable.

protected _freeze() : void

_mutate()

Changes the mutability state of this parameter.

protected _mutate(bool $i_bMutable) : void
Parameters
$i_bMutable : bool

Whether the parameter should be mutable

Tags
throws
LogicException

If trying to make a frozen parameter mutable

_set()

Sets the value of this parameter.

protected _set(array<string|int, mixed>|bool|float|int|string|IParameter|null $i_xValue) : void
Parameters
$i_xValue : array<string|int, mixed>|bool|float|int|string|IParameter|null

The value to set

Tags
throws
LogicException

If the parameter is immutable and already set

throws
InvalidArgumentException

If null is provided but not allowed, or array depth exceeds limits

checkArray()

Validates that this parameter contains an array value.

private checkArray() : void
Tags
throws
TypeError

If this parameter is not an array

child()

Creates a child parameter with inherited configuration.

private child(array<string|int, mixed>|bool|float|int|string|IParameter|null $i_xValue) : Parameter
Parameters
$i_xValue : array<string|int, mixed>|bool|float|int|string|IParameter|null

The value for the child parameter

Return values
Parameter —

A new Parameter instance with inherited configuration

unwrap()

Recursively unwraps nested IParameter objects into plain arrays.

private static unwrap(array<string|int, mixed>|IParameter $i_xValue) : array<string|int, mixed>
Parameters
$i_xValue : array<string|int, mixed>|IParameter

The value to unwrap

Return values
array<string|int, mixed> —

The unwrapped array with all IParameter objects converted to their values


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results