philiprehberger/php-schema-validator

Fluent data schema validator with nested objects, arrays, and dot-notation errors

v1.1.1 2026-03-17 20:06 UTC

Requires

• php: ^8.2

Requires (Dev)

• laravel/pint: ^1.0
• phpstan/phpstan: ^1.12|^2.0
• phpunit/phpunit: ^11.0

MIT

• Philip Rehberger

• php
• schema
• validator
• fluent
• validation

README

Fluent data schema validator with nested objects, arrays, and dot-notation errors.

Requirements

Dependency	Version
PHP	^8.2

No external dependencies required.

Installation

composer require philiprehberger/php-schema-validator

Usage

use PhilipRehberger\SchemaValidator\Schema;

$schema = Schema::object([
    'name'  => Schema::string()->min(1)->max(100),
    'email' => Schema::string()->email(),
    'age'   => Schema::int()->min(0)->max(150),
]);

$result = $schema->validateData([
    'name'  => 'Alice',
    'email' => '[e-mail]',
    'age'   => 30,
]);

$result->passes(); // true
$result->fails();  // false
$result->errors(); // []

Nested Objects

$schema = Schema::object([
    'user' => Schema::object([
        'profile' => Schema::object([
            'email' => Schema::string()->email(),
        ]),
    ]),
]);

$result = $schema->validateData([
    'user' => ['profile' => ['email' => 'invalid']],
]);

$result->errors(); // ["user.profile.email must be a valid email address"]

Typed Arrays

$schema = Schema::object([
    'tags'  => Schema::arrayOf(Schema::string()),
    'items' => Schema::arrayOf(Schema::object([
        'id'   => Schema::int(),
        'name' => Schema::string(),
    ])),
]);

Optional and Nullable Fields

$schema = Schema::object([
    'name'     => Schema::string(),
    'nickname' => Schema::string()->optional(),  // field may be absent
    'bio'      => Schema::string()->nullable(),  // field may be null
]);

String Validators

Schema::string()->min(3)->max(50);   // length constraints
Schema::string()->email();           // email format
Schema::string()->url();             // URL format
Schema::string()->uuid();            // UUID format
Schema::string()->regex('/^\d+$/');  // custom pattern

Enum Values

Schema::enum(['draft', 'published', 'archived']);

Any Value

Schema::any();           // accepts any non-null value
Schema::any()->nullable(); // accepts anything including null

Custom Validation Rules

Add custom validation logic to any schema type using custom(). The callable receives the value and returns null if valid, or an error message string if invalid.

$schema = Schema::object([
    'username' => Schema::string()->min(3)->custom(function (string $value): ?string {
        if (str_starts_with($value, 'admin')) {
            return 'must not start with "admin"';
        }

        return null;
    }),
    'age' => Schema::int()->min(0)->custom(function (int $value): ?string {
        if ($value % 2 !== 0) {
            return 'must be an even number';
        }

        return null;
    }),
]);

$result = $schema->validateData(['username' => 'admin_user', 'age' => 25]);
$result->errors();
// ["username must not start with "admin"", "age must be an even number"]

Custom validators only run when all built-in checks pass.

Value Transformers

Use transform() to normalize a value before validation. The callable receives the raw value and returns the transformed value.

$schema = Schema::object([
    'email' => Schema::string()->email()->transform(fn (mixed $v) => strtolower(trim($v))),
    'tags'  => Schema::arrayOf(Schema::string())->transform(fn (mixed $v) => array_unique($v)),
]);

$result = $schema->validateData([
    'email' => '  [e-mail]  ',
    'tags'  => ['php', 'laravel', 'php'],
]);

$result->passes(); // true — email was trimmed and lowered before validation

Transformers run before any type or constraint checks (but after the null check).

Cross-Field Validation

Use crossField() on an ObjectSchema to validate relationships between fields. Each callable receives the full data array and returns null if valid, or an error message string.

$schema = Schema::object([
    'password'         => Schema::string()->min(8),
    'password_confirm' => Schema::string(),
    'start_date'       => Schema::string(),
    'end_date'         => Schema::string(),
])->crossField(function (array $data): ?string {
    if ($data['password'] !== $data['password_confirm']) {
        return 'password_confirm must match password';
    }

    return null;
})->crossField(function (array $data): ?string {
    if ($data['start_date'] >= $data['end_date']) {
        return 'end_date must be after start_date';
    }

    return null;
});

$result = $schema->validateData([
    'password'         => 'secret123',
    'password_confirm' => 'different',
    'start_date'       => '2026-03-20',
    'end_date'         => '2026-03-10',
]);

$result->errors();
// ["password_confirm must match password", "end_date must be after start_date"]

Cross-field validators only run when all individual field validations pass.

API

Schema (static factory)

Method	Returns	Description
Schema::object(array $fields)	ObjectSchema	Create an object schema with field definitions
Schema::string()	StringSchema	Create a string schema
Schema::int()	IntSchema	Create an integer schema
Schema::float()	FloatSchema	Create a float schema
Schema::bool()	BoolSchema	Create a boolean schema
Schema::arrayOf(SchemaType $item)	ArraySchema	Create a typed array schema
Schema::enum(array $values)	EnumSchema	Create an enum schema
Schema::any()	AnySchema	Create a schema that accepts any value

ValidationResult

Method	Returns	Description
passes()	bool	True if validation passed
fails()	bool	True if validation failed
errors()	array<string>	All error messages
firstError()	?string	First error message or null

ObjectSchema extras

Method	Description
crossField(callable $validator)	Add a cross-field validator (receives full data array, returns ?string)

Common Modifiers

All schema types support:

Method	Description
optional()	Field may be absent from the parent object
nullable()	Field may be null
custom(callable $validator)	Add a custom validation callback (receives value, returns ?string)
transform(callable $transformer)	Transform the value before validation

Development

composer install
vendor/bin/phpunit
vendor/bin/pint --test
vendor/bin/phpstan analyse

License

MIT