README

Validation library for PHP 8.4+. The package provides validators, rule composition, string rule syntax, property attributes, mapped validators, immutable validation context, localized messages, and factories for framework integration.

Installation

composer require componenta/validation

The Composer package installs the dependencies needed by all bundled rules. When the package is wired through Componenta\Validation\ConfigProvider, the container must provide Cycle\Database\DatabaseInterface and Componenta\Detector\MimeTypeDetectorInterface, because the default rule factory is built with database and MIME support.

If you instantiate Componenta\Validation\Rule\RuleFactory manually, both dependencies are optional constructor arguments. Passing null disables the rules that need that dependency:

• exists and unique are registered only when a database is available;
• mime_type and MIME checks inside file are registered only when a detector is available;
• framework registration is provided by Componenta\Validation\ConfigProvider.

Related Packages

Quick Start

use Componenta\Validation\Rule\RuleFactory;
use Componenta\Validation\Validator;

$ruleFactory = new RuleFactory();

$validator = new Validator([
    'email' => $ruleFactory->createRule('required|email|length:5,255'),
    'age' => $ruleFactory->createRule('int|range:18,120'),
]);

$result = $validator->validate([
    'email' => 'user@example.com',
    'age' => 25,
]);

if ($result !== true) {
    $errors = $result->toArray();
}

In a framework application, inject ValidatorFactoryInterface and call createFrom() with an array of field names to rule definitions:

$validator = $factory->createFrom([
    'email' => 'required|email|length:5,255',
]);

A standalone string rule is not a validator definition.

Validator Contract

ValidatorInterface::validate(iterable $data, ?ContextInterface $context = null) returns:

• true when validation passes;
• ErrorMessageCollectorInterface when validation fails.

When ContextInterface::THROW_ON_FAILURE_ATTRIBUTE is true, validation throws ValidationException instead of returning the collector.

$result = $validator->validate(['email' => 'invalid']);

if ($result !== true) {
    $result->has('email');
    $result->get('email');
    $result->toArray();
}

Validator is immutable. Methods such as withRules(), withWalker(), withFormatter(), and withLocale() return new validators.

Field Paths And Wildcards

Rules are keyed by field path. Nested arrays use dot notation. Wildcards validate every element at that level.

$validator = $factory->createFrom([
    'user.email' => 'required|email',
    'users.*.email' => 'required|email',
    'tags.*' => 'string|length:1,50',
]);

The walker reports errors under fully qualified paths, for example users.0.email.

Rule Syntax

Rules are created by RuleFactoryInterface.

$ruleFactory->createRule('email');
$ruleFactory->createRule('required|email|length:5,255');
$ruleFactory->createRule('nullable|email');
$ruleFactory->createRule('oneof:email,phone');

Syntax:

• name
• name:param1,param2
• ruleA|ruleB|ruleC
• regex:/^\d+$/

Pipe-separated rules are wrapped in AllOf: every rule must pass. nullable|... is special: null passes immediately; non-null values must pass the remaining rules.

Composite string rules (allof, oneof, arrayof) parse their parameters as nested rule definitions. Other rules treat parameters as plain strings.

Built-In Rules

Attribute Validation

AttributeValidationProvider builds validators from class property attributes. The attribute classes are also allowed on parameters so other framework layers can reuse the same metadata, but this provider itself scans properties only.

use Componenta\Validation\Attribute\Field;
use Componenta\Validation\Attribute\Validate;
use Componenta\Validation\Attribute\When;
use Componenta\Validation\Rule\Email;
use Componenta\Validation\Rule\Required;

final class CreateUserCommand
{
    #[Field('user_email')]
    #[Required]
    #[Email]
    #[Validate('length:5,255')]
    public string $email;

    #[When('status:published', then: 'required|string', else: 'nullable|string')]
    public ?string $summary = null;
}

Field name resolution order:

1. #[Field('name')]
2. #[Validate(..., as: 'name')]
3. PHP property name

Attribute types:

Rules requiring services should use RuleAttribute subclasses so the real rule is built by RuleFactory.

Validation Providers

ValidationProviderInterface resolves validators by entry id, usually class name.

ValidationProviderFactory builds different chains:

• development: validatable, mapped, attribute, validated-by;
• production: validatable and mapped.

Reflection-based attribute provider is excluded from production by default.

Custom Rules

Rules implement RuleInterface.

use Componenta\Validation\ContextInterface;
use Componenta\Validation\Error\ErrorMessage;
use Componenta\Validation\Error\ErrorMessageCollector;
use Componenta\Validation\Error\ErrorMessageCollectorInterface;
use Componenta\Validation\Rule\RuleInterface;

final class Uppercase implements RuleInterface
{
    public string $name {
        get => 'uppercase';
    }

    public function validate(mixed $value, ContextInterface $context): true|ErrorMessageCollectorInterface
    {
        if (is_string($value) && $value === strtoupper($value)) {
            return true;
        }

        $collector = new ErrorMessageCollector();
        $collector->add(
            (string) $context->getAttribute(ContextInterface::CURRENT_PATH_ATTRIBUTE, ''),
            new ErrorMessage($context, 'validation.uppercase.invalid'),
        );

        return $collector;
    }
}

Register it through RuleFactory::register():

$ruleFactory->register('uppercase', static fn (): RuleInterface => new Uppercase());
$ruleFactory->alias('upper', 'uppercase');

For composite rules whose parameters should be parsed as nested rules, pass composite: true.

Context

Context is immutable. Use withAttribute() and withAttributes() to derive a modified context.

use Componenta\Validation\Context;
use Componenta\Validation\ContextInterface;

$context = new Context([
    ContextInterface::STOP_ON_FIRST_FAILURE_ATTRIBUTE => true,
    ContextInterface::THROW_ON_FAILURE_ATTRIBUTE => true,
]);

Important context attributes:

Messages

MessageFormatterInterface formats error keys through dictionaries. If ConfigKey::DICTIONARY is empty, MessageFormatterFactory loads default dictionaries for configured locales.

Configuration keys:

Default locale constants include LOCALE_EN, LOCALE_RU, LOCALE_ES, LOCALE_FR, and LOCALE_DE.

ConfigProvider

Componenta\Validation\ConfigProvider registers:

• ValidatorFactoryInterface
• ValidationProviderInterface
• RuleFactoryInterface
• MessageFormatterInterface
• default locale configuration

Rule factory creation accepts normal callable factories; it does not require DI-specific lazy service factories.