README

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

Requirements

• PHP 8.2+

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' => 'alice@example.com',
    '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' => '  Alice@Example.COM  ',
    '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.

Conditional Fields

Use when() on an ObjectSchema to conditionally require additional fields based on the value of another field.

$schema = Schema::object([
    'type' => Schema::string(),
    'email' => Schema::string()->email(),
])->when('type', 'business', [
    'company_name' => Schema::string()->min(1),
    'tax_id' => Schema::string(),
]);

// When type is 'business', company_name and tax_id are also validated
// When type is anything else, those fields are ignored

Schema Composition

Use extend() to create a new schema that combines the fields of the current schema with additional fields.

$base = Schema::object(['name' => Schema::string(), 'email' => Schema::string()->email()]);
$admin = $base->extend(['role' => Schema::string(), 'permissions' => Schema::arrayOf(Schema::string())]);
// $admin validates name, email, role, and permissions
// $base is unchanged

Custom Error Messages

Use withMessages() on a ValidationResult to replace default error messages for specific fields.

$result = $schema->validateData($data);

$result = $result->withMessages([
    'name' => 'Please enter your full name',
    'email' => 'A valid email address is required',
]);

API

Schema (static factory)

ValidationResult

ObjectSchema extras

Common Modifiers

All schema types support:

Development

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

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT