violin

Violin is an easy to use, highly customisable PHP validator.

Note: This package is under heavy development and is not recommended for production.

Installing

Install using Composer.

{
    "require": {
        "alexgarrett/violin": "2.*"
    }
}

Basic usage

use Violin\Violin;

$v = new Violin;

$v->validate([
    'name'  => 'billy',
    'age'   => 20
], [
    'name'  => 'required',
    'age'   => 'required|int'
]);

if($v->passes()) {
    echo 'Validation passed, woo!';
} else {
    echo '<pre>', var_dump($v->errors()->all()), '</pre>';
}

Adding custom rules

Adding custom rules is simple. If the closure returns false, the rule fails.

$v->addRuleMessage('isbanana', 'The {field} field expects "banana", found "{value}" instead.');

$v->addRule('isbanana', function($value, $input, $args) {
    return $value === 'banana';
});

$v->validate([
    'fruit' => 'apple'
], [
    'fruit' => 'isbanana'
]);

Adding custom error messages

You can add rule messages, or field messages for total flexibility.

Adding a rule message

$v->addRuleMessage('required', 'You better fill in the {field} field, or else.');

Adding rule messages in bulk

$v->addRuleMessages([
    'required' => 'You better fill in the {field} field, or else.',
    'int'      => 'The {field} needs to be an integer, but I found {value}.',
]);

Adding a field message

Any field messages you add are used before any default or custom rule messages.

$v->addFieldMessage('username', 'required', 'You need to enter a username to sign up.');

Adding field messages in bulk

$v->addFieldMessages([
    'username' => [
        'required' => 'You need to enter a username to sign up.'
    ],
    'age' => [
        'required' => 'I need your age.',
        'int'      => 'Your age needs to be an integer.',
    ]
]);

Extending Violin

You can extend the Violin class to add custom rules, rule messages and field messages. This way, you can keep a tidy class to handle custom validation if you have any dependencies, like a database connection or language files.

class MyValidator extends Violin
{
    protected $db;

    public function __construct(PDO $db)
    {
        $this->db = $db;
        
        // Add rule message for custom rule method.
        $this->addRuleMessage('uniqueUsername', 'That username is taken.');
    }
    
    // Custom rule method for checking a unique username in our database.
    // Just prepend custom rules with validate_
    public function validate_uniqueUsername($value, $input, $args)
    {
        $user = $this->db->prepare("
            SELECT count(*) as count
            FROM users
            WHERE username = :username
        ");

        $user->execute(['username' => $value]);

        if($user->fetchObject()->count) {
            return false; // Username exists, so return false.
        }

        return true;
    }
}

// A database connection.
$db = new PDO('mysql:host=127.0.0.1;dbname=website', 'root', 'root');

// Instantiate your custom class with dependencies.
$v = new MyValidator($db);

$v->validate([
    'username' => 'billy'
], [
    'username' => 'required|uniqueUsername'
]);

Rules

This list of rules are in progress. Of course, you can always contribute to the project if you'd like to add more to the base ruleset.

alnumDash

If the value is alphanumeric. Dashes and underscores are permitted.

alnum

If the value is alphanumeric.

alpha

If the value is alphabetic letters only.

array

If the value is an array.

between(int, int)

Checks if the value is within the intervals defined. This check is inclusive, so 5 is between 5 and 10.

bool

If the value is a boolean.

checked

If a field has been 'checked' or not, meaning it contains one of the following values: 'yes', 'on', '1', 1, true, or 'true'. This can be used for determining if an HTML checkbox has been checked.

date

If the given input is a valid date.

You can validate human readable dates like '25th October 1961' and instances of DateTime. For example:

$twoDaysAgo = new DateTime('2 days ago');
$date = $twoDaysAgo->format('d M Y');

$v->validate([
    'date' => $date
], [
    'date' => 'required|date'
]);

different(field)

Checks if one given input is different to the other.

email

If the value is a valid email.

int

If the value is an integer, including numbers within strings. 1 and '1' are both classed as integers.

ip

If the value is a valid IP address.

matches(field)

Checks if one given input matches the other. For example, checking if password matches password_confirm.

max(int/string)

Checks if the value is less than or equal to the given parameter. If the value is a string, this will check if the length of the string in characters is less than or equal to the given parameter.

min(int/string)

Checks if the value is greater than or equal to the given parameter. If the value is a string, this will check if the length of the string in characters is greater than or equal to the given parameter.

number

If the value is a number, including numbers within strings.

Numeric strings consist of optional sign, any number of digits, optional decimal part and optional exponential part. Thus +0123.45e6 is a valid numeric value. Hexadecimal (e.g. 0xf4c3b00c), Binary (e.g. 0b10100111001), Octal (e.g. 0777) notation is allowed too but only without sign, decimal and exponential part.

regex(expression)

If the given input has a match for the regular expression given.

required

If the value is present.

url

If the value is formatted as a valid URL.

Contributing

Please file issues under GitHub, or submit a pull request if you'd like to directly contribute.

Running tests

Tests are run with phpunit. Run ./vendor/bin/phpunit to run tests.

kezadias / violin