awurth/slim-validation

A validator for the Slim PHP Micro-Framework

Slim Validation

, _(*1)

A validator for PHP, using Respect Validation (Requires PHP 7+), _(*2)

This project was originally designed to be used with the Micro-Framework "Slim", but can now be used with any psr/http-message compliant framework, or any other PHP project if you don't need request parameters validation., _(*3)

Installation

``` bash $ composer require awurth/slim-validation, <sub>(*4)</sub>

### Configuration
To initialize the validator, create a new instance of `Awurth\SlimValidation\Validator`
``` php
Validator::__construct([ bool $showValidationRules = true [, array $defaultMessages = [] ]])

$showValidationRules

• If set to true, errors will be stored in an associative array with the validation rules names as the key ``` php $errors = [ 'username' => [ 'length' => 'The username must have a length between 8 and 16', 'alnum' => 'The username must contain only letters (a-z) and digits (0-9)' ] ];

* If set to `false`, errors will be stored in an array of strings
``` php
$errors = [
    'username' => [
        'The username must have a length between 8 and 16',
        'The username must contain only letters (a-z) and digits (0-9)'
    ]
];

$defaultMessages

An array of messages to overwrite the default Respect Validation messages ``` php $defaultMessages = [ 'length' => 'This field must have a length between {{minValue}} and {{maxValue}} characters', 'notBlank' => 'This field is required' ];, <sub>(*5)</sub>

### Add the validator as a service
You can add the validator to the app container to access it easily through your application
``` php
$container['validator'] = function () {
    return new Awurth\SlimValidation\Validator();
};

Usage

``` php use Respect\Validation\Validator as V;, <sub>(*6)</sub>

// The validate method returns the validator instance $validator = $container->validator->validate($request, [ 'get_or_post_parameter_name' => V::length(6, 25)->alnum('_')->noWhitespace(), // ... ]);, <sub>(*7)</sub>

if ($validator->isValid()) { // Do something... } else { $errors = $validator->getErrors(); }, <sub>(*8)</sub>

### Validation methods
#### Request parameters validation
``` php
$_POST = [
    'username' => 'awurth',
    'password' => 'my_password'
];

``` php /** * @var Psr\Http\Message\ServerRequestInterface $request */, <sub>(*9)</sub>

$validator->request($request, [ 'username' => V::notBlank(), 'password' => V::length(8) ]);, <sub>(*10)</sub>

#### Object properties validation
``` php
class ObjectToValidate {
    private $privateProperty;
    protected $protectedProperty;
    public $pulicProperty;

    // ...
}

``` php /** * @var object $object */, <sub>(*11)</sub>

$validator->object($object, [ 'privateProperty' => V::notBlank(), 'protectedProperty' => V::notBlank(), 'publicProperty' => V::notBlank() ]);, <sub>(*12)</sub>

If a property does not exist, the tested value will be `null`

#### Array validation
``` php
$arrayToValidate = [
    'key_1' => 'value_1',
    'key_2' => 'value_2'
];

``` php /** * @var array $arrayToValidate */, <sub>(*13)</sub>

$validator->array($arrayToValidate, [ 'key_1' => V::notBlank(), 'key_2' => V::notBlank() ]);, <sub>(*14)</sub>

#### Single value validation
``` php
$validator->value('12345', V::numeric(), 'secret_code');

The validate() method

``` php /** * @var Psr\Http\Message\ServerRequestInterface $request */, <sub>(*15)</sub>

$validator->validate($request, [ 'param' => V::notBlank() ]);, <sub>(*16)</sub>

/** * @var object $object */, <sub>(*17)</sub>

$validator->validate($object, [ 'property' => V::notBlank() ]);, <sub>(*18)</sub>

/** * @var array $array */, <sub>(*19)</sub>

$validator->array($array, [ 'key' => V::notBlank() ]);, <sub>(*20)</sub>

$secretCode = '12345'; $validator->validate($secretCode, [ 'rules' => V::numeric(), 'key' => 'secret_code' ]);, <sub>(*21)</sub>

### Error groups
``` php
$user = [
    'username' => 'awurth',
    'password' => 'my_password'
];

$address = [
    'street' => '...',
    'city' => '...',
    'country' => '...'
];

$validator->validate($user, [
    // ...
], 'user');

$validator->validate($address, [
    // ...
], 'address');

``` php $validator->getErrors();, <sub>(*22)</sub>

// Will return: [ 'user' => [ 'username' => [ // Errors... ] ], 'address' => [ 'street' => [ // Errors... ] ] ], <sub>(*23)</sub>

### Custom messages
Slim Validation allows you to set custom messages for validation errors. There are 4 types of custom messages

#### Default rules messages
The ones defined in the `Validator` constructor.

#### Global rules messages
Messages that overwrite **Respect Validation** and **default rules messages** when calling the `validate` method.

``` php
$container->validator->validate($request, [
    'get_or_post_parameter_name' => V::length(6, 25)->alnum('_')->noWhitespace(),
    // ...
], null, [
    'length' => 'Custom message',
    'alnum' => 'Custom message',
    // ...
]);

Individual rules messages

Messages for a single request parameter. Overwrites all above messages., <sub>(*24)</sub>

``` php $container->validator->validate($request, [ 'get_or_post_parameter_name' => [ 'rules' => V::length(6, 25)->alnum('_')->noWhitespace(), 'messages' => [ 'length' => 'Custom message', 'alnum' => 'Custom message', // ... ] ], // ... ]);, <sub>(*25)</sub>

#### Single parameter messages
Defines a single error message for a request parameter, ignoring the validation rules. Overwrites all messages.

``` php
$container->validator->validate($request, [
    'get_or_post_parameter_name' => [
        'rules' => V::length(6, 25)->alnum('_')->noWhitespace(),
        'message' => 'This field must have a length between 6 and 25 characters and contain only letters and digits'
    ],
    // ...
]);

Twig extension

This package comes with a Twig extension to display error messages and submitted values in your Twig templates. You can skip this step if you don't want to use it., <sub>(*26)</sub>

To use the extension, you must install twig first ``` bash $ composer require slim/twig-view, <sub>(*27)</sub>

### Configuration
``` php
$container['view'] = function ($container) {
    // Twig configuration
    $view = new Slim\Views\Twig(...);
    // ...

    // Add the validator extension
    $view->addExtension(
        new Awurth\SlimValidation\ValidatorExtension($container['validator'])
    );

    return $view;
};

Functions

``` twig {# Use has_errors() function to know if a form contains errors #} {{ has_errors() }}, <sub>(*28)</sub>

{# Use has_error() function to know if a request parameter is invalid #} {{ has_error('param') }}, <sub>(*29)</sub>

{# Use error() function to get the first error of a parameter #} {{ error('param') }}, <sub>(*30)</sub>

{# Use errors() function to get all errors #} {{ errors() }}, <sub>(*31)</sub>

{# Use errors() function with the name of a parameter to get all errors of a parameter #} {{ errors('param') }}, <sub>(*32)</sub>

{# Use val() function to get the value of a parameter #} {{ val('param') }}, <sub>(*33)</sub>

## Example
##### AuthController.php
``` php
public function register(Request $request, Response $response)
{
    if ($request->isPost()) {
        $this->validator->validate($request, [
            'username' => V::length(6, 25)->alnum('_')->noWhitespace(),
            'email' => V::notBlank()->email(),
            'password' => [
                'rules' => v::length(6, 25),
                'messages' => [
                    'length' => 'This field must have a length between {{minValue}} and {{maxValue}} characters'
                ]
            ],
            'confirm_password' => [
                'rules' => v::equals($request->getParam('password')),
                'messages' => [
                    'equals' => 'The password confirmation must be equal to the password'
                ]
            ]
        ]);

        if ($this->validator->isValid()) {
            // Register user in database

            return $response->withRedirect('url');
        }
    }

    return $this->view->render($response, 'register.twig');
}

register.twig

``` twig , <sub>(*34)</sub>

<input type="text" name="email" value="{{ val('email') }}">
{% if has_error('email') %}<span>{{ error('email') }}</span>{% endif %}

<input type="text" name="password">
{% if has_error('password') %}<span>{{ error('password') }}</span>{% endif %}

<input type="text" name="confirm_password">
{% if has_error('confirm_password') %}<span>{{ error('confirm_password') }}</span>{% endif %}