Validation¶

Valider la Présence d’un champ¶

La méthode requirePresence() oblige le champ à être présent dans tout tableau de validation. Si le champ est absent, la validation va échouer. La méthode requirePresence() a 4 modes:

• true La présence du champ est toujours requise.

• false La présence du champ n’est pas requise.

• create La présence du champ est requise lorsque vous validez une opération create.

• update La présence du champ est requise lorsque vous validez une opération update.

Par défaut true est utilisée. La présence de la clé est vérifiée pour l’utilisation de array_key_exists() donc les valeurs null vont être comptabilisées comme étant présentes. Vous pouvez définir le mode en utilisant le deuxième paramètre:

$validator->requirePresence('author_id', 'create');

Si vous avez plusieurs champs dont la présence est requise, vous pouvez les définir en liste:

// Définir plusieurs champs pour create
$validator->requirePresence(['author_id', 'title'], 'create');

// Définir plusieurs champs pour divers modes
$validator->requirePresence([
    'author_id' => [
        'mode' => 'create',
        'message' => "L'auteur est obligatoire.",
    ],
    'published' => [
        'mode' => 'update',
        'message' => 'Le statut de publication est obligatoire.',
    ]
]);

Permettre aux Champs d’être Vides¶

Les méthodes allowEmpty() et notEmpty() vous permettent de contrôler les champs autorisés à être “vide”. En utilisant la méthode notEmpty(), le champ donné sera noté comme invalide quand il est vide. Vous pouvez utiliser allowEmpty() pour permettre à un champ d’être vide. Les deux méthodes allowEmpty() et notEmpty() ont un paramètre mode qui vous permet de contrôler quand un champ peut ou ne peut pas être vide:

• true Le champ peut être vide.

• false Le champ ne peut pas être vide.

• create La présence du champ est nécessaire mais il peut être vide lors de la validation d’une opération create.

• update La présence du champ est nécessaire mais il peut être vide lors de la validation d’une opération update.

Les valeurs '', null et [] (tableau vide) vont entraîner des erreurs de validation quand les champs n’ont pas l’autorisation d’être vide. Quand les champs ont l’autorisation d’être vide, les valeurs '', null, false, [], 0, '0' sont acceptées.

Un exemple de ces méthodes est le suivant:

$validator->allowEmpty('published')
    ->notEmpty('title', 'Le titre ne peut être vide')
    ->notEmpty('body', 'Le body ne peut être vide', 'create')
    ->allowEmpty('header_image', 'update');

Marquer les Règles comme étant les Dernières à être exécutées¶

Quand les champs ont plusieurs règles, chaque règle de validation sera exécutée même si la précédente a échouée. Cela vous permet de recueillir autant d’erreurs de validation que vous le pouvez en un seul passage. Si toutefois, vous voulez stopper l’exécution après qu’une règle spécifique a échoué, vous pouvez définir l’option last à true:

$validator = new Validator();
$validator
    ->add('body', [
        'minLength' => [
            'rule' => ['minLength', 10],
            'last' => true,
            'message' => 'Les commentaires doivent avoir un contenu un peu fourni.'
        ],
        'maxLength' => [
            'rule' => ['maxLength', 250],
            'message' => 'Les commentaires ne peuvent pas être trop longs.'
        ]
    ]);

Dans l’exemple ci-dessus, si la règle minLength (longueur minimale) échoue, la règle maxLength ne sera pas exécutée.

Méthodes de Validation Moins Verbeuses¶

Depuis la version 3.2, l’objet Validator accepte de nombreuses nouvelles méthodes qui rendent la construction de validateurs moins verbeux. Par exemple, ajouter des règles de validation à un champ username peut maintenant ressembler à ceci:

$validator = new Validator();
$validator
    ->email('username')
    ->ascii('username')
    ->lengthBetween('username', [4, 8]);

Ajouter des Providers de Validation¶

Les classes Validator, ValidationSet et ValidationRule ne fournissent elles-mêmes aucune méthode de validation. Les règles de validation viennent de “providers”. Vous pouvez lier tout nombre de providers à un objet Validator. Les instances de Validator sont automatiquement fournies avec une configuration de provider à “default”. Le provider par défaut est mappé à la classe Cake\Validation\Validation. Cela facilite l’utilisation des méthodes de cette classe en règles de validation. Lors de l’utilisation conjointe de Validators et de l’ORM, des providers supplémentaires sont configurés pour la table et les objets entity. Vous pouvez utiliser la méthode setProvider() pour ajouter un provider supplémentaire que votre application a besoin d’utiliser:

$validator = new Validator();

// Utilise une instance de l'object.
$validator->setProvider('custom', $myObject);

// Utilise un nom de classe. Les méthodes doivent être static.
$validator->setProvider('custom', 'App\Model\Validation');

Les providers de Validation peuvent être des objets, ou des noms de classe. Si un nom de classe est utilisé, les méthodes doivent être static. Pour utiliser un provider autre que “default”, assurez-vous de définir la clé setProvider() dans votre règle:

// Utilise une règle à partir du provider de la table
$validator->add('title', 'custom', [
    'rule' => 'customTableMethod',
    'provider' => 'table'
]);

Si vous souhaitez ajouter un provider à tous les objets Validator créés plus tard, vous pouvez utiliser la méthode addDefaultProvider():

use Cake\Validation\Validator;

// En utilisant une instance d'objet.
Validator::addDefaultProvider('custom', $myObject);

// En utilisant un nom de classe. Les méthodes devront être static.
Validator::addDefaultProvider('custom', 'App\Model\Validation');

Vous pouvez utiliser le plugin Localized pour fournir des providers basés sur les pays. Avec ce plugin, vous pourrez valider les champs de models selon un pays, par exemple:

namespace App\Model\Table;

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

class PostsTable extends Table
{
    public function validationDefault(Validator $validator)
    {
        // Ajoute le provider au validator
        $validator->setProvider('fr', 'Localized\Validation\FrValidation');
        // utilise le provider dans une règle de validation de champ
        $validator->add('phoneField', 'myCustomRuleNameForPhone', [
            'rule' => 'phone',
            'provider' => 'fr'
        ]);

        return $validator;
    }
}

Le plugin localized utilise le code ISO à 2 lettres des pays pour la validation, par exemple en, fr, de.

Il y a quelques méthodes qui sont communes à toutes les classes, définies par l’interface ValidationInterface:

phone() pour vérifier un numéro de téléphone
postal() pour vérifier un code postal
personId() pour vérifier un ID d'une personne d'un pays

Règles de Validation Personnalisées¶

En plus de l’utilisation des méthodes venant des providers, vous pouvez aussi utiliser toute fonction appellable inclue de façon anonyme en règle de validation:

// Utilise une fonction globale
$validator->add('title', 'custom', [
    'rule' => 'validate_title',
    'message' => 'Le titre est invalide'
]);

// Utilise un tableau appelable qui n'est pas un provider
$validator->add('title', 'custom', [
    'rule' => [$this, 'method'],
    'message' => 'Le titre est invalide'
]);

// Utilise une closure
$extra = 'Des valeurs supplémentaires dont vous avez besoin dans la closure';
$validator->add('title', 'custom', [
    'rule' => function ($value, $context) use ($extra) {
        // Logique personnalisée qui retourne true/false
    },
    'message' => 'Le titre est invalide'
]);

// Utilisez une règle à partir d'un provider personnalisé
$validator->add('title', 'custom', [
    'rule' => 'customRule',
    'provider' => 'custom',
    'message' => 'Le titre n'est pas suffisamment unique'
]);

Les Closures ou les méthodes appelables vont recevoir 2 arguments lors de leur appel. Le premier va être la valeur pour le champ étant validé. Le second est un tableau contextuel contenant des données liées au processus de validation:

• data: Les données originelles passées à la méthode de validation, utile si vous planifiez de créer les règles comparant les valeurs.

• providers: La liste complète de règle des objets provider, utile si vous avez besoin de créer des règles complexes en appelant plusieurs providers.

• newRecord: Selon si l’appel de la validation est pour un nouvel enregistrement ou pour un enregistrement existant.

Si vous devez passer des données supplémentaires à vos méthodes de validation comme pour les ids des users, vous pouvez utiliser un provider dynamique personnalisé dans votre controller:

$this->Examples->validator('default')->provider('passed', [
    'count' => $countFromController,
    'userid' => $this->Auth->user('id')
]);

Ensuite assurez-vous que votre méthode de validation ait le deuxième paramètre de contexte:

public function customValidationMethod($check, array $context)
{
    $userid = $context['providers']['passed']['userid'];
}

Validation Conditionnelle¶

Lors de la définition des règles de validation, vous pouvez utiliser la clé on pour définir quand une règle de validation doit être appliquée. Si elle est laissée non définie, la règle va toujours être appliquée. Les autres valeurs valides sont create et update. L’utilisation d’une de ces valeurs va faire que la règle va s’appliquer seulement pour les opérations create ou update.

En plus, vous pouvez fournir une fonction appelable qui va déterminer si oui ou non, une règle particulière doit être appliquée:

$validator->add('picture', 'file', [
    'rule' => ['mimeType', ['image/jpeg', 'image/png']],
    'on' => function ($context) {
        return !empty($context['data']['show_profile_picture']);
    }
]);

Vous pouvez accéder aux autres données soumises depuis le formulaire via le tableau $context['data']. L’exemple ci-dessus va rendre la règle pour “picture” optionnelle selon si la valeur pour show_profile_picture est vide. Vous pouvez également utiliser la règle de validation uploadedFile pour créer des inputs optionnelles d’upload de fichiers:

$validator->add('picture', 'file', [
    'rule' => ['uploadedFile', ['optional' => true]],
]);

Les méthodes de validation allowEmpty(), notEmpty() et requirePresence() prennent également une fonction appelable en dernier argument, ce qui determine si oui ou non la règle doit être appliquée. Par exemple on peut autoriser parfois à un champ à être vide:

$validator->allowEmpty('tax', function ($context) {
    return !$context['data']['is_taxable'];
});

De la même façon, on peut vouloir qu’un champ soit peuplé quand certaines conditions sont vérifiées:

$validator->notEmpty('email_frequency', 'This field is required', function ($context) {
    return !empty($context['data']['wants_newsletter']);
});

Dans l’exemple ci-dessus, le champ email_frequency ne peut être laissé vide si l’utilisateur veut recevoir la newsletter.

De plus il est aussi possible de demander à ce qu’un champ soit présent sous certaines conditions seulement:

$validator->requirePresence('full_name', function ($context) {
    if (isset($context['data']['action'])) {
        return $context['data']['action'] === 'subscribe';
    }

    return false;
});
$validator->requirePresence('email');

Ceci demanderait à ce que le champ full_name soit présent seulement dans le cas où l’utilisateur veut créer une inscription, alors que le champ email est toujours requis puisqu’il serait aussi demandée lors de l’annulation d’une inscription.

Imbriquer des Validators¶

Lorsque vous validez des Formulaires Sans Models avec des données imbriquées, ou lorsque vous travaillez avec des modèles qui contiennent des données de type tableau, il est nécessaire de valider les données imbriquées dont vous disposez. CakePHP permet d’ajouter des validators sur des attributs spécifiques. Par exemple, imaginez que vous travailliez avec une base de données non relationnelle et que vous ayez besoin d’enregistrer un article et ses commentaires:

$data = [
    'title' => 'Meilleur article',
    'comments' => [
        ['comment' => '']
    ]
];

Pour valider les commentaires, vous utiliseriez un validator imbriqué:

$validator = new Validator();
$validator->add('title', 'not-blank', ['rule' => 'notBlank']);

$commentValidator = new Validator();
$commentValidator->add('comment', 'not-blank', ['rule' => 'notBlank']);

// Connecte les validators imbriqués.
$validator->addNestedMany('comments', $commentValidator);

// Prior to 3.9 use $validator->errors()
// Récupère toutes erreurs y compris celles des validators imbriqués.
$validator->validate($data);

Vous pouvez créer des “relations” 1:1 avec addNested() et des “relations” 1:N avec addNestedMany(). Avec ces deux méthodes, les erreurs des validators contribuerons aux erreurs du validator parent et influeront sur le résultat final.

Créer des Validators Ré-utilisables¶

Bien que définir des validators inline, là où ils sont utilisés, permet de donner un bon exemple de code, cela ne conduit pas à avoir des applications facilement maintenable. A la place, vous devriez créer des sous-classes de Validator pour votre logique de validation réutilisable:

// Dans src/Model/Validation/ContactValidator.php
namespace App\Model\Validation;

use Cake\Validation\Validator;

class ContactValidator extends Validator
{
    public function __construct()
    {
        parent::__construct();
        // Add validation rules here.
    }
}