serkin/volan

PHP array schema validator

dev-master 2018-06-19 09:43 UTC

Requires

• php: >=7.0|>=5.4
• monolog/monolog: *

Requires (Dev)

• friendsofphp/php-cs-fixer: *
• phpunit/phpunit: ~4.8|~5.7

MIT

• Serkin Alexander

• php
• validation

README

For everyone who uses MongoDB or other NoSQL solution and cares about what client sends to his/her database and looking for validation library written in PHP. Volan validates array against given shema and provides you with full information about invalid nodes. Can be used with logging so you can see the whole validation process.

• Volan
  • Installation
  • Usage
  • Predefined validatorse
  • Custom validators
  • Usage with other libraries
  • Tips
    • Allow extra keys in data
    • Allow required fields be omitted
    • Logging
    • PSR compatible class names
    • Relational structure
  • Dependencies
  • Contribution
  • Licence
  • Tests

Installation

via Composer:

composer require serkin/volan dev-master

Usage

All you have to do is to specify _type field for each node. _type is a reference to a validation class

include 'vendor/autoload.php';

$schema = [
    'root' => [ // Schema must begins with 'root'
        'title' => [
            '_type' => 'required_string'
        ],
        'price' => [
            '_type' => 'number'
        ],
        'author' => [
            '_type' => 'string'
        ],
        'instock' => [
            '_type' => 'required_boolean'
        ],
        'info' =>  [
            '_type' => 'array',
            'isbn' => [
                '_type' => 'string'
            ],
            'pages' => [
                '_type' => 'number'
            ]
        ],
        'comments' => [
            '_type' => 'nested_array',
            'user_id' => [
                '_type' => 'required_number'
            ],
            'comment' => [
                '_type' => 'required_string'
            ]
        ]
    ]
];

$book = [
    'title' => 'The Idiot', // Cannot be omitted
    'instock' => true, // Cannot be omitted and has to be bool type
    'info' => ['isbn' => '978-0451531520'],
    //  'price' can be omitted but if present has to be numeric type 
    'comments' => [ // Nested array check nested elements
        [
            'user_id' => 1,
            'comment' => 'Good book',
            // 'extra_field' => 'bad field' 
            // By default if key not present in schema validation stops and returns false 
        ],
        [
            'user_id' => 2,
            'comment' => 'I like it'
        ]
    ]
];

$validator = new \Volan\Volan($schema);
$result = $validator->validate($book);

// if $result->isValid() === false you can get full information about invalid node
var_dump($result->getErrorInfo());

Predefined validators

Strings

• string: string
• required_string: string that has to be present

Arrays

• array: array
• required_array: array that has to be present
• nested_array: array with nested arrays
• required_nested_array: array with nested arrays has to be present

Bool

• boolean: boolean
• required_boolean: boolean that has to be present

Numbers

• number: int or float
• required_number: int or float that has to be present

Custom validators

If you need extra validators you can create them extending \Volan\Validator\AbstractValidator class

• Create folder src/Volan/Validator in your library
• Add your custom validator src/Volan/Validator/mongoid_validator.php. Example for mongoid validator:

namespace Volan\Validator;
class MongoidValidator extends AbstractValidator
{
    public function isValid($nodeData)
    {
        return ($nodeData instanceof \MongoId);
    }
}

• Add autoload to composer.json

"autoload": {
        "psr-4": {
            "Volan\\Validator\\": "src/Volan/Validator/"
        }
    }

Usage with other libraries

If you want to use other validation libraries with Volan it is easy. Let's take a look how it works with Respect validation engine

namespace Volan\Validator;
use Respect\Validation\Validator as v;

class IntBetween10And20Validator extends AbstractValidator
{
    public function isValid($nodeData)
    {
        return v::int()->between(10, 20)->validate($nodeData);
        
    }
}

Tips

Allow extra keys in data

If you want allow extra keys in array you can define it in constructor

$validator = new \Volan\Volan($schema, $strictMode = false);

Allow required fields be omitted

In mongoDB when you update just several fields in collection you cannot pass validation cause required fields may be missing. You can tell validator consider all required validation as optional.

$validator = new \Volan\Volan($schema);
$validator->setRequiredMode(false);
$result = $validator->validate($book);

Logging

If you want see validation process set logger

$validator = new \Volan\Volan($schema);

$result = $validator->validate($book);
$result->getLog();

PSR compatible class names

You can use PSR compatible names for validation classes. Previous example with mongoid validation class can be rewritten like:

namespace Volan\Validator;

class MongoidValidator extends AbstractValidator
{
    public function isValid($nodeData)
    {
        return ($nodeData instanceof \MongoId);
    }
}

Here we changed mongoid_validator to MongoidValidator. Example with int_between_10_and_20_validator be rewritten to IntBetween10And20Validator

Relational structure

Let's imagine we have field in our book data

...
'categories' => [new \MongoId('111111111111111111111111'),new \MongoId('111111111111111111111112')]
...

and we want ensure that all elements not only instances of MongoId but actually present in our database. It is easy. Our validator will be look like: namespace Volan\Validator;

class ArrayOfMongoids extends AbstractValidator
{
    public function isValid($nodeData)
    {
        foreach($nodeData as $id) {
            if($id !instanceof \MongoId) || !$this->presentInCategoryCollection($id))
                return false;
            }
        }
        
        return true;
    }
    
    public function presentInCategoryCollection($id)
    {
        // Getting connection and so on

        $collection = $db->selectCollection('categories');
        return (bool)$collection->findOne(['_id' => $id]);
    }
    
}

now in schema we add

...
'categories' => ['_type' => 'array_of_mongoids']
...

Dependencies

• PHP: >= 5.4

Contribution

Please see CONTRIBUTING for details.

Licence

The MIT License (MIT). Please see License File for more information.

Tests

phpunit

Or with Docker

docker run --rm -v "$PWD":/var/src/ serkin/php7 vendor/bin/phpunit --debug

Code style

docker run --rm -v "$PWD":/var/src/ serkin/php7 vendor/bin/php-cs-fixer fix src