jridgewell/form-validator

A simple HTML form validator

v1.1.2 2013-06-26 03:46 UTC

README

FormValidator allows you to create and validate forms using a simple rule based approach. It uses an API very similar to Rails' ActiveRecord.

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

test.form.php (the model)

<?php
    use \FormValidator\Form;
    use \FormValidator\Validation;

    class TestForm extends \FormValidator\Form {
        public function __construct() {
            $this->validations = array( // Contains a hash array of form elements
                "name" => Validation::presence() // name field must contain something
            );
        }
    }
?>

index.php (the controller)

<?php
    require_once('test.form.php')
    $form = new TestForm();

    /* Checks if the form has submitted then the form is checked for validation against the rules contained
       within the $validations array of TestForm returning the validated data if its successful
     */

    if($form->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');
    }
?>

form.html.php (the view)

    <form name='input' method='POST'>
    <?php $form->error('name', 'There was an error'); ?>

    Please Enter your name: <?php $form->input('name'); ?><br/>
    <?php $form->submit('Submit');?>
    </form>
About the View
  1. 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)
  2. 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.

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.

<?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:

<?php
    <form name='input' method='POST'>
    <?php $form->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.

<?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()

No options

This field is always valid

Validation::acceptance()

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)

Validation::email()

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

Validation::length()

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 (<=) $x 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

Validation::numericality()

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

Validation::presence()

message => 'message' Use a custom error message

This field must not be empty

Validation::url()

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

Advanced Validations (require parameters)

Validation Parameter Options Description

Validation::confirmation($func)

$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.

Validation::exclusion($array)

$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.

Validation::format($regex)

$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

Validation::inclusion($array)

$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.

Validation::validateWith($func)

/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

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'
                ))
            );
        }
    }
?>
Validation::format($regex)
<?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.

<?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');
                })
            );
        }
    }
?>