README

Input validation library, that has inbuilt error messages that are translatable, validators that are easy to extend, and that has easy to understand test declaration syntax.

Succinct Test Declaration

Test is composed of assertions about the input.

/**
 * @param Gajus\Vlad\Translator $translator
 */
$test = new \Gajus\Vlad\Test();

/**
 * Add an assertion to the test.
 *
 * @param string $selector_name
 * @return Gajus\Vlad\Assertion
 */
$assertion = $test->assert('user[first_name]');

/**
 * @param string $validator_name
 * @param array $validator_options
 * @param array $condition_options
 * @return Gajus\Vlad\Assertion
 */
$assertion->is('NotEmpty');
$assertion->is('String');
$assertion->is('LengthMin', ['length' => 5]);
$assertion->is('LengthMax', ['length' => 20]);

// In practise, assertion is declared using chaining:
$test
    ->assert('user[last_name]')
    ->is('NotEmpty')
    ->is('String')
    ->is('LengthMin', ['length' => 5])
    ->is('LengthMax', ['length' => 20]);

/**
 * @param array $source
 * @param string $selector_name
 * @return array Errors.
 */
$assessment = $test->assess($_POST);

if ($assessment) {
    // Iterate through error messages.
    foreach ($assessment as $error) {
        // [..]
    }
}

Limit the Assessment Scope

Note that assertions are done against selector name, not the actual value. You can limit test to specific assertions at the time of the assessment:

/**
 * @param string $selector_name
 * @param mixed $value
 * @return string Error.
 */
$error = $test->assertion('user[first_name]', $_POST);

Extendable Validation Rules

Vlad has inbuilt validators. It is easy to write custom validators. You can request new validators to be added to the core package. Validators benefit from the translator interface.

Vlad does not encourage inline boolean validation expressions.

Inbuilt Validation Rules

Writing a Custom Validator

Each validator is a class that extends Gajus\Vlad\Validator. Validators that are not part of the Vlad package must be under a namespace.

<?php
namespace Foo\Bar;

class HexColor extends \Gajus\Vlad\Validator {
    static protected
        // Each option must be predefined with default value.
        $default_options = [
            'trim' => false
        ],
        $message = '{input.name} is not a hexadecimal number.';
    
    public function assess ($value) {
        $options = $this->getOptions();

        if ($options['trim']) {
            $value = ltrim($value, '#');
        }

        return ctype_xdigit($value) && (strlen($value) == 6 || strlen($value) == 3);
    }
}

In the test declaration, custom validator is referred to using the full (namespaced) class name.

$test = new \Gajus\Vlad\Test();
$test
    ->assert('foo_bar')
    ->is('Foo\Bar\HexColor');

$assessment = $test->assess(['foo_bar' => 'fff']);

Multilingual

Translator allows to overwrite default error messages and give input names.

In addition to the provided (below) use cases of the translator, you can extend Gajus\Vlad\Translator with your own functionality (e.g. importing translations from a file or database).

Input name

In most cases, you do not need to provide input name at all. Vlad will derive English name from the selector, e.g. foo[bar_tar_id] will come out as "Foo Bar Tar".

You can translate input names.

$translator = new \Gajus\Vlad\Translator();
$translator->setInputName('foo[bar_tar_id]', 'Bar Tar');

$test = new \Gajus\Vlad\Test();
$test
    ->assert('foo_bar')
    ->is('NotEmpty');

$assessment = $test->assess([]);

The above will produce the following error message:

Bar Tar is empty.

Validator Message

Validators have inbuilt English error messages. You can overwrite them like this:

$translator = new \Gajus\Vlad\Translator();
$translator->setValidatorMessage('NotEmpty', '{input.name} cannot be left empty.');

$test = new \Gajus\Vlad\Test($translator);
$test
    ->assert('foo_bar')
    ->is('NotEmpty');

$assessment = $test->assess([]);

Foo Bar cannot be left empty.

Assertion Error Message

Individual assertions can overwrite the error messages.

$test = new \Gajus\Vlad\Test();
$test
    ->assert('foo_bar')
    ->is('NotEmpty', null, ['message' => 'You must provide Foo Bar value.']);

Installation

Vlad uses Composer to install and update:

curl -s http://getcomposer.org/installer | php
php composer.phar require gajus/vlad

Todo

Documentation.
Add URL validator. This should consider that URL does not necessarily include protocol and that those that do include, e.g. ftp:// might not necessarily be expected URLs.
Improve email validator. Zend validator includes useful additions (MX check, host name validator, etc) https://github.com/zendframework/zf2/blob/master/library/Zend/Validator/EmailAddress.php.

gajus / vlad

Maintainers

Details