Download the PHP package wscore/leanvalidator without Composer

LeanValidator

An AI-friendly and simple validator for PHP.

Features

• Fluent Interface: Easy to read and write validation rules.
• Whitelist Validation: getValidatedData() returns only the data that has been validated.
• Nested Structures: Supports validation of arrays and nested objects using asList() and asObject().
• Flexible Rules: Use built-in rules, closures, or any PHP callable.
• AI-Friendly: Simple and consistent API that is easy for AI to understand and generate.

Sanitizer:

This package also provides a sanitization utility that can be used to clean and transform input data.

• Sanitization: Automatic UTF-8 conversion and trimming of strings. Supports custom rules and nested data using dot-notation and wildcards.

Installation

Use composer to install the package.

Basic Usage

Initialization

You can create a validator instance using the make method.

Defining Rules

Use field to specify the field and chain validation rules.

Checking Results

Rules and Messages

Default Error Messages

By default, the validator provides two error messages for common validation rules:

• Default error: "Please check the input value." (used for rules like int, email, etc.)

• Required error: "This field is required." (used for required)

• If the age field is missing, the error message will be "This field is required."
• If the value is not an integer or is less than 18, the error message will be "Please check the input value."

You can change these default messages for the entire validator instance:

Custom Error Messages

You can set custom messages at three levels:

1. Rule level: Use with() to set a custom message for the next rule in the chain. This message is used only for that rule and is cleared immediately after.
2. Field level: Use the second argument of field() to set a default error message for all rules in that field.
3. Manual level: Use addError(string $field, string $message) to manually add an error to a specific field.
4. Required level: Pass a custom message directly to required().

The message() call only affects the rule that immediately follows it. If you want to use custom messages for multiple rules, call message() before each one.

The validator searches for messages in the following order:

1. Message passed directly to the rule (via message() or required($msg)).
2. Message passed to field($key, $msg).
3. Global default message (defaultMessage or defaultMessageRequired).

Getting Error Messages

If isValid() returns false, you can retrieve error messages from the validator:

The MessageBag also supports retrieving messages using HTML form field names:

Validation Flow

Optional Fields

Required Fields

Conditional Required Fields (requiredIf, requiredWith, requiredWithout)

Use these methods to make a field required based on another field.

requiredIf(string $otherKey, mixed $expect, ?string $msg = null, mixed $elseOverwrite = null)

Required if $otherKey's value matches $expect.

requiredUnless(string $otherKey, mixed $expect, ?string $msg = null, mixed $elseOverwrite = null)

Required unless $otherKey's value matches $expect.

requiredWith(string $otherKey, ?string $msg = null, mixed $elseOverwrite = null)

Required if $otherKey exists in the input data (even if it's null).

requiredWithout(string $otherKey, ?string $msg = null, mixed $elseOverwrite = null)

Required if $otherKey does not exist in the input data.

requiredWhen(callable $call, ?string $msg = null, mixed $elseOverwrite = null)

Required if the callback $call($data) returns true. The $data contains all input data.

elseOverwrite

For all these methods, if the condition is not met, you can provide an elseOverwrite value. The field will be set to this value and further validation rules in the chain will be skipped.

Built-in Rules

• string(): Checks if value is a string.
• int(): Checks that the value is a PHP integer (is_int).
• min(int|float $min): Value must be numeric and >= $min.
• max(int|float $max): Value must be numeric and <= $max.
• between(int|float $min, int|float $max): Value must be numeric and between $min and $max (inclusive; if $min > $max the bounds are swapped).
• float(): Validates if the value is a float.
• email(): Validates email format.
• url(): Validates URL format.
• regex(string $pattern): Validates against a regular expression.
• alnum(): Validates alphanumeric characters.
• alpha(): Validates alphabetic characters.
• digit(): Validates that the value is a string containing only ASCII digits (0–9), one or more characters.
• numeric(): Validates that the value is numeric in the PHP sense (is_numeric()), including int/float and numeric strings (e.g. "123", "1.5").
• in(array $choices): Validates if the value is within the given choices. Supports Enum::cases().
• enum(string $enumClass): Validates if the value matches the given BackedEnum (value) or UnitEnum (name).
• contains(string $needle): Validates if the value contains the needle.
• startsWith(string $prefix): Validates if the string value starts with the prefix.
• endsWith(string $suffix): Validates if the string value ends with the suffix.
• json(): Validates that the value is a string containing syntactically valid JSON (json_decode with no JSON error).
• bool(): Validates that the value is strictly a PHP boolean (is_bool), i.e. true or false (not 1, "true", etc.).
• equalTo(mixed $expect): Validates if the value is equal to the expected value.
• sameAs(string $otherKey): Validates that the value strictly matches (===) the value at another top-level input key (e.g. password confirmation against password).
• length(?int $min = null, ?int $max = null): Checks the length of a string.
• filterVar(int $filter): Uses PHP's filter_var.

Advanced Validation

Validating Enums

You can validate against PHP Enums using enum() or in().

When using enum() with a BackedEnum: int, the validator automatically casts numeric strings to integers before validation.

Validating Arrays of Scalars

Use asList() to apply a rule to every element in an array.

Validating Array Size

Use arrayCount() to validate the number of elements in an array.

Validating Nested Objects (Associative Arrays)

Use asObject() to validate a nested associative array without using dot-notation in field. Only the validated fields will be included in getValidatedData() (whitelist).

Validating Arrays of Objects (Nested Data)

Use asListObject() to validate complex nested structures.

Custom Validators

You can use apply() to use any callable, closure, or rule class as a validation rule.

Extending: Custom Rules and IDE Completion

You can add project-specific rules with IDE code completion by extending ValidatorRules and overriding createRules() on your Validator (or ValidatorData) subclass.

1. Extend ValidatorRules and add your methods (or register names in $rules and use @method in the docblock).
2. Override createRules() in your Validator subclass to return your rules instance.
3. Override field() with @return YourValidatorRules so that $v->field('x') is inferred as your class and your custom methods appear in autocomplete.

Language- or context-specific Rules (Japanese, etc.)

For Japanese-specific validations, use the Wscore\LeanValidator\Rule\Ja class.

Available rules in Ja class:

• hiragana(): Hiragana only.
• katakana(): Katakana only.
• kana(): Hiragana and Katakana.
• hankakuKana(): Hankaku-Katakana.
• kanji(): Kanji only.
• zenkaku(): Zenkaku characters (non-ASCII).
• zip(): Japanese Zip code (000-0000).
• tel(): Japanese Phone number.

Network-specific Rules (IP, UUID, etc.)

For network-related validations, use the Wscore\LeanValidator\Rule\Net class.

Available rules in Net class:

• ip(int $flags = 0): IP address (v4 or v6).
• ipv4(): IPv4 address.
• ipv6(): IPv6 address.
• mac(): MAC address.
• uuid(): UUID.
• domain(): Domain name.

Date-specific Rules (HTML date/time, etc.)

For HTML date/time formats and date constraints, use the Wscore\LeanValidator\Rule\Date class.

Available rules in Date class:

• htmlDate(): HTML5 <input type="date"> (Y-m-d).
• htmlMonth(): HTML5 <input type="month"> (Y-m).
• htmlTime(): HTML5 <input type="time"> (H:i or H:i:s).
• htmlDateTimeLocal(): HTML5 <input type="datetime-local"> (Y-m-d\TH:i or Y-m-d\TH:i:s).
• htmlWeek(): HTML5 <input type="week"> (YYYY-Www).
• notFutureDate(?string $format = 'Y-m-d'): Rejects dates strictly in the future, using the given format.

You can also create a Rules subclass for better IDE support:

Rules added with addRule() or by merging callables into $this->rules in the constructor (same shape as Sanitizer::$rules: fn ($value) => bool, e.g. 'ip' => fn ($v) => is_string($v) && filter_var($v, FILTER_VALIDATE_IP) !== false) work with apply('name') and __call, but will not show in IDE completion unless you add a corresponding @method on your Rules subclass.

API Reference

Validator::make(array|string|numeric $data): static

Creates a validator. If a string or number is passed, it treats it as a single item to be validated.

field(string $key, ?string $errorMsg = null): static

Specifies the field to validate. Optionally sets a default error message for any rule in the chain.

required(?string $msg = null): static

Marks the field as required.

optional(mixed $default = null): static

Marks the field as optional. If the field is missing, it will be set to the default value.

requiredIf(string $otherKey, mixed $expect, ?string $msg = null, mixed $elseOverwrite = null): static

Marks the field as required if the value of $otherKey matches $expect.

• If matched: acts like required($msg).
• If not matched:
  • If $elseOverwrite is provided, sets the field to this value and skips further validation.
  • Otherwise, acts like optional().

requiredWith(string $otherKey, ?string $msg = null, mixed $elseOverwrite = null): static

Marks the field as required if $otherKey exists.

• If exists: acts like required($msg).
• Otherwise: acts like optional() or overwrites if $elseOverwrite is provided.

requiredWithout(string $otherKey, ?string $msg = null, mixed $elseOverwrite = null): static

Marks the field as required if $otherKey does not exist.

• If not exists: acts like required($msg).
• Otherwise: acts like optional() or overwrites if $elseOverwrite is provided.

requiredWhen(callable $call, ?string $msg = null, mixed $elseOverwrite = null): static

Marks the field as required if $call($data) returns true.

• If true: acts like required($msg).
• Otherwise: acts like optional() or overwrites if $elseOverwrite is provided.

isValid(): bool

Returns true if there are no validation errors.

getValidatedData(): array

Returns the validated data. Throws RuntimeException if validation failed.

getErrorsFlat(): array

Returns a flat array of error messages where keys are the field names.

addError(string $fieldName, string $errorMessage): static

Manually adds an error message to a specific field. Useful for errors that cannot be expressed with validation rules.

Sanitizer Features

The Sanitizer class provides various methods to clean and transform input data.

Default Sanitization

• UTF-8 Conversion: Ensures strings are valid UTF-8.
• Trimming: Removes surrounding whitespace using Unicode-aware regex.

Built-in Rules

Use these methods to apply specific transformations:

• toUtf8(...$fields): Ensures valid UTF-8.
• toTrim(...$fields): Trims whitespace.
• toDigits(...$fields): Removes all non-digit characters.
• toInt(...$fields): If the string is a valid decimal integer (FILTER_VALIDATE_INT), converts it to PHP int; otherwise leaves the string unchanged so validation can reject it.
• toFloat(...$fields): If the string is a valid float (FILTER_VALIDATE_FLOAT), converts it to PHP float; otherwise leaves the string unchanged.
• toBool(...$fields): Uses FILTER_VALIDATE_BOOLEAN with FILTER_NULL_ON_FAILURE. Recognized true values include (case-insensitive) 1, true, on, yes; false values include 0, false, off, no, and empty string. Anything else (e.g. maybe, 2) is left as the original string so validation can reject it. Output is real PHP bool; map to 0/1 or DB types at persistence if your schema requires it.
• toLower(...$fields): Converts to lowercase.
• toUpper(...$fields): Converts to uppercase.
• toKana(...$fields): Converts to Zenkaku-Kana (needs mbstring).
• toHankaku(...$fields): Converts to Hankaku-Kana (needs mbstring).
• toZenkaku(...$fields): Converts to Zenkaku-Kana/Alphanumeric (needs mbstring).

Skipping Sanitization

• skip(...$fields): Skips all sanitization (useful for passwords).
• skipTrim(...$fields): Skips only the trimming process.

Dot-Notation and Wildcards

You can target nested data using dot-notation and wildcards.

Adding Custom Rules

You can add your own sanitization rules using addRule().

Data Sanitization

By default, the Validator can sanitize input data using the Sanitizer class. To apply sanitization, you must explicitly call the sanitize() method before validation.

By default, the Sanitizer converts strings to UTF-8 and trims surrounding whitespace. If you don't call sanitize(), the validation will be performed on the raw input data.