library carbon-validator

htmlburger/carbon-validator

Basic Validator class implemented as a stand alone library. Inspired by Laravel Validation module.

TLDR;

PHP библиотека за валидиране на входни данни., _(*1)

 'required',
    'email'   => 'required|email',
    'message' => 'string_min_length:15|string_max_length:255'
));

if ($validator->fails()) {
    $errors = $validator->get_errors();
} else {
    send_mail_notification();
    header('Location: ?success');
}
?>

1. Създаваме нов обект като подаваме входните данни и правилата според които трябва да се валидират тези данни
   1. Входните данни трябва да бъдат асоциативен масив подобен на $_POST
   2. Правилата за валидация са отново асоциативен масив в който ключа е името на полето а стойността: всички правила, които се отнасят към него
2. Можем да проверим дали данните са валидни като извикаме метода $validator->fails() или $validator->passes()
3. Можем да извлечем автоматично генериран списък от грешки от валидатора чрез $validator->get_errors()
4. Можем да подаваме специфични грешки за определени полета и правила(пример по-долу)

Дефиниция на правилата

Всяко поле се асоциира с набор от валидационни правила. Той може да бъде пуснат под формата на string или масив. Когато правилата се подават като стринг те се разделят от символа pipe(|) по следния начин:, _(*2)

<?php
$validator = new Carbon_Validator($_POST, array(
    // The "customer_email" field is required and must be valid email
    'customer_email' => 'required|email' 
));
?>

Когато се подават като масив той трябва да е числово индексиран по следния начин:, _(*3)

<?php
$validator = new Carbon_Validator($_POST, array(
    'email' => array('required', 'email')
));
?>

Всяко правило само по себе си се състои от:, _(*4)

1. Име(например string_min_length)
2. Аргумент разделен от името с двуеточие(например :15 от string_min_length:15)

Налични правила за валидиране

Carbon_Validator идва с няколко пакето от валидационни правила. За да заредите пакет се използва следния статичен метод:, _(*5)

Carbon_Validator::load_package('wordpress');

Пакет generic (зарежда се по подразбиране): * required - полето трябва да има някаква стойност * in:value1,value2,value3,... - полето трябва да има една от стойностите подадени като параметри на правилото * email - валиден email адрес (зад кулисите се използва функцията filter_var на PHP) * regex:/regex_body/i - валидира стойността на полето с подадения регулярен израз * numeric - прекарва стойността през вградената в PHP is_numeric функция * string_min_length:value - указва минимална дължина на полето * string_max_length:value - указва максимална дължина на полето * numeric_min:value - указва минимална числова стойност на полето * numeric_max:value - указва максимална числова стойност на полето * url - валиден URL адрес(зад кулисите се използва функцията filter_var на PHP) * file:ext,ext2 - уверява се че е качен файл с опеделен тип. Не се прави проверка на самия extension на файа, а на MIME типа му * filesize:2M - уверява се че е качен файл под определен размер(2MB). Приемат се и размери със суфикс K(от KB) * email_exists - проверява дали вече съществува потребител с този email адрес * user_exists - проверява дали вече съществува потребител с този username, _(*6)

Пакет wordpress: * wp_nonce:action_name - Валидира полето чрез wp_verify_nonce() * wp_post:post_type1,post_type2 - Валидира ID на пост чрез get_post(). По избор можете да добавите 1 или повече пост типове като изискване за валидация на поста * wp_user:role_or_capability1,role_or_capability2 - Валидира ID на потребител чрез get_userdata(). По избор можете да добавите 1 или повече роли/възможности като изискване за валидация на потребителя, _(*7)

Store / Load

Имате възможност да запазвате инстанции на Carbon_Validator и да ги заредите по-късно., _(*8)

Carbon_Validator::store('some_id', $validator);

$validator = Carbon_Validator::load('some_id');

Example:

functions.php, _(*9)

 "required",
        "contact_email" => "required|email",
        "contact_message" => "required",
    ));

    // Store the validator, so we can use it in the front-end
    Carbon_Validator::store('contact_form' , $validator);

    $success = $validator->passes();

    if ($success) {
        // Send email notification, or whatever. 
    }
}
?>

templates/contact.php, _(*10)

    <?php if ($validator->passes()): ?>
        <p class="alert alert-success"><?php _e('Your message has been sent.', 'crb'); ?></p> 
    <?php elseif ($errors = $validator->get_errors()): ?>
        <div class="alert alert-danger">
            <ul>
                <?php foreach ($errors as $error): ?>
                    <li><?php echo esc_html($error) ?></li>
                <?php endforeach ?>
            </ul>
        </div>
     <?php endif ?>

Custom Error Messages

Автоматично генерираните валидационни грешки вършат работа в повечето ситуации. Понякога обаче се налага да се добавят и custom error messages. Това се прави чрез 3ти аргумент на конструктора на класа Validator:, _(*11)

 'required',
    'email'   => 'required|email',
    'message' => 'string_min_length:15|string_max_length:255'
);

$error_messages = array(
    'name.required' => 'We need your full name in order to contact you later. ',
    'message.string_min_length' => 'Your message is too short -- please enter more than 15 characters. ',
    'message.string_max_length' => 'Your message is too long -- please enter less than 255 characters. '
);

$validator = new Carbon_Validator($_POST, $rules, $error_messages);
?>

Global default error messages

За да добавите или презапишете едно съобщение за всички инстанции на Carbon_Validator, можете да използвате следния статичен метод:, _(*12)

// Carbon_Validator::register_default_error_message($rule, $message);
Carbon_Validator::register_default_error_message('required', 'You should really fill out the "%1$s" field.');

Ако го използвате, %1$s ще бъде заместено с user-friendly име на полето, което се валидира., _(*13)

Този метод също ви позволява да преминете дадено съобщение през функция за превеждане ( __(), _е() и т.н. в WordPress), _(*14)

Custom Validation Rules

Вградените правила не винаги са достатъчни. Когато трябва да се направи по-специфична валидация можем да напраим следното:, _(*15)

 "John Doe",
#   "ip-address" => "192.168.2.54",
# );

$rules = array(
    'ip-address' => 'required|internal_ip',
);

$messages = array(
    'ip-address.internal_ip' => 'Please enter valid internal IP addres. ',
);

$validator = new Carbon_Validator($_POST, $rules, $messages);
?>

Разширяването става чрез статичния метод Carbon_Validator::extend($rule_name, $callback). След разширяване, $rule_name може да се ползва във валидационните правила на формите., _(*16)

Самите грешки могат да се се предават към Carbon_Validator класа чрез хвърляне на специално изключение Carbon_Validator_ValidationError., _(*17)

Custom Validation Rule Callback

Параметрите, които се подават на callback-а са:, _(*18)

function my_custom_validation_rule_callback($value, $parameters, $field, $validator_instance) { };

1. $value - стойността, която трябва да се валидира
2. $parameters - масив от стойности подадени като параметри за правилото (в списък разделен със запетаи)
3. $field - полето, което се валидира
4. $validator_instance - референция към инстанцията на валидатора, която вика този callback

Валидиране на файлове

 Carbon_FileUpload::make($_FILES['avatar'])
));

$validator = new Carbon_Validator($data, array(
    'name' => 'required',
    'email' => 'required|email',
    'message' => 'required',
    'avatar' => 'file:jpg|filesize:1M',
));

?>

Наличните разширения за валидиране на файлове могат да бъдат отркти във validator/mime-types.php., _(*19)

Валидиране на масиви

Когато имате масиви в $_POST можете да валидирате определен елемент на като използвате квадратни скоби за да опишете до него по следния начин:, _(*20)

 array(
        'first_name' => 'John',
        'last_name' => 'Doe',
        'email' => 'johndoe@example.com',
        'address' => array(
            'street' => array(
                'number' => "123"
            )
        )
    )
);
$validator = new Carbon_Validator($input, array(
    'user[first_name]' => 'required',
    'user[last_name]' => 'required|string_min_length:2',
    'user[email]' => 'email',
    'user[address][street][number]' => 'required',
));

var_dump($validator->passes());
?>

Дизайна на класа е взаимстван от библиотеката Laravel., _(*21)