PHP Luminova: Input Validation Rules

The Rule class provides a fluent, static API for defining validation rules when validating request data. It ensures that input data is properly structured before processing or storage.

Unlike legacy string-based rules, the fluent rule builder offers:

• better readability
• default error message based on rule.
• IDE auto-completion support
• predictable and structured rule definitions
• improved maintainability

This approach replaces fragile string parsing with explicit, type-safe rule construction.

Rule Structure

Each Rule method returns a structured array:

Example:

Rule::minLength(5, 'Minimum 5 characters required.')

Resolves internally to:

['minLength', [5], 'Minimum 5 characters required.']

Usages

Defining Rules

Rules are assigned per field using an array:

$validation->rules = [
    'username' => [
        Rule::required('Username is required.'),
        Rule::minLength(3, 'Must be at least 3 characters.'),
    ],
];

Each field can contain multiple rules, executed in order.

Applying Rules

You can define validation rules directly within your controller or service class:

$this->input->setRules([
    'email' => [
        Rule::required(),
        Rule::email(),
    ],

    'username' => [
        Rule::required(),
        Rule::alphanumeric(),
        Rule::minLength(3),
        Rule::maxLength(20),
    ],

    'age' => [
        Rule::required(),
        Rule::between(18, 50),
    ],
]);

Passing Arguments

Some rules accept parameters to refine validation behavior.

Examples:

Ensures the value contains at least 6 characters.

Rule::minLength(6)

With comparison:

Ensures the field value is not equal to another field.

Rule::notEqual('password')

Custom Messages

Each rule can define its own error message:

Rule::required('Email is required.')

If no message is provided, the validator will fallback to a default message (depending on rule-type).

Class Definition

• Full namespace: \Luminova\Security\Rule
• This class is marked as final and can't be subclassed
• This class is a Final class

Methods

for

Build a validation rule definition.

public static for(string $rule, ?array $argument, ?string $error = null): array<int,mixed>

This method creates a structured rule array used by the validation engine.It supports passing optional arguments and a custom error message.

If no error message is provided, a default message is generated using:The {field} is invalid ({rule}).

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

Throws:

• \Luminova\Exceptions\InvalidArgumentException - If invalid rule name.

isRule

Check if a validation rule exists.

public static isRule(string $name): bool

This method does not perform validation. It only verifies whetherthe given rule name is supported by the validator.

Parameters:

Return Value:

bool - Return true if rule exists, false otherwise.

required

Require that the field is not empty or null.

public static required(?string $error = null): array<int,mixed>

Rule name: required

Fails when the value is an empty string, null, or otherwiseconsidered empty by the validator's internal isEmpty check.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

nullable

Indicate that the field can be empty or null.

public static nullable(): array<int,mixed>

Rule name: nullable

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

isString

Require that the value is a PHP string.

public static isString(?string $error = null): array<int,mixed>

Rule name: string

Fails when is_string($value) returns false.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

numeric

Require that the value is numeric.

public static numeric(?string $error = null): array<int,mixed>

Rule name: numeric

Delegates to PHP's is_numeric(), so integer strings andfloat strings both pass.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

boolean

Require that the value is a valid boolean representation.

public static boolean(?string $error = null): array<int,mixed>

Rule name: boolean

Accepts true, false, 1, 0, "true", "false", "yes","no", etc., as determined by the validator.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

integer

Require that the value is an integer.

public static integer(?string $type = 'unsigned', ?string $error = null): array<int,mixed>

Rule name: integer

An optional type qualifier constrains the integer further:

• positive — value must be greater than zero.
• negative — value must be less than zero.
• unsigned — value must be greater or equals to zero.
• null — any valid integer.

Values containing a decimal point (.) are always rejected.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

digit

Require that the value consists of decimal digits only.

public static digit(?string $error = null): array<int,mixed>

Rule name: digit

Delegates to ctype_digit(). Floats, negative numbers, andleading/trailing spaces will fail.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

isFloat

Require that the value is a floating-point number.

public static isFloat(?string $type = 'unsigned', ?string $error = null): array<int,mixed>

Rule name: float

An optional type qualifier constrains the float:

• positive — value must be greater than zero.
• negative — value must be less than zero.
• unsigned — value must be greater or equals to zero.
• any — any float (default).

Values containing scientific notation (e.g. 1e5) are rejected.Integer values without a decimal point are also rejected.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

decimal

Require that the value is a decimal number (must contain a decimal point).

public static decimal(?string $type = 'unsigned', ?string $error = null): array<int,mixed>

Rule name: decimal

Behaves like self::float() but additionally requires the valueto contain a . character, ruling out plain integers.

An optional type qualifier constrains the result:

• positive — value must be greater than zero.
• negative — value must be less than zero.
• unsigned — value must be greater or equals to zero.
• null — any decimal (default).

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

alphanumeric

Require that the value is alphanumeric.

public static alphanumeric(?string $error = null): array<int,mixed>

Rule name: alphanumeric

Delegates to ctype_alnum(). The value must be a non-empty stringcontaining only ASCII letters (A-Z, a-z) and digits (0-9).

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

alphabet

Require that the value contains alphabetic characters only.

public static alphabet(?string $error = null): array<int,mixed>

Rule name: alphabet

Delegates to ctype_alpha(). Digits, spaces, and special characterswill cause validation to fail.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

email

Require that the value is a valid e-mail address.

public static email(array $rejectDomains = [], bool $allowIdn = false, ?string $error = null): array<int,mixed>

Rule name: email

Optionally reject specific domains and/or allow internationalizeddomain names (IDN).

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

url

Require that the value is a valid URL.

public static url(bool $allowIdn = false, bool $httpOnly = true, ?string $error = null): array<int,mixed>

Rule name: url

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

json

Require that the value is a valid JSON string.

public static json(?string $error = null): array<int,mixed>

Rule name: json

Delegates to PHP's json_validate(). The value must be a string.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

array

Require that the value is an array or a JSON-encoded array string.

public static isArray(?string $error = null): array<int,mixed>

Rule name: array

Passes when is_array($value) is true, or when the value is astring that decodes to an array via json_decode().

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

binary

Require that the value is a valid binary representation.

public static binary(bool $strict = true, bool $allowPrintable = false, ?string $error = null): array<int,mixed>

Rule name: binary

Behavior is controlled by the two flags, matching the validator's

• $strict = true (default) — only characters 0 and 1 are accepted.
• $strict = false — PHP-style binary literals (e.g. 0b1010) are also accepted.
• $allowPrintable = true — when non-strict, printable ASCII strings are accepted as a fallback.
• $allowPrintable = false — printable ASCII fallback is disabled (default).

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

hexadecimal

Require that the value is a valid hexadecimal string.

public static hexadecimal(?string $error = null): array<int,mixed>

Rule name: hexadecimal

Delegates to ctype_xdigit(). The value must not be an array.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

min

Require that the value is greater than or equal to a minimum.

public static min(float|int $value, ?string $error = null): array<int,mixed>

Rule name: min

Universal rule — type is auto-detected:

• Numeric: the numeric value is compared.
• String: the character length is compared.
• Array: the element count is compared.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

max

Require that the value is less than or equal to a maximum.

public static max(float|int $value, ?string $error = null): array<int,mixed>

Rule name: max

Universal rule — type is auto-detected:

• Numeric: the numeric value is compared.
• String: the character length is compared.
• Array: the element count is compared.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

fixed

Require that the value is exactly equal to the given number.

public static fixed(float|int $value, ?string $error = null): array<int,mixed>

Rule name: fixed

Universal rule — type is auto-detected:

• Numeric: the numeric value is compared.
• String: the character length is compared.
• Array: the element count is compared.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

between

Require that the value falls within a range (inclusive).

public static between(float|int $min = 1, float|int $max = 100, ?string $error = null): array<int,mixed>

Rule name: between

Works with both numbers and strings:

• Numeric values: the number is compared directly.
• Strings: the character length is compared.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

length

Require that the string length is exactly $length characters.

public static length(int $length, ?string $error = null): array<int,mixed>

Rule name: length

Type-specific: only applied to string values.Maps to the 'fixed' comparator internally.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

minLength

Require that the string length is at least $length characters.

public static minLength(int $length, ?string $error = null): array<int,mixed>

Rule name: minlength

Type-specific: only applied to string values.Maps to the 'min' comparator internally.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

maxLength

Require that the string length does not exceed $length characters.

public static maxLength(int $length, ?string $error = null): array<int,mixed>

Rule name: maxlength

Type-specific: only applied to string values.Maps to the 'max' comparator internally.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

limit

Require that the numeric value equals exactly $value.

public static limit(float|int $value, ?string $error = null): array<int,mixed>

Rule name: limit

Type-specific: only applied to numeric values.

Similar to fixed() but operates in the limit contextused by the validator for numeric fields.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

minLimit

Require that the numeric value is at least $value.

public static minLimit(float|int $value, ?string $error = null): array<int,mixed>

Rule name: minlimit

Type-specific: only applied to numeric values.Maps to the min() comparator internally.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

maxLimit

Require that the numeric value does not exceed $value.

public static maxLimit(float|int $value, ?string $error = null): array<int,mixed>

Rule name: maxlimit

Type-specific: only applied to numeric values.Maps to the max() comparator internally.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

size

Require that the array contains exactly $count elements.

public static size(int $count, ?string $error = null): array<int,mixed>

Rule name: size

Type-specific: only applied to array values.Maps to the fixed() comparator internally.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

minSize

Require that the array contains at least $count elements.

public static minSize(int $count, ?string $error = null): array<int,mixed>

Rule name: minsize

Type-specific: only applied to array values.Maps to the 'min' comparator internally.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

maxSize

Require that the array does not exceed $count elements.

public static maxSize(int $count, ?string $error = null): array<int,mixed>

Rule name: maxsize

Type-specific: only applied to array values.Maps to the 'max' comparator internally.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

latitude

Require that the value is a valid geographic latitude coordinate.

public static latitude(bool $strict = false, int $precision = 6, ?string $error = null): array<int,mixed>

Rule name: latitude

Accepts values in the range −90 to +90.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

lat

Short alias for latitude().

public static lat(bool $strict = false, int $precision = 6, ?string $error = null): array<int,mixed>

Rule name: lat

Useful for shorter rule expressions while retaining the same behavior.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

longitude

Require that the value is a valid geographic longitude coordinate.

public static longitude(bool $strict = false, int $precision = 6, ?string $error = null): array<int,mixed>

Rule name: longitude

Accepts values in the range −180 to +180. Delegates to Math::isLng().

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

lng

Alias for longitude().

public static lng(bool $strict = false, int $precision = 6, ?string $error = null): array<int,mixed>

Rule name: lng

Useful for shorter rule expressions while retaining the same behavior.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

latLng

Require that the value is a valid latitude,longitude coordinate pair.

public static latLng(bool $strict = false, int $precision = 6, ?string $error = null): array<int,mixed>

Rule name: latlng

The field value must be a comma-separated string (e.g. "51.5074,-0.1278").The lat and lng parts are split from the value, $strict and $precisionare applied to validation.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

ip

Require that the value is a valid IP address.

public static ip(int $version = 0, ?string $error = null): array<int,mixed>

Rule name: ip

Pass 4 for IPv4-only, 6 for IPv6-only,or 0 to accept any version. When no argument is given the validatordefaults to 0 (any version).

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

uuid

Require that the value is a valid UUID string.

public static uuid(int $version = 4, ?string $error = null): array<int,mixed>

Rule name: uuid

Validates the string format against the specified UUID version.When no argument is given the validator defaults to version 4.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

phone

Require that the value is a valid phone number.

public static phone(int $min = 10, int $max = 15, ?string $error = null): array<int,mixed>

Rule name: phone

The digit count of the number (after stripping formatting characters) must fall between $minand $max inclusive.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

path

Require that the value is a valid file-system path.

public static path(?string $access = null, ?string $error = null): array<int,mixed>

Rule name: path

The optional $access argument controls what "valid" means:

• null — the value must match a well-formed absolute path pattern (default).
• readable — the path must exist and be readable (is_readable()).
• writable — the path must exist and be writable (is_writable()).

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

scheme

Require that the value is a string with a valid URI scheme.

public static scheme(string $protocol = null, ?string $error = null): array<int,mixed>

Rule name: scheme

When $protocol is empty (default) any syntactically valid scheme isaccepted (e.g. http://, ftp://, mailto:).When $protocol is provided (e.g. 'https') the value must beginwith exactly that scheme followed by :.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

equals

Require that the value equals the value of another field in the same request body.

public static equals(string $field, ?string $error = null): array<int,mixed>

Rule name: equals

Useful for "confirm password" style checks where two fields must match.Comparison is strict (===) after both values are normalized through toValue().

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

notEqual

Require that the value does not equal the value of another field in the same request body.

public static notEqual(string $field, ?string $error = null): array<int,mixed>

Rule name: not_equal

Comparison is strict (!==) after both values are normalized.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

isValue

Require that the value is exactly a specified literal value.

public static isValue(mixed $value, ?string $error = null): array<int,mixed>

Rule name: is_value

Unlike equals(), which compares against another field'sruntime value, this compares the field against a hard-coded literalthat is embedded directly in the rule expression.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

regex

Require that the value matches a regular-expression pattern.

public static regex(string $pattern, ?string $error = null): array<int,mixed>

Rule name: regex

Provide the pattern without enclosing delimiters; the validatorwraps it in /…/ automatically before calling preg_match().

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

inArray

Require that the value is present in a given list.

public static inArray(array $values, bool $strict = false, ?string $error = null): array<int,mixed>

Rule name: in_array

When $strict is false (default) the comparison is type-coercing (==).When $strict is true strict type-safe comparison (===) is used.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

isList

Require that the value is a comma-separated list with a minimum number of items.

public static isList(int $min = 1, ?string $error = null): array<int,mixed>

Rule name: is_list

The value must be a string. Items are split by ,, trimmed, and emptysegments are discarded before the count is compared against $min.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

keyExists

Require that at least one of the given keys exists in the array value.

public static keyExists(array $keys, ?string $error = null): array<int,mixed>

Rule name: key_exists

Passes when the intersection of $keys and the field value's array keysis non-empty. Fails if the field value is not an array, or if none ofthe specified keys are present.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

keysExists

Require that all specified keys exist in the array value.

public static keysExists(array $keys, bool $strict = false, ?string $error = null): array<int,mixed>

Rule name: keys_exists

When $strict is false (default) only a subset check is performed,extra keys in the value are allowed.When $strict is true the value must contain exactly $keys andno additional keys (bidirectional diff check).

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

username

Require that the value is a valid username.

public static username(bool $allowUppercase = true, array $reservedUsernames = [], ?string $error = null): array<int,mixed>

Rule name: username

Validates:

• Length: 3–64 UTF-8 characters.
• Allowed characters: letters, numbers, _, -, . ([\p{L}\p{N}_.-]).
• No whitespace.
• No all-uppercase (even when $allowUppercase is true).
• No all-numbers string.
• No leading/trailing hyphens or dots.
• No consecutive hyphens (--), underscores (__), or dots (..).

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

callback

Validate the field value with a custom callable.

public static callback(callable|array|string $fn, ?string $error = null): array<int,mixed>

Rule name: callback

The callable receives ($fieldValue, $fieldName) and must returna truthy value to indicate success or a falsy value for failure.

Supported callable formats:

• Closure: fn($value, $field): bool
• Plain function name: 'myFunction'
• Instance method: 'MyClass@method'
• Static method string: 'MyClass::method'
• Static array: [MyClass::class, 'method']

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

default

Assign a default value to the field when it is empty or missing.

public static default(mixed $value): array<int,mixed>

Rule name: default

When the field value is empty the validator replaces it with $valuein the validated body and on the request object (when available).No validation error is recorded for this rule.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.

fallback

Alias for default().

public static fallback(mixed $value): array<int,mixed>

Rule name: fallback

Identical behavior, handled by the same case 'fallback': branchin the validator. Use whichever name reads more naturally in context.

Parameters:

Return Value:

array{0: string, 1: ?array, 2: string} - Return an array that resolve to rule.