Edit

Валідація даних

При валідації даних валідатор послідовно застосовує до значення поля задані правила, при виникненні помилки в масив даних про помилки додається запис і подальша обробка форми припиняється.

Валідація вважається пройденою, якщо в масиві даних про помилки відсутні записи.

Правила валідації

Список правил задається у вигляді масиву. Ключем є ім'я поля, а значенням - масив правил валідації. Правило валідації є методом класу-валідатора. У масиві правил ключем є ім'я правила (назва методу валідації), значенням може бути або рядок з повідомленням про помилку валідації правила, або ж масив з описом. У цьому масиві в ключі params задаються необхідні для валідації значення, а в ключі message задається рядок з повідомленням про помилку.

Можна також використовувати заперечення правил, якщо додати перед ім'ям правила знак оклику:"!numeric " - поле пройде валідацію, якщо його значення не є числом.

Якщо потрібно реалізувати перевірку тільки заповнених полів, то перед ім'ям поля в списку правил потрібно додати знак оклику. У цьому випадку якщо значення поля порожнє, правила будуть проігноровані.

{
    "ім'я поля 1": {
        "правило 1" : "повідомлення про помилку",
        "правило 2" : "повідомлення про помилку"
    },
    "ім'я поля 2": {
        "правило 1" : "повідомлення про помилку",
        "правило 2" : {
            "params" : значення,
            "message" : "повідомлення про помилку"
        }
    },
    "!ім'я поля 3":{
        "правило 1" : "повідомлення про помилку"
    }
}

Стандартним класом валідації (\FormLister\Validator) передбачені правила:

required: поле заповнене;
date: значення поля є датою в заданому форматі;
min: значення поля більше заданого або дорівнює йому;
max: значення поля менше заданого або дорівнює йому;
greater: значення поля строго менше заданого;
less: значення поля строго більше заданого;
between: значення поля входить в діапазон;
equals: значення поля рівне заданому;
in: значення поля входить в заданий масив значень;
alpha: значення поля містить тільки літери;
numeric: значення поля містить тільки цифри;
alphaNumeric: значення поля містить тільки літери і цифри;
slug: значення поля є частиною url;
decimal: значення поля є десятковим числом;
phone: значення поля є номером телефону;
matches: значення поля задовольняє регулярному виразу;
url: значення поля є посиланням;
email: значення поля є email-адресою;
length: довжина значення поля дорівнює заданому;
minLength: довжина значення поля більше заданого або дорівнює йому;
maxLength: довжина значення поля менше заданого або дорівнює йому;
lengthBetween: довжина значення поля входить в діапазон;
minCount: розмір масиву більше заданого;
maxCount: розмір масиву менше заданого;
countBetween: розмір масиву входить в діапазон.

Якщо потрібно задати два значення для правила, то їх слід задавати як масив:

&rules=`{
    "field" : {
        "lengthBetween" : {
            "params" : [10,20],
            "message" : "Довжина повинна бути від 10 до 20"
        }
    }
}`

Для правила in (і інших правил, що використовують масив) масив значень слід задавати наступним чином:

&rules=`{
    "field" : {
        "in" : {
            "params" : [ [10,20,30] ],
            "message" : "Значення поля field має дорівнювати 10, 20 або 30"
        }
    }
}`

Це потрібно, щоб масив був переданий в функцію одним аргументом.

Передбачена також можливість використовувати для валідації функції або статичні методи завантаженого класу:

&rules=`{
    "myfield":{
        "required":"Required field",
        "custom":{
            "function":"\\Namespace\\Classname::myCustomRule",
            "params":[10,20,30],
            "message":"Custom check failed"
        }
    }
}`

Метод повинен приймати першим аргументом екземпляр контролера з якого викликається правило, другим аргументом - значення перевіряємого поля, далі - параметри які передаються в ключі опису params:

public static function myCustomRule($fl,$value,$a,$b,$c) {
    $result = $fl->getField('field1') == $a && $fl->getField('field2') == $b && $value == $c;
    return $result;
}

У прикладі правило буде пройдено, якщо значення поля field1 = 10, значення поля field2 = 20, а значення поля, до которму застосовується правило, = 30.

Метод повинен повернути true, false або текст повідомлення про помилку (в цьому випадку можна не вказувати message в списку правил).

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

Приклад сніпета з функцією для перевірки чи є в перевіряємом полі посилання, і якщо є то повертаємо помилку:

<?php
function checkUrls($fl,$value) {
    $pattern = '~[a-z]+://\S+~';
    if($num_found = preg_match_all($pattern, $value, $out) > 0) {
        // Посилання є, не важливо скільки, повернення помилки
        return false;
    }

    // Посилань немає, валідація пройшла успішно
    return true;
}

У прикладі використовується назва правила "сustom", але можна використовувати будь-яку назву правила, якого немає в класі валідації. Таким чином можна використовувати кілька правил даного типу.

Результати валідації

Дані про помилки зберігаються у вигляді масиву і можуть бути отримані викликом методу getFormData('errors'):

{
    "ім'я поля 1": {
        "ім'я порушеного правила" : "повідомлення про помилку"
    },
    "ім'я поля 2": {
        "ім'я порушеного правила" : "повідомлення про помилку"
    }
}

Для додавання даних в цей масив використовується метод addError (ім'я поля, ім'я правила, повідомлення про помилку). Таким чином, можна впливати на підсумковий результат валідації, вручну додаючи записи в цей масив. Можна також оголосити валідацію непройденной за замовчуванням, викликавши метод setValid (false).

У шаблонах результати валідації для кожного поля виводяться за допомогою плейсхолдера [+ім'я поля.error+]. Загальний результат може бути виведений в плейсхолдер [+form.messages+], який задається шаблоном messagesTpl. У свою чергу, в цьому шаблоні можна використовувати плейсхолдери:

[+required+] - повідомлення про незаповнені поля;
[+ errors +] - повідомлення про невірно заповнені поля.

Отримати повідомлення про помилки для певного поля можна за допомогою методу getErrorMessage (ім'я поля).