Valider des Données¶

Valider les Données Avant de Construire les Entities¶

Durant la transformation des données en entities, vous pouvez valider les données. La validation des données vous permet de vérifier le type, la forme et la taille des données. Par défaut les données requêtées seront validées avant qu’elles ne soient converties en entities. Si une des règles de validation échoue, l’entity retournée contiendra des erreurs. Les champs avec des erreurs ne seront pas présents dans l’entity retournée:

$article = $articles->newEntity($this->request->getData());
if ($article->errors()) {
    // validation de l'entity a échouée.
}

Quand vous construisez une entity avec la validation activée, les choses suivantes vont se produire:

1. L’objet validator est créé.

2. Les providers de validation table et default sont attachés.

3. La méthode de validation nommée est appelée. Par exemple, validationDefault().

4. L’event Model.buildValidator va être déclenché.

5. Les données Requêtées vont être validées.

6. Les données Requêtées vont être castées en types qui correspondent aux types de colonne.

7. Les erreurs vont être définies dans l’entity.

8. Les données valides vont être définies dans l’entity, alors que les champs qui échouent la validation seront laissés de côté.

Si vous voulez désactiver la validation lors de la conversion des données requêtées, définissez l’option validate à false:

$article = $articles->newEntity(
    $this->request->data,
    ['validate' => false]
);

La méthode patchEntity() fonctionne de façon identique:

$article = $articles->patchEntity($article, $newData, [
    'validate' => false
]);

use Cake\ORM\Table;
use Cake\Validation\Validator;

class ArticlesTable extends Table
{

    public function validationDefault(Validator $validator)
    {
        $validator
            ->requirePresence('title', 'create')
            ->notEmpty('title');

        $validator
            ->allowEmpty('link')
            ->add('link', 'valid-url', ['rule' => 'url']);

        ...

        return $validator;
    }
}

$article = $articles->newEntity(
    $this->request->data,
    ['validate' => 'update']
);

class ArticlesTable extends Table
{
    public function validationUpdate($validator)
    {
        $validator
            ->add('title', 'notEmpty', [
                'rule' => 'notEmpty',
                'message' => __('Vous devez fournir un titre'),
            ])
            ->add('body', 'notEmpty', [
                'rule' => 'notEmpty',
                'message' => __('un corps est nécessaire')
            ]);
        return $validator;
    }
}

Utiliser un Ensemble de Validation Différent pour les Associations¶

Les ensembles de validation peuvent également être définis par association. Lorsque vous utilisez les méthodes newEntity() ou patchEntity(), vous pouvez passer des options supplémentaires à chaque association qui doit être convertie:

$data = [
     'title' => 'My title',
     'body' => 'The text',
     'user_id' => 1,
     'user' => [
         'username' => 'mark'
     ],
     'comments' => [
         ['body' => 'First comment'],
         ['body' => 'Second comment'],
     ]
 ];

 $article = $articles->patchEntity($article, $data, [
     'validate' => 'update',
     'associated' => [
         'Users' => ['validate' => 'signup'],
         'Comments' => ['validate' => 'custom']
     ]
 ]);

// UsersTable.php

public function validationDefault(Validator $validator)
{
    $validator->notEmpty('username');
    $validator->notEmpty('password');
    $validator->add('email', 'valid-email', ['rule' => 'email']);
    ...

    return $validator;
}

public function validationeHardened(Validator $validator)
{
    $validator = $this->validationeDefault($validator);

    $validator->add('password', 'length', ['rule' => ['lengthBetween', 8, 100]]);
    return $validator;
}

use Cake\ORM\Table;
use Cake\Validation\Validator;

class UsersTable extends Table
{

    public function validationDefault(Validator $validator)
    {
        $validator
            ->add('role', 'validRole', [
                'rule' => 'isValidRole',
                'message' => __('Vous devez fournir un rôle valide'),
                'provider' => 'table',
            ]);
        return $validator;
    }

    public function isValidRole($value, array $context)
    {
        return in_array($value, ['admin', 'editor', 'author'], true);
    }

}

$validator->add('name', 'myRule', [
    'rule' => function ($data, $provider) {
        if ($data > 1) {
            return true;
        }
        return 'Valeur incorrecte.';
    }
]);

$defaultValidator = $usersTable->validator('default');

$hardenedValidator = $usersTable->validator('hardened');

// Dans votre class Table
public function initialize(array $config)
{
    $this->_validatorClass = '\FullyNamespaced\Custom\Validator';
}

Créer un Vérificateur de Règles¶

Les classes de vérificateur de Règles sont généralement définies par la méthode buildRules() dans votre classe de table. Les behaviors et les autres souscripteurs d’event peuvent utiliser l’event Model.buildRules pour ajouter des règles au vérificateur pour une classe de Table donnée:

use Cake\ORM\RulesChecker;

// Dans une classe de table
public function buildRules(RulesChecker $rules)
{
    // Ajoute une règle qui est appliquée pour la création et la mise à jour d'opérations
    $rules->add(function ($entity, $options) {
        // Retourne un booléen pour indiquer si succès/échec
    }, 'ruleName');

    // Ajoute une règle pour la création.
    $rules->addCreate(function ($entity, $options) {
        // Retourne un booléen pour indiquer si succès/échec
    }, 'ruleName');

    // Ajoute une règle pour la mise à jour.
    $rules->addUpdate(function ($entity, $options) {
        // Retourne un booléen pour indiquer si succès/échec
    }, 'ruleName');

    // Ajoute une règle pour la suppression.
    $rules->addDelete(function ($entity, $options) {
        // Retourne un booléen pour indiquer si succès/échec
    }, 'ruleName');

    return $rules;
}

Vos fonctions de règles ont pour paramètres l’Entity à vérifier et un tableau d’options. Le tableau d’options va contenir errorField, message et repository. L’option repository va contenir la classe de table sur laquelle les règles sont attachées. Comme les règles acceptent tout callable, vous pouvez aussi utiliser des fonctions d’instance:

$rules->addCreate([$this, 'uniqueEmail'], 'uniqueEmail');

ou des classes callable:

$rules->addCreate(new IsUnique(['email']), 'uniqueEmail');

Lors de l’ajout de règles, vous pouvez définir le champ pour lequel la règle est faite, et le message d’erreur en options:

$rules->add([$this, 'isValidState'], 'validState', [
    'errorField' => 'status',
    'message' => 'Cette facture ne peut pas être déplacée pour ce statut.'
]);

L’erreur sera visible lors de l’appel à la méthode errors() dans l’entity:

$entity->errors(); // Contient les messages d'erreur des règles du domaine

Créer des Règles de Champ Unique¶

Comme les règles uniques sont couramment utilisées, CakePHP inclut une classe de Règle simple qui vous permet de définir des ensembles de champ unique:

use Cake\ORM\Rule\IsUnique;

// Un champ unique.
$rules->add($rules->isUnique(['email']));

// Une liste de champs
$rules->add($rules->isUnique(
    ['username', 'account_id'],
    'Cette combinaison `username` & `account_id` est déjà utilisée.'
));

Quand vous définissez des règles sur des champs de clé étrangère, il est important de se rappeler que seuls les champs listés sont utilisés dans la règle. Cela signifie que définir $user->account->id ne va pas déclencher la règle ci-dessus.

Règles des Clés Etrangères¶

Alors que vous pourriez compter sur les erreurs de la base de données pour imposer des contraintes, utiliser des règles peut vous aider à fournir une expérience utilisateur plus sympathique. C’est pour cela que CakePHP inclut une classe de règle ExistsIn:

// Un champ unique.
$rules->add($rules->existsIn('article_id', 'articles'));

// Plusieurs clés, utile pour des clés primaires composites.
$rules->add($rules->existsIn(['site_id', 'article_id'], 'articles'));

Les champs dont il faut vérifier l’existence dans la table liée doivent faire parti de la clé primaire.

Vous pouvez forcer existsIn à passer quand des parties qui peuvent être nulles de votre clé étrangère composite sont nulles:

// Example: Une clé primaire composée dans NodesTable est (id, site_id).
// Un "Node" peut faire référence à un parent Node mais ce n'est pas obligatoire.
// Dans un cas d'utilisation, parent_id est null.
// Nous permettons à cette règle de passer, même si les champs qui sont nullable, comme
// parent_id, sont null :
$rules->add($rules->existsIn(
    ['parent_id', 'site_id'], // Schema: parent_id NULL, site_id NOT NULL
    'ParentNodes',
    ['allowNullableNulls' => true]
));

// Un Node doit cependant toujours avoir une référence à un Site.
$rules->add($rules->existsIn(['site_id'], 'Sites'));

Dans la majorité des bases de données SQL, les index UNIQUE sur plusieurs colonnes permettent à plusieurs valeurs null d’exister car NULL n’est pas égal à lui même. Même si autoriser plusieurs valeurs null est le comportement par défaut de CakePHP, vous pouvez inclure des valeurs null dans vos validations en utilisant allowMultipleNulls:

// Seulement une valeur null peut exister dans `parent_id` et `site_id`
$rules->add($rules->existsIn(
    ['parent_id', 'site_id'],
    'ParentNodes',
    ['allowMultipleNulls' => false]
));

Règles sur le Nombre de Valeurs d’une Association¶

Si vous devez valider qu’une propriété ou une association contient un bon nombre de valeurs, vous pouvez utiliser la règle validCount():

// Dans le fichier ArticlesTable.php
// Pas plus de 5 tags sur un article.
$rules->add($rules->validCount('tags', 5, '<=', 'Vous pouvez avoir seulement 5 tags'));

Quand vous définissez des règles qui concernent le nombre, le troisième paramètre vous permet de définir l’opérateur de comparaison à utiliser. ==, >=, <=, >, <, and != sont les opérateurs acceptés. Pour vous assurer qu’un nombre d’une propriété est entre certaines valeurs, utilisez deux règles:

// Dans le fichier ArticlesTable.php
// Entre 3 et 5 tags
$rules->add($rules->validCount('tags', 3, '>=', 'Vous devez avoir au moins 3 tags'));
$rules->add($rules->validCount('tags', 5, '<=', 'Vous devez avoir au moins 5 tags'));

Notez que validCount retourne false si la propriété ne peut pas être comptée ou n’existe pas:

// La sauvegarde échouera si tags est null
$rules->add($rules->validCount('tags', 0, '<=', 'Vous ne devez pas avoir de tags'));

Utiliser les Méthodes Entity en tant que Règles¶

Vous pouvez utiliser les méthodes entity en tant que règles de domaine:

$rules->add(function ($entity, $options) {
    return $entity->isOkLooking();
}, 'ruleName');

Créer des Règles Personnalisées Réutilisables¶

Vous pouvez vouloir réutiliser des règles de domaine personnalisées. Vous pouvez le faire en créant votre propre règle invokable:

use App\ORM\Rule\IsUniqueWithNulls;
// ...
public function buildRules(RulesChecker $rules)
{
    $rules->add(new IsUniqueWithNulls(['parent_id', 'instance_id', 'name']), 'uniqueNamePerParent', [
        'errorField' => 'name',
        'message' => 'Name must be unique per parent.'
    ]);
    return $rules;
}

Regardez les règles du coeur pour plus d’informations sur la façon de créer de telles règles.

Créer des Objets de Règles Personnalisées¶

Si votre application a des règles qui sont souvent réutilisées, il peut être utile de packager ces règles dans des classes réutilisables:

// Dans src/Model/Rule/CustomRule.php
namespace App\Model\Rule;

use Cake\Datasource\EntityInterface;

class CustomRule
{
    public function __invoke(EntityInterface $entity, array $options)
    {
        // Do work
        return false;
    }
}

// Ajoute la règle personnalisée
use App\Model\Rule\CustomRule;

$rules->add(new CustomRule(...), 'ruleName');

En ajoutant des classes de règle personnalisée, vous pouvez garder votre code DRY et faciliter le test des règles de votre domaine.

Désactiver les Règles¶

Quand vous sauvegardez une entity, vous pouvez désactiver les règles si cela est nécessaire:

$articles->save($article, ['checkRules' => false]);

$validatedEntity = $articlesTable->newEntity(
    $unsafeData,
    ['validate' => 'customName']
);
$validatedEntity = $articlesTable->patchEntity(
    $entity,
    $unsafeData,
    ['validate' => 'customName']
);

public function validationCustomName($validator)
{
    $validator->add(...);
    return $validator;
}

// Dans src/Model/Table/UsersTable.php
public function validatePasswords($validator)
{
    $validator->add('confirm_password', 'no-misspelling', [
        'rule' => ['compareWith', 'password'],
        'message' => 'Les mot de passe ne sont pas égaux',
    ]);

    ...
    return $validator;
}

$userEntity->email = 'pas un email!!';
$usersTable->save($userEntity);

// Dans src/Model/Table/UsersTable.php
public function buildRules(RulesChecker $rules)
{
    $rules->add($rules->isUnique(['email']));
    return $rules;
}

// Autre part dans le code de votre application
$userEntity->email = '[email protected]';
$usersTable->save($userEntity); // Retourne false

// Dans src/Model/Table/OrdersTable.php
public function buildRules(RulesChecker $rules)
{
    $check = function ($order) {
        return $order->price < 100 && $order->shipping_mode === 'free';
    };
    $rules->add($check, [
        'errorField' => 'shipping_mode',
        'message' => 'Pas de frais de port gratuit pour une commande de moins de 100!'
    ]);
    return $rules;
}

// Autre part dans le code de l'application
$order->price = 50;
$order->shipping_mode = 'free';
$ordersTable->save($order); // Retourne false

Utiliser la Validation en tant que Règle d’Application¶

Dans certaines situations, vous voudrez peut-être lancer les mêmes routines pour des données générées à la fois par un utilisateur et à l’intérieur de votre application. Cela peut se produire lorsque vous exécutez un script CLI qui définit des propriétés directement dans des entities:

// Dans src/Model/Table/UsersTable.php
public function validationDefault(Validator $validator)
{
    $validator->add('email', 'valid', [
        'rule' => 'email',
        'message' => 'Email invalide'
    ]);
    ...
    return $validator;
}

public function buildRules(RulesChecker $rules)
{
    // Ajoute des règles de  validation
    $rules->add(function ($entity) {
        $data = $entity->extract($this->schema()->columns(), true);
        $validator = $this->validator('default');
        // Prior to 3.9 use $validator->errors()
        $errors = $validator->validate($data, $entity->isNew());
        $entity->errors($errors);

        return empty($errors);
    });

    ...

    return $rules;
}

Lors de l’exécution du code suivant, la sauvegarde échouera grâce à la nouvelle règle d’application qui a été ajoutée:

$userEntity->email = 'Pas un email!!!';
$usersTable->save($userEntity);
$userEntity->errors('email'); // Email invalide

le même résultat est attendu lors de l’utilisation de newEntity() ou patchEntity():

$userEntity = $usersTable->newEntity(['email' => 'Pas un email!!']);
$userEntity->errors('email'); // Email invalide