#Валідація

Валідатор Lift відповідає на одне запитання: «чи відповідають ці вхідні дані очікуваним мною правилам?» — і дає точний перелік того, що не пройшло.

Він працює з будь-яким асоціативним масивом: тіло HTTP-запиту, рядок запиту, параметри JSON-RPC, аргументи CLI, навіть рядок, прочитаний з іншого сервісу. DSL навмисно схожий на Laravel, тому крива навчання майже нульова.

Ментальна модель: ви описуєте кожне поле списком правил ('required|email|max:255'). Валідатор збирає всі помилки (він не зупиняється на першій) і повертає або очищені дані, або карту помилок.

#1. Тур за 60 секунд

use Lift\Validation\Validator;

$v = new Validator($_POST, [
    'name'     => 'required|string|min:2|max:255',
    'email'    => 'required|email',
    'age'      => 'integer|min:13|max:120',
    'role'     => 'required|in:admin,user,moderator',
    'website'  => 'nullable|url',
]);

if ($v->fails()) {
    return Response::json(['errors' => $v->errors()], 422);
}

$data = $v->validated();

Три речі, які треба пам’ятати:

1. Правила можуть бути рядком через вертикальну риску ('required|email') або масивом правил/об’єктів/замикань (['required', 'email', new MyRule()]).
2. $v->errors() — це array<string, string[]> — кожне поле може мати кілька повідомлень про помилки.
3. $v->validated() повертає лише ті поля, для яких ви оголосили правила (чистий DTO).

#2. Валідація всередині маршруту

В HTTP-обробнику однорядковий $req->validate(...) — найпростіший шлях. Він об’єднує тіло + query + параметри маршруту, запускає валідатор, викидає ValidationException за помилки, а інакше повертає валідований масив. Типовий обробник помилок Lift перетворює виняток на HTTP 422 з правильною формою JSON — try/catch писати не потрібно:

$app->post('/users', function (Request $req) use ($repo) {
    $data = $req->validate([
        'name'     => 'required|string|min:2',
        'email'    => 'required|email',
        'password' => 'required|min:8|confirmed',
    ]);

    return Response::json($repo->create($data), 201);
});

Тіло відповіді за помилки виглядає так:

{
  "errors": {
    "email":    ["The email must be a valid email address."],
    "password": ["The password must be at least 8 characters."]
  }
}

Для типізованого, повторно використовуваного контейнера використовуйте FormRequest.

#3. Шпаргалка з повернених значень

#4. Синтаксис правил

// Через вертикальну риску (компактно, рекомендовано для простих випадків)
'email' => 'required|email|max:255'

// Масив (дозволяє змішувати замикання та об’єкти правил)
'phone' => ['required', 'string', new PhoneRule()]

Правила виконуються у порядку, в якому ви їх перелічили. required, nullable і sometimes особливі — вони впливають на те, чи виконується решта ланцюжка взагалі (див. §6 нижче).

Кілька помилок на поле збираються: валідація не зупиняється на першій невдачі, тому користувач бачить усі проблеми одразу.

#5. Вбудовані правила — повний довідник

#Присутність і потік

'bio'        => 'nullable|string|max:500',          // порожній рядок допустимий
'avatar_url' => 'sometimes|url',                    // може бути відсутнім за PATCH
'profile.id' => 'present',                          // має бути присутнім, навіть як null

#Умовні required / prohibited

Посилайтеся на будь-яке інше поле через крапковий шлях. Працюють і поля верхнього рівня, і вкладені.

'type'         => 'required|in:individual,company',
'company.name' => 'required_if:type,company|string|max:200',
'person.dob'   => 'required_unless:type,company|date',

'admin_token'  => 'prohibited_unless:role,admin|string',
'password'     => 'prohibited_if:role,guest|string|min:8',

#Тип

#Формат

#Обмеження значення

#Правила для масивів

#6. required, nullable, sometimes — коли що відбувається?

Найтонші правила системи. Запам’ятайте цю таблицю:

Простими словами:

• nullable — «це поле можна залишити порожнім / null, але якщо воно заповнене, воно має задовольняти правила».
• sometimes — «це поле може взагалі бути відсутнім у вхідних даних; якщо воно є, валідувати як зазвичай». Ідеально для PATCH-ендпоінтів.
• required — «це поле має бути присутнім і непорожнім».

#7. Вкладені дані з крапковими шляхами

$v = new Validator($data, [
    'user.name'              => 'required|string|max:100',
    'user.email'             => 'required|email',
    'user.address.city'      => 'required|string',
    'user.address.zip'       => 'required|digits_between:5,10',
    'user.preferences.lang'  => 'required|in:en,ru,de,fr',
]);

Помилки мають ключ із тим самим крапковим шляхом:

{ "errors": { "user.address.zip": ["The user.address.zip must be 5-10 digits."] } }

#8. Підстановні знаки (.*) — валідація масивів сутностей

.* розгортається у кожен елемент із цілочисловим індексом батьківського масиву.

$v = new Validator($data, [
    'tags'    => 'required|array|list|distinct|min_items:1|max_items:10',
    'tags.*'  => 'required|string|max:50|alpha_num',
]);

Ключі помилок стають tags.0, tags.1, … тож фронтенд може зіставити помилки з потрібним <input>.

Вкладені підстановні знаки (масив об’єктів):

$v = new Validator($data, [
    'items'              => 'required|array|min_items:1|max_items:100',
    'items.*.name'       => 'required|string|max:200',
    'items.*.sku'        => 'required|string|regex:/^[A-Z0-9\-]+$/',
    'items.*.qty'        => 'required|integer|min:1',
    'items.*.tags'       => 'nullable|array|list|max_items:10',
    'items.*.tags.*'     => 'string|max:50',
]);

#9. Правила-замикання — швидка вбудована логіка

Замикання отримує ($field, $value, $allData, $fail). Викличте $fail("message"), щоб позначити правило проваленим:

$v = new Validator($data, [
    'slug' => [
        'required', 'string', 'min:3',
        function (string $field, mixed $value, array $data, \Closure $fail): void {
            if (str_contains($value, '--')) {
                $fail("The {$field} must not contain consecutive hyphens.");
            }
        },
    ],
]);

Замикання отримує всі дані — ідеально для міжполевих перевірок ('end_date' >= 'start_date' тощо).

#10. Повторно використовувані класи правил (RuleInterface)

Для логіки, яку ви повторно використовуєте у 3+ місцях, оформіть її як клас:

use Lift\Validation\RuleInterface;

final class PhoneRule implements RuleInterface
{
    public function passes(string $field, mixed $value, array $data): bool
    {
        return is_string($value) && preg_match('/^\+?[0-9]{10,15}$/', $value) === 1;
    }

    public function message(): string
    {
        return 'The :attribute must be a valid phone number.';
    }
}

$v = new Validator($data, [
    'phone' => ['required', new PhoneRule()],
]);

Плейсхолдер :attribute автоматично замінюється іменем поля. Перевизначте його для конкретного поля через масив власних повідомлень (наступний розділ).

#11. Власні повідомлення про помилки

Передайте масив третім аргументом конструктора. Ключі — "field.rule" (найконкретніший) або просто "rule" (запасний варіант для всього правила). Плейсхолдери :attribute, :min, :max, :value, :other, :when, :values підставляються автоматично.

$v = new Validator($data, $rules, [
    // На поле
    'email.required' => 'We need your email address.',
    'email.email'    => ':attribute does not look right.',

    // Запасний варіант для всіх полів, що використовують правило
    'required'       => 'This field is required.',
    'min'            => ':attribute must be at least :min.',
]);

Усередині FormRequest перевизначте messages():

public function messages(): array
{
    return [
        'password.min' => 'Password must be at least :min characters.',
    ];
}

#12. Реєстрація власних правил глобально

Для правил, які мають бути доступні всюди ('card' => 'required|luhn'):

use Lift\Validation\Validator;

// Форма-замикання
Validator::extend(
    'luhn',
    fn(string $field, mixed $value, array $data) => $this->checkLuhn($value),
    'The :attribute must be a valid card number.',
);

// Форма RuleInterface (використовує власний message())
Validator::extend('isbn13', new Isbn13Rule());

Реєструйте під час завантаження (наприклад, у public/index.php або файлі початкового завантаження).

#13. Реальний приклад — замовлення в інтернет-магазині

$data = $req->validate([
    // Заголовок замовлення
    'currency'    => 'required|string|size:3|uppercase',
    'coupon_code' => 'nullable|string|max:30|alpha_num',
    'note'        => 'nullable|string|max:1000',

    // Доставка
    'shipping.name'         => 'required|string|max:100',
    'shipping.line1'        => 'required|string|max:200',
    'shipping.line2'        => 'nullable|string|max:200',
    'shipping.city'         => 'required|string|max:100',
    'shipping.zip'          => 'required|digits_between:4,10',
    'shipping.country_code' => 'required|alpha|max:2|uppercase',

    // Позиції — 1..50
    'items'                       => 'required|array|list|min_items:1|max_items:50',
    'items.*.product_id'          => 'required|uuid',
    'items.*.qty'                 => 'required|integer|min:1|max:999',
    'items.*.unit_price'          => 'required|numeric|min:0',
    'items.*.promotions'          => 'nullable|array|list|max_items:5',
    'items.*.promotions.*'        => 'string|max:50',

    // Оплата
    'payment.method'         => 'required|in:card,paypal,bank_transfer',
    'payment.token'          => 'required_if:payment.method,card|string',
    'payment.paypal_email'   => 'required_if:payment.method,paypal|email',
    'payment.bank_reference' => 'required_if:payment.method,bank_transfer|string|max:100',
    'payment.save_card'      => 'prohibited_unless:payment.method,card|boolean',
]);

#14. Локалізовані повідомлення про помилки

Передайте Translator для виводу не англійською:

use Lift\Translation\Translator;

// Глобальне значення за замовчуванням
Validator::setTranslator(new Translator('ru'));

// Або на екземпляр
$v = new Validator($data, $rules, [], new Translator('fr'));

Файл перекладів використовує ключі повідомлень на кшталт validation.required, validation.email тощо. Формат див. у Локалізації.

#15. ValidationException — програмне використання

Коли потрібно провалити валідацію ззовні валідатора (наприклад, після запиту до БД):

use Lift\Validation\ValidationException;

throw ValidationException::withErrors([
    'email' => ['This email is already registered.'],
]);

Обробник помилок Lift перетворює його на HTTP 422 так само, як будь-яку іншу невдачу валідації. Щоб перехопити й оглянути його:

try {
    $data = $v->validated();
} catch (ValidationException $e) {
    $errors = $e->errors();   // ['field' => ['msg', …], …]
}

#Часті підводні камені

#Шпаргалка

// Найчастіше: однорядковий код усередині обробника
$data = $req->validate([
    'email' => 'required|email',
    'age'   => 'integer|min:13',
]);

// Окремо
$v = new Validator($input, $rules, $customMessages = []);
$v->passes() / $v->fails() / $v->errors() / $v->validated();

// Власне правило
final class FooRule implements RuleInterface { … }
Validator::extend('foo', new FooRule());

// Викинути своє
throw ValidationException::withErrors(['email' => ['already taken']]);

Кеш →