README

PHPixie Validation library

Most PHP validation libraries share a large flaw - they only work with flat arrays and are mostly targeting form validation. This approach is irredeemably outdated, as when developing APIs and RESTful services we frequently have to work with request documents with complex structures. PHPixie Validate is designed to provide an easy approach to validating those. It requires no dependencies, so even if you are not using PHPixie it can still come in handy in your project.

Let's start with an easy flat array example first:

$validate = new \PHPixie\Validate();

//Or if you are using PHPixie
$validate = $builder->components()->validate();

// The data we will be validating
$data = array(
    'name' => 'Pixie',
    'home' => 'Oak',
    'age'  => 200,
    'type' => 'fairy'
);

// There are multiple syntaxes supported
// for building a validator
// The standard approach

$validator = $validate->validator();

// A flat file is just a document
$document = $validator->rule()->addDocument();

// A required field with filters
$document->valueField('name')
    ->required()
    ->addFilter()
        ->alpha()
        ->minLength(3)
        
        // Add custom error message if this set of filters fails
        ->message('Name is too short')
        
        // Or define a custom error type
        ->customError('name_short', 'Name is too short');

// You can also add filters as array
$document->valueField('home')
    ->required()
    ->addFilter()
        ->filters(array(
            'alpha',
            'minLength' => array(3)
        ));
        
// Or a shorthand

$document->valueField('home')
    ->required()
    ->filter(array(
        'alpha',
        'minLength' => array(3)
    ), "Home must consist of letters and be longer than 3 characters");

// A shorthand approach
$document->valueField('age')
    ->required()
    
    // Define filter and message
    ->filter('numeric', 'Age must be a number');
    
// Pass your own callback
$document->valueField('type')
    ->required()
    
    // More flexible callback with
    // access to result object
    ->callback(function($result, $value) {
        if(!in_array($value, array('fairy', 'pixie'))) {
            
            // If is not valid add an error to the result
            $result->addMessageError("Type can be either 'fairy' or 'pixie'");
            
            //Or you can just return an error message to be added
            return "Type can be either 'fairy' or 'pixie'";
        }
    });

// By default validator will only allow
// fields that have rules attached to them
// If you wish to allow extra fields:
$document->allowExtraFields();

// Custom validator function
$validator->rule()->callback(function($result, $value) {
    if($value['type'] === 'fairy' && $value['home'] !== 'Oak') {
        $result->addMessageError("Fairies live only inside oaks");
    }
});

The full list of available filters can be found here. Every public method in these Registry classes is an available filter

You can also build the validator using an shorthand callback syntax:

$validator = $validate->validator(function($value) {
    $value->document(function($document) {
        $document
            ->allowExtraFields()
            ->field('name', function($name) {
                $name
                    ->required()
                    ->filter(function($filter) {
                        $filter
                            ->alpha()
                            ->minLength(3);
                    });
            })
            ->field('home', function($home) {
                $home
                    ->required()
                    ->filter(array(
                        'alpha',
                        'minLength' => array(3)
                    ));
            })
            ->field('age', function($age) {
                $age
                    ->required()
                    ->filter('numeric');
            })
            ->field('type', function($home) {
                $home
                    ->required()
                    ->callback(function($result, $value) {
                        if(!in_array($value, array('fairy', 'pixie'))) {
                            $result->addMessageError("Type can be either 'fairy' or 'pixie'");
                        }
                    });
            });
    })
    ->callback(function($result, $value) {
        if($value['type'] === 'fairy' && $value['home'] !== 'Oak') {
            $result->addMessageError("Fairies live only inside oaks");
        }
    });
});

Now let's try validating:

$result = $validator->validate($data);
var_dump($result->isValid());

// Add some errors
$data['name'] = 'Pi';
$data['home'] = 'Maple';
$result = $validator->validate($data);
var_dump($result->isValid());

// Print errors
foreach($result->errors() as $error) {
    echo $error."\n";
}
foreach($result->invalidFields() as $fieldResult) {
    echo $fieldResult->path().":\n";
    foreach($fieldResult->errors() as $error) {
        echo $error."\n";
    }
}

/*
bool(true)
bool(false)
Fairies live only inside oaks
name:
Value did not pass filter 'minLength'
*/

Working with results

As you can see above a Result object contains the errors appended to it and also results of all fields. It may see that errors are just strings, while in fact they are also classes that implement the magic __toString() method for debugging convenience. When working with forms you'll probably want to use your own error messages instead. To do this get the type and parameters information from the error class and format it accordingly, e.g. :

if($error->type() === 'filter') {
    if($error->filter() === 'minLength') {
       $params = $error->parameters();
       echo "Please enter at least {$params[0]} characters";
    }
}

This way with a simple helper class you can customize all errors for your users.

Data structures

Now let's try a structured example:

$data = array(
    'name' => 'Pixie',
    
    // 'home' is just a subdocument
    'home' => array(
        'location' => 'forest',
        'name'     => 'Oak'
    ),
    
    // 'spells' is an array of documents of a particular type
    // and a string key (also has to be validated)
    // of the same type
    'spells' => array(
        'charm' => array(
            'name' => 'Charm Person',
            'type' => 'illusion'
        ),
        'blast' => array(
            'name' => 'Fire Blast',
            'type' => 'evocation'
        ),
        // ....
    )
);

$validator = $validate->validator();
$document = $validator->rule()->addDocument();

$document->valueField('name')
    ->required()
    ->addFilter()
        ->alpha()
        ->minLength(3);

// Subdocument
$homeDocument = $document->valueField('home')
    ->required()
    ->addDocument();

$homeDocument->valueField('location')
    ->required()
    ->addFilter()
        ->in(array('forest', 'meadow'));

$homeDocument->valueField('name')
    ->required()
    ->addFilter()
        ->alpha();

// Array of subdocuments
$spellsArray = $document->valueField('spells')
    ->required()
    ->addArrayOf()
    ->minCount(1);

// Rule for the array key
$spellDocument = $spellsArray
    ->valueKey()
    ->filter('alpha');

// Rule for the array element
$spellDocument = $spellsArray
    ->valueItem()
    ->addDocument();

$spellDocument->valueField('name')
    ->required()
    ->addFilter()
        ->minLength(3);

$spellDocument->valueField('type')
    ->required()
    ->addFilter()
        ->alpha();

It looks much better with the alternative syntax, since it follows the structure of your data:

$validator = $validate->validator(function($value) {
    $value->document(function($document) {
        $document
            ->field('name', function($name) {
                $name
                    ->required()
                    ->filter(array(
                        'alpha',
                        'minLength' => array(3)
                    ));
            })
            ->field('home', function($home) {
                $home
                    ->required()
                    ->document(function($home) {
                        
                        $home->field('location', function($location) {
                            $location
                                ->required()
                                ->addFilter()
                                    ->in(array('forest', 'meadow'));
                            });
                        
                        $home->field('name', function($name) {
                            $name
                                ->required()
                                ->filter('alpha');
                        });
                    });
            })
            ->field('spells', function($spells) {
                $spells->required()->arrayOf(function($spells){
                    $spells
                        ->minCount(1)
                        ->key(function($key) {
                            $key->filter('alpha');
                        })
                        ->item(function($spell) {
                            $spell->required()->document(function($spell) {
                                $spell->field('name', function($name) {
                                    $name
                                        ->required()
                                        ->addFilter()
                                            ->minLength(3);
                                });
                                    
                                $spell->field('type', function($type) {
                                    $type
                                        ->required()
                                        ->filter('alpha');
                                });
                            });
                    });
                });
            });
    });
});

Now let's try using it:

$result = $validator->validate($data);

var_dump($result->isValid());
//bool(true)

// Add some errors
$data['name'] = '';
$data['spells']['charm']['name'] = '1';

// Invalid key (should be string)
$data['spells'][3] = $data['spells']['blast'];

$result = $validator->validate($data);

var_dump($result->isValid());
//bool(false)

// Recursive function for error printing
function printErrors($result) {
    foreach($result->errors() as $error) {
        echo $result->path().': '.$error."\n";
    }
    
    foreach($result->invalidFields() as $result) {
        printErrors($result);
    }
}
printErrors($result);

/*
name: Value is empty
spells.charm.name: Value did not pass filter 'minLength'
spells.3: Value did not pass filter 'alpha'
*/

Try it out

To fire up this demo, just run:

git clone https://github.com/phpixie/validate
cd validate/examples

php composer.phar install
php simple.php
php document.php