alexgarrett / violin
Violin is an easy to use, highly customisable PHP validator.
Installs: 65 619
Dependents: 4
Suggesters: 0
Security: 0
Stars: 206
Watchers: 20
Forks: 50
Open Issues: 27
Requires
- php: >=5.4
Requires (Dev)
- phpunit/phpunit: ~4.5
- squizlabs/php_codesniffer: 2.1.*
README
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', 'required'], 'age' => [20, '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', '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.', ] ]);
Using Field Aliases
Field Aliases helps you format any error messages without showing weird form names or the need to create a custom error.
$v->validate([ 'username_box|Username' => ['' => 'required'] ]); // Error output: "Username is required."
Callbacks
Violin allows you to attach callbacks to be run before or after any validation. This might be useful if you need to do some further validation, or maybe raise an event. You can add as many before and after callbacks as you want, and you can also use the current Violin instance within them.
Examples:
$v->before(function($violin) { // This will happen before the validation.. });
$v->after(function($violin) { // This will happen after the validation.. });
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', '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.
alnum
If the value is alphanumeric.
alnumDash
If the value is alphanumeric. Dashes and underscores are permitted.
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.
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.
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.
ip
If the value is a valid IP address.
min(int, [number])
Check if string length is greater than or equal to given int
. To check the size of a number, pass the optional number
option.
$v->validate([ 'username' => ['billy', 'required|min(3)|max(20)'], 'age' => ['20', 'required|min(18, number)|max(100, number)'] ]);
max(int, [number])
Check if string length is less than or equal to given int
. To check the size of a number, pass the optional number
option.
required
If the value is present.
url
If the value is formatted as a valid URL.
matches(field)
Checks if one given input matches the other. For example, checking if password matches password_confirm.
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, 'required|date'] ]);
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.
regex(expression)
If the given input has a match for the regular expression given.
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.