gajus/vlad

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.

0.3.3 2014-12-04 03:47 UTC

This package is not auto-updated.

Last update: 2024-03-25 23:41:44 UTC


README

Build Status Coverage Status Latest Stable Version

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

Validator Description
String Validate that input is a string.
Regex Validate that input is matched using a regular expression.
Date Validates that string can be parsed using a date format.
RangeMinInclusive Validate that a numeric input is at least of the given size (inclusive).
RangeMinExclusive Validate that a numeric input is at least of the given size (exclusive).
RangeMaxInclusive Validate that a numeric input is at most of the given size (inclusive).
RangeMaxExclusive Validate that a numeric input is at most of the given size (exclusive).
NotEmpty Validate that input value is not empty.
Length Validate that input string representation is of a specific length.
Integer Validate that input is an integer.
LengthMin Validate that input string representation is not shorter than the specified length.
LengthMax Validate that input string representation is not longer than the specified length.
In Validate that input value is in the haystack.
Email Validate that input value is syntactically valid email address.

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

Alternatives