param

Parse
in package

Static utility class for parsing and validating string values.

The Parse class provides methods to convert string inputs to specific types with validation. Each method validates the input and throws ParseException if the string cannot be converted to the expected type. This class is used internally by Parameter classes to handle type-safe conversions.

Table of Contents

Methods

arrayMap()  : string
Maps a key to its corresponding value in an associative array.
arrayValue()  : string
Validates that a value exists in an array of allowed values.
bool()  : bool
Parses a string to a boolean value.
constant()  : string
Validates that a string matches a specific constant value.
currency()  : int
Parses a currency string to cents (integer).
date()  : string
Parses and validates a date string.
dateTime()  : string
Parses and validates a date-time string.
emailAddress()  : string
Validates an email address.
emailUsername()  : string
Validates an email username (local part before @).
existingDirectory()  : string
Validates that a path is an existing directory.
existingFilename()  : string
Validates that a path is an existing file.
float()  : float
Parses a string to a floating-point number.
floatRangeClosed()  : float
Parses a float and validates it's within a closed range (exclusive bounds).
floatRangeHalfClosed()  : float
Parses a float and validates it's within a half-closed range [min, max).
floatRangeOpen()  : float
Parses a float and validates it's within an open range [min, max].
glob()  : array<int, string>
Executes a glob pattern and returns matching filenames.
hostname()  : string
Validates a hostname.
int()  : int
Parses a string to an integer.
intRangeClosed()  : int
Parses an integer and validates it's within a closed range (exclusive bounds).
intRangeHalfClosed()  : int
Parses an integer and validates it's within a half-closed range [min, max).
intRangeOpen()  : int
Parses an integer and validates it's within an open range [min, max].
ip()  : string
Validates an IP address (IPv4 or IPv6).
ipv4()  : string
Validates an IPv4 address.
ipv6()  : string
Validates an IPv6 address.
nonexistentFilename()  : string
Validates that a filename path does not exist.
positiveFloat()  : float
Parses a string to a positive floating-point number (> 0).
positiveInt()  : int
Parses a string to a positive integer (> 0).
roundedFloat()  : float
Parses a string to a float and rounds it to the specified precision.
roundedInt()  : int
Parses a string to a float, rounds it, then converts to integer.
summarizeOptions()  : string
Creates a summary string of options for error messages.
time()  : string
Parses and validates a time string.
timeStamp()  : int
Parses a date-time string and converts it to a Unix timestamp.
unsignedFloat()  : float
Parses a string to a non-negative floating-point number (>= 0).
unsignedInt()  : int
Parses a string to a non-negative integer (>= 0).

Methods

arrayMap()

Maps a key to its corresponding value in an associative array.

public static arrayMap(string $i_stKey, array<string, string> $i_r[, string|null $i_nstError = null ]) : string
Parameters
$i_stKey : string

The key to look up

$i_r : array<string, string>

The associative array to search

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the key is not found in the array

Return values
string —

The mapped value for the given key

arrayValue()

Validates that a value exists in an array of allowed values.

public static arrayValue(string $i_stValue, array<int, string> $i_r[, string|null $i_nstError = null ]) : string
Parameters
$i_stValue : string

The value to validate

$i_r : array<int, string>

The array of allowed values

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the value is not in the allowed array

Return values
string —

The validated value

bool()

Parses a string to a boolean value.

public static bool(string $i_stBool[, string|null $i_nstError = null ]) : bool

Accepts numeric values (0 = false, non-zero = true) and text values such as 'true', 'yes', 'on', 'false', 'no', 'off' (case-insensitive).

Parameters
$i_stBool : string

The string to parse

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the string cannot be parsed as a boolean

Return values
bool —

The parsed boolean value

constant()

Validates that a string matches a specific constant value.

public static constant(string $i_stString, string $i_stConstant[, string|null $i_nstError = null ]) : string
Parameters
$i_stString : string

The string to validate

$i_stConstant : string

The expected constant value

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the string does not match the constant

Return values
string —

The validated string (same as input if valid)

currency()

Parses a currency string to cents (integer).

public static currency(string $i_stCurrency[, string|null $i_nstError = null ]) : int

Converts currency amounts like "$1.23" or "1.23" to cents (123).

Parameters
$i_stCurrency : string

The currency string to parse

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the string cannot be parsed as currency

Return values
int —

The currency amount in cents

date()

Parses and validates a date string.

public static date(string $i_stDate[, string|null $i_nstError = null ]) : string
Parameters
$i_stDate : string

The date string to parse

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the string is not a valid date

Return values
string —

The validated date string in standard format

dateTime()

Parses and validates a date-time string.

public static dateTime(string $i_stDateTime[, string|null $i_nstError = null ]) : string
Parameters
$i_stDateTime : string

The date-time string to parse

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the string is not a valid date-time

Return values
string —

The validated date-time string in standard format

emailAddress()

Validates an email address.

public static emailAddress(string $i_stEmail[, string|null $i_nstError = null ]) : string
Parameters
$i_stEmail : string

The email address to validate

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the string is not a valid email address

Return values
string —

The validated email address

emailUsername()

Validates an email username (local part before @).

public static emailUsername(string $i_stUsername[, string|null $i_nstError = null ]) : string
Parameters
$i_stUsername : string

The email username to validate

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the string is not a valid email username

Return values
string —

The validated email username

existingDirectory()

Validates that a path is an existing directory.

public static existingDirectory(string $i_stDir[, string|null $i_nstError = null ]) : string
Parameters
$i_stDir : string

The directory path to validate

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the path is not an existing directory

Return values
string —

The validated directory path

existingFilename()

Validates that a path is an existing file.

public static existingFilename(string $i_stFile[, string|null $i_nstError = null ]) : string
Parameters
$i_stFile : string

The file path to validate

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the path is not an existing file

Return values
string —

The validated file path

float()

Parses a string to a floating-point number.

public static float(string $i_stFloat[, string|null $i_nstError = null ]) : float
Parameters
$i_stFloat : string

The string to parse

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the string cannot be parsed as a float

Return values
float —

The parsed float value

floatRangeClosed()

Parses a float and validates it's within a closed range (exclusive bounds).

public static floatRangeClosed(string $i_stFloat, float $i_fMin, float $i_fMax[, string|null $i_nstError = null ]) : float
Parameters
$i_stFloat : string

The string to parse

$i_fMin : float

The minimum allowed value (exclusive)

$i_fMax : float

The maximum allowed value (exclusive)

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the string is not a valid float or is outside the range

Return values
float —

The parsed and validated float

floatRangeHalfClosed()

Parses a float and validates it's within a half-closed range [min, max).

public static floatRangeHalfClosed(string $i_stFloat, float $i_fMin, float $i_fMax[, string|null $i_nstError = null ]) : float
Parameters
$i_stFloat : string

The string to parse

$i_fMin : float

The minimum allowed value (inclusive)

$i_fMax : float

The maximum allowed value (exclusive)

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the string is not a valid float or is outside the range

Return values
float —

The parsed and validated float

floatRangeOpen()

Parses a float and validates it's within an open range [min, max].

public static floatRangeOpen(string $i_stFloat, float $i_fMin, float $i_fMax[, string|null $i_nstError = null ]) : float
Parameters
$i_stFloat : string

The string to parse

$i_fMin : float

The minimum allowed value (inclusive)

$i_fMax : float

The maximum allowed value (inclusive)

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the string is not a valid float or is outside the range

Return values
float —

The parsed and validated float

glob()

Executes a glob pattern and returns matching filenames.

public static glob(string $i_stGlob[, int $i_iFlags = 0 ][, bool $i_bAllowEmpty = false ]) : array<int, string>
Parameters
$i_stGlob : string

The glob pattern to execute

$i_iFlags : int = 0

Optional flags for the glob function

$i_bAllowEmpty : bool = false

Whether to allow empty results

Tags
throws
ParseException

If the glob pattern is invalid or no matches found (unless allowed)

Return values
array<int, string> —

A list of filenames matching the glob pattern

hostname()

Validates a hostname.

public static hostname(string $i_stHost[, string|null $i_nstError = null ]) : string
Parameters
$i_stHost : string

The hostname to validate

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the string is not a valid hostname

Return values
string —

The validated hostname

int()

Parses a string to an integer.

public static int(string $i_stInt[, string|null $i_nstError = null ]) : int
Parameters
$i_stInt : string

The string to parse

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the string cannot be parsed as an integer

Return values
int —

The parsed integer value

intRangeClosed()

Parses an integer and validates it's within a closed range (exclusive bounds).

public static intRangeClosed(string $i_stInt, int $i_iMin, int $i_iMax[, string|null $i_nstError = null ]) : int
Parameters
$i_stInt : string

The string to parse

$i_iMin : int

The minimum allowed value (exclusive)

$i_iMax : int

The maximum allowed value (exclusive)

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the string is not a valid integer or is outside the range

Return values
int —

The parsed and validated integer

intRangeHalfClosed()

Parses an integer and validates it's within a half-closed range [min, max).

public static intRangeHalfClosed(string $i_stInt, int $i_iMin, int $i_iMax[, string|null $i_nstError = null ]) : int
Parameters
$i_stInt : string

The string to parse

$i_iMin : int

The minimum allowed value (inclusive)

$i_iMax : int

The maximum allowed value (exclusive)

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the string is not a valid integer or is outside the range

Return values
int —

The parsed and validated integer

intRangeOpen()

Parses an integer and validates it's within an open range [min, max].

public static intRangeOpen(string $i_stInt, int $i_iMin, int $i_iMax[, string|null $i_nstError = null ]) : int
Parameters
$i_stInt : string

The string to parse

$i_iMin : int

The minimum allowed value (inclusive)

$i_iMax : int

The maximum allowed value (inclusive)

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the string is not a valid integer or is outside the range

Return values
int —

The parsed and validated integer

ip()

Validates an IP address (IPv4 or IPv6).

public static ip(string $i_stIP[, string|null $i_nstError = null ]) : string
Parameters
$i_stIP : string

The IP address to validate

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the string is not a valid IP address

Return values
string —

The validated IP address

ipv4()

Validates an IPv4 address.

public static ipv4(string $i_stIP[, string|null $i_nstError = null ]) : string
Parameters
$i_stIP : string

The IPv4 address to validate

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the string is not a valid IPv4 address

Return values
string —

The validated IPv4 address

ipv6()

Validates an IPv6 address.

public static ipv6(string $i_stIP[, string|null $i_nstError = null ]) : string
Parameters
$i_stIP : string

The IPv6 address to validate

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the string is not a valid IPv6 address

Return values
string —

The validated IPv6 address

nonexistentFilename()

Validates that a filename path does not exist.

public static nonexistentFilename(string $i_stFile[, string|null $i_nstError = null ]) : string
Parameters
$i_stFile : string

The file path to validate

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the file exists or the directory path is invalid

Return values
string —

The validated file path

positiveFloat()

Parses a string to a positive floating-point number (> 0).

public static positiveFloat(string $i_stFloat[, string|null $i_nstError = null ]) : float
Parameters
$i_stFloat : string

The string to parse

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the string is not a positive float

Return values
float —

The parsed positive float value

positiveInt()

Parses a string to a positive integer (> 0).

public static positiveInt(string $i_stInt[, string|null $i_nstError = null ]) : int
Parameters
$i_stInt : string

The string to parse

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the string is not a positive integer

Return values
int —

The parsed positive integer value

roundedFloat()

Parses a string to a float and rounds it to the specified precision.

public static roundedFloat(string $i_stFloat[, int $i_iPrecision = 0 ][, string|null $i_nstError = null ]) : float
Parameters
$i_stFloat : string

The string to parse

$i_iPrecision : int = 0

Number of decimal places to round to

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the string cannot be parsed as a float

Return values
float —

The parsed and rounded float value

roundedInt()

Parses a string to a float, rounds it, then converts to integer.

public static roundedInt(string $i_stInt[, int $i_iPrecision = 0 ][, string|null $i_nstError = null ]) : int
Parameters
$i_stInt : string

The string to parse

$i_iPrecision : int = 0

Number of decimal places before rounding

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the string cannot be parsed as a float

Return values
int —

The parsed, rounded, and converted integer value

summarizeOptions()

Creates a summary string of options for error messages.

public static summarizeOptions(array<int, string> $i_rOptions) : string

Limits the display to the first 4 options plus "..." if there are more than 5 options.

Parameters
$i_rOptions : array<int, string>

The list of options to summarize

Return values
string —

A comma-separated summary of the options

time()

Parses and validates a time string.

public static time(string $i_stTime[, string|null $i_nstError = null ]) : string
Parameters
$i_stTime : string

The time string to parse

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the string is not a valid time

Return values
string —

The validated time string in standard format

timeStamp()

Parses a date-time string and converts it to a Unix timestamp.

public static timeStamp(string $i_stTimeStamp[, string|null $i_nstError = null ]) : int
Parameters
$i_stTimeStamp : string

The date-time string to parse

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the string is not a valid date-time

Return values
int —

The Unix timestamp

unsignedFloat()

Parses a string to a non-negative floating-point number (>= 0).

public static unsignedFloat(string $i_stFloat[, string|null $i_nstError = null ]) : float
Parameters
$i_stFloat : string

The string to parse

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the string is not a non-negative float

Return values
float —

The parsed non-negative float value

unsignedInt()

Parses a string to a non-negative integer (>= 0).

public static unsignedInt(string $i_stInt[, string|null $i_nstError = null ]) : int
Parameters
$i_stInt : string

The string to parse

$i_nstError : string|null = null

Optional custom error message

Tags
throws
ParseException

If the string is not a non-negative integer

Return values
int —

The parsed non-negative integer value


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results