FormValidator allows you to create and validate forms using a simple
rule based approach. It uses an API very similar to Rails' ActiveRecord., (*1)
Basics
A form file is just a class that extends the \FormValidator\Form class
In this example, the form validator checks if name
isn't empty, (*2)
validations = array( // Contains a hash array of form elements
"name" => Validation::presence() // name field must contain something
);
}
}
?>
index.php (the controller)
hasPosted() && ($data = $form->validate())) {
// Form passes validation, use the $data for validated POST data
} else {
// Form hasn't posted or hasn't passed validation, so we load our html file
require_once('form.html.php');
}
?>
About the View
- If the form fails validation, by using the
$form->input
method, we
preserve whatever value the user typed into that field (except for
password fields)
- The form must have a field with the name attribute set to the
name of the form class (
name="TestForm"
in our example). Using the
$form->submit
method takes care of this requirement.
Installation
Via Composer
composer require "jridgewell/form-validator:1.*"
Then just add require 'vendor/autoload.php';
to any code that requires
FormValidator., (*3)
The Validations Array
The $validations
array contains all the form fields and rules that
need to pass, for the form to be valid. In the example above, it showed
a single rule applying to one form element, but you can apply multiple
rules to an element by using an array., (*4)
<?php
class TestForm extends Form{
public function __construct() {
$this->validations = array(
'name' => Validation::presence(),
'age' => array( //Specifiy multiple rules
Validation::presence(),
Validation::numericality()
)
);
}
}
?>
In our html file, if we wanted to show the errors for the validations,
we could do the following:, (*5)
error('name', 'There was an error'); ?>
Please Enter your name: <?php $form->input('name'); ?><br/>
<?php $form->error('age', 'This is an optional custom message about age'); ?>
Please Enter your age: <?php $form->input('age'); ?><br/>
<?php $form->submit('Submit');?>
</form>
?>
Validation Array Options
Most validations also support passing in an options array. This allows
for custom messages, and can allow for a field to be optional (blank).
Please see the validation for acceptable parameters., (*6)
<?php
class TestForm extends Form {
public function __construct() {
$this->validations = array(
'name' => Validation::length(array(
'minimum' => 0,
'maximum' => 100
)),
'age' => Validation::numericality(array(
'optional' => true,
'only_integer' => true
)),
'username' => Validation::exclusion(array(
'admin',
'superuser'
), array(
'message' => 'You are not our master!'
))
);
}
}
?>
List of validations
Simple Validations
Validation |
Options |
Description |
Validation::anything(), (*7) |
No options, (*8) |
This field is always valid, (*9) |
Validation::acceptance(), (*10)
|
- message => 'message'
- Use a custom error message
- accept => 'truthy'
- The value that this field will be compared (==)
with. Defaults to true
|
This field must be accepted (truthy), (*11) |
Validation::email(), (*12) |
- message => 'message'
- Use a custom error message
- optional => true
- Will accept a blank field. If this field is not
blank, will preform the validations.
|
This field must be a valid email, (*13) |
Validation::length(), (*14) |
- message => 'message'
- Use a custom error message
- optional => true
- Will accept a blank field. If this field is not
blank, will preform the validations.
- is => $x
- The length of this field must be equal to $x
- minimum => $x
- The length of this field must be at least (
- maximum => $x
- The length of this field must be at most (>=) $x
|
This field's number of characters must be in the supplied
range. If no options are passed, this field will always be valid, (*15)
|
Validation::numericality(), (*16) |
- message => 'message'
- Use a custom error message
- optional => true
- Will accept a blank field. If this field is not
blank, will preform the validations.
- only_integer => true
- Only whole integers are acceptable. If not
supplied, whole integers or floats are acceptable.
- even => true
- Only even numbers are acceptable
- odd => true
- Only odd numbers are acceptable
- equal_to => $x
- The number must be equal to $x
- less_than => $x
- The number must be less than $x
- less_than_or_equal_to => $x
- The number must be less than or equal to $x
- greater_than => $x
- The number must be greater than $x
- greater_than_or_equal_to => $x
- The number must be greater than or equal to $x
|
This field must be a number, (*17) |
Validation::presence(), (*18) |
- message => 'message'
- Use a custom error message
|
This field must not be empty, (*19) |
Validation::url(), (*20)
|
- message => 'message'
- Use a custom error message
- optional => true
- Will accept a blank field. If this field is not
blank, will preform the validations.
|
This field must be a valid url, (*21) |
Advanced Validations (require parameters)
Validation |
Parameter |
Options |
Description |
Validation::confirmation($func), (*22) |
- $func
- A (callable) callback to match against. It's
return value will be type and value checked
(===) against this field
|
- message => 'message'
- Use a custom error message
- optional => true
- Will accept a blank field. If this field is not
blank, will preform the validations.
|
This field must match the return value of $other_field_func.
Useful for confirming a password in a second field., (*23) |
Validation::exclusion($array), (*24) |
- $array
- A list of unacceptable values.
|
- message => 'message'
- Use a custom error message
- optional => true
- Will accept a blank field. If this field is not
blank, will preform the validations.
|
This field must not be equal (==) to a value inside
$array., (*25)
|
Validation::format($regex), (*26) |
- $regex
- The regex to match this field against
|
- message => 'message'
- Use a custom error message
- optional => true
- Will accept a blank field. If this field is not
blank, will preform the validations.
|
This field must match against the supplied $regex, (*27) |
Validation::inclusion($array), (*28) |
- $array
- A list of acceptable values.
|
- message => 'message'
- Use a custom error message
- optional => true
- Will accept a blank field. If this field is not
blank, will preform the validations.
|
This field must be equal (==) to a value inside
$array., (*29) |
Validation::validateWith($func), (*30)
/td>
|
- $func
- A custom (callable) callback to match against.
|
- message => 'message'
- Use a custom error message
- optional => true
- Will accept a blank field. If this field is not
blank, will preform the validations.
|
This validation allows for a custom function to preform the
field validation. It's return value must be (===) true, or else
it will use the return value as the field's error message, (*31) |
Advanced Validation Examples
Validation::confirmation($other_field_func)
<?php
// TestForm.php
class TestForm extends Form{
public function __construct() {
$this->validations = array(
'password' => Validation::confirmation(function() {
return $_POST['password_confirmation'];
})
);
}
}
?>
Validation::exclusion($array)
<?php
// TestForm.php
class TestForm extends Form{
public function __construct() {
$this->validations = array(
'usernames' => Validation::exclusion(array(
'admin',
'superuser'
))
);
}
}
?>
<?php
// TestForm.php
class TestForm extends Form{
public function __construct() {
$this->validations = array(
'mp3Url' => Validation::format('/\.mp3$/')
);
}
}
?>
Validation::inclusion($array)
<?php
class TestForm extends Form{
public function __construct() {
$this->validations = array(
'usernames' => Validation::inclusion(array(
'Matt',
'Thor',
'Asa'
))
);
}
}
?>
Validation::validateWith($func)
This validation requires a (callable) callback. This callback is
then provided with the submitted field data as it's only parameter. The
callback can either return true
and the validation will pass, or
return anything else and the return will be used as the error message
for the field., (*32)
<?php
class TestForm extends Form {
public function __construct() {
$this->validations = array(
'checkCustom' => Validation::validateWith(function($val) {
if ($val === 'supahSecret') {
return true;
}
return (substr($val, 0, 2) == 'st');
})
);
}
}
?>