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

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.

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

Advanced Validations (require parameters)

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

jridgewell / form-validator

Maintainers

Details