Presentation

Helper used to validate data, to verify that it respects a contract. This can be useful to verify that the input data of an API is as expected.

Contract examples

Pass-through:

null

Scalar types:

'null'

'int'

'string'

'float'

'bool'

Scalar types with a default value:

[
    'type'    => 'string',
    'default' => 'abc',
]

[
    'type'    => 'bool',
    'default' => false,
]

Number (int or float) with a minimum and/or maximum value:

[
    'type' => 'int',
    'min'  => 1,
]

[
    'type' => 'float',
    'min'  => -8.12,
    'max'  => 8.12,
]

String with a minimum and/or maximum length, or a regular expression mask:

[
    'type'   => 'string',
    'minlen' => 1,
    'maxlen' => 12,
]

[
    'type' => 'string',
    'mask' => '^[Bb][Oo0]..[Oo0].r$',
]

Enum type with an optional default value:

[
    'type'    => 'enum',
    'values'  => ['red', 'green', 'blue'],
    'default' => 'red',
]

List type with a contract definition used to filter its values as integers:

[
    'type'     => 'list',
    'contract' => 'int',
]

Associative array with the definition of its keys (some of them with a defined type):

[
    'type' => 'assoc',
    'keys' => [
        'id' => 'int',
        'name',
        'dateCreation',
    ]
]

List type with a contract definition used to defined its values as associative arrays:

[
    'type'     => 'list',
    'contract' => [
        'type' => 'assoc',
        'keys' => ['id', 'name'],
    ]
]

Associative array with keys definition (all of them with a type, one is not mandatory):

[
    'type' => 'assoc',
    'keys' => [
        'id'   => int,
        'name' => [
            'type'      => 'string',
            'mandatory' => false,
        ]
    ]
]

Complex example:

[
       'type' => 'assoc',
       'keys' => [
               'id'          => 'int',
               'isCreated'   => 'bool',
               'name'        => [
                       'type'    => 'string',
                       'default' => 'abc',
               ],
               'color'       => [
                       'type'      => 'enum',
                       'values'    => ['red', 'green', 'blue'],
                       'default'   => 'red',
                       'mandatory' => false,
               ],
               'creator'     => [
                       'type' => 'assoc',
                       'keys' => [
                               'id' => 'int',
                               'name',
                               'dateCreation',
                       ],
               ],
               'children'    => [
                       'type'      => 'list',
                       'mandatory' => false,
                       'contract'  => [
                               'type' => 'assoc',
                               'keys' => [
                                       'id' => 'int',
                                       'name',
                               ]
                       ],
               ],
               'identifiers' => [
                       'type'     => 'list',
                       'contract' => 'int',
               ],
       ],
]

Usage

The \Temma\Utils\DataFilter object offers a static method process(). This method takes two parameters, the data to filter and the contract to use, and returns the filtered data. If the contract's syntax is not correct, the method raises a \Temma\Exceptions\IO exception. If the data doesn't validate the contract, the method raises a \Temma\Exceptions\Application exception.

Example:

use \Temma\Utils\Datafilter as TµDataFilter;
use \Temma\Exceptions\IO as TµIOException;
use \Temma\Exceptions\Application AS TµApplicationException;
use \Temma\Base\Log as TµLog;

$contract = [
    'type'   => 'enum',
    'values' => ['admin', 'member', 'guest'],
];
try {
    $data = TµDatafilter($data, $contract);
} catch (TµIOException $ie) {
    TµLog::log('myapp', 'WARN', "Invalid contract.");
    throw $ie;
} catch (TµApplicationException $ae) {
    TµLog::log('myapp', 'WARN', "Invalid data.");
    throw $ae;
}