serkin/volan

PHP array schema validator

Light PHP validation library

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., _(*1)

, _(*2)

• 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:, _(*3)

``` bash composer require serkin/volan dev-master, <sub>(*4)</sub>

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

```php
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: ``` php namespace Volan\Validator; class MongoidValidator extends AbstractValidator { public function isValid($nodeData) { return ($nodeData instanceof \MongoId); } }, <sub>(*5)</sub>

* Add autoload to composer.json
``` 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 ``` php namespace Volan\Validator; use Respect\Validation\Validator as v;, <sub>(*6)</sub>

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

}

}, <sub>(*8)</sub>

## Tips
### Allow extra keys in data
If you want allow extra keys in array you can define it in constructor
``` php
$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., <sub>(*9)</sub>

``` php $validator = new \Volan\Volan($schema); $validator->setRequiredMode(false); $result = $validator->validate($book);, <sub>(*10)</sub>

### Logging
If you want see validation process set logger
``` php


$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: ``` php namespace Volan\Validator;, <sub>(*11)</sub>

class MongoidValidator extends AbstractValidator { public function isValid($nodeData) { return ($nodeData instanceof \MongoId); } }, <sub>(*12)</sub>

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
``` php
...
'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; ``` php class ArrayOfMongoids extends AbstractValidator { public function isValid($nodeData) { foreach($nodeData as $id) { if($id !instanceof \MongoId) || !$this->presentInCategoryCollection($id)) return false; } }, <sub>(*13)</sub>

    return true;
}

public function presentInCategoryCollection($id)
{
    // Getting connection and so on

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

}, <sub>(*14)</sub>

now in schema we add 
``` php
...
'categories' => ['_type' => 'array_of_mongoids']
...

Dependencies

• PHP: >= 5.4

Contribution

Please see CONTRIBUTING for details., <sub>(*15)</sub>

Licence

The MIT License (MIT). Please see License File for more information., <sub>(*16)</sub>

Tests

phpunit

Or with Docker, <sub>(*17)</sub>

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

Code style, <sub>(*18)</sub>

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