ZF Zend Framework

Si toutes les données d'entrée passent les règles de validation la méthode isValid() retourne true. Si n'importe quelle donnée d'entrée n'est pas validée, ou est manquante, alors isValid() retourne false.

if ($input->isValid()) {
  echo "OK\n";
}

Cette méthode accepte aussi un paramètre facultatif nommant un champ particulier dans la donnée d'entrée. Ceci permet une vérification individuelle.

if ($input->isValid('month')) {
  echo "Le champ 'month' est OK\n";
}

if ($input->hasInvalid() || $input->hasMissing()) {
  $messages = $input->getMessages();
}

// getMessages() retourne la fusion de getInvalid() et getMissing()

if ($input->hasInvalid()) {
  $invalidFields = $input->getInvalid();
}

if ($input->hasMissing()) {
  $missingFields = $input->getMissing();
}

if ($input->hasUnknown()) {
  $unknownFields = $input->getUnknown();
}

Les valeurs retournées par getMessages() sont sous la forme d'un tableau dont la clé est la règle concernée et la valeur un tableau d'erreurs la concernant. Le tableau d'erreurs comporte en clé le nom de la règle déclarée qui peut être différent des noms de champs vérifiés par la règle.

La méthode getMessages() retourne la fusion des tableaux retournés par getInvalid() et getMissing(). Ces méthodes retournent une sous-partie des messages correspondant soit aux échecs de validation, soit aux champs qui sont déclarés requis mais qui sont absents.

La méthode getErrors() retourne un tableau associatif dont les clés sont des noms de règles et les valeurs associées des tableaux identifiants les erreurs. Les identifiants d'erreurs sont des chaînes constantes et figées, qui permettent d'identifier la raison de l'échec de validation, tandis que les messages associés sont eux-mêmes personnalisables. Voir Section 48.1.2, « Utilisation basique des validateurs » pour plus d'information.

Vous pouvez spécifier le message retourné par getMissing() en utilisant l'option "missingMessage", en tant qu'argument du constructeur de Zend_Filter_Input ou en utilisant l'option setOptions().

$options = array(
    'missingMessage' => "Field '%field%' is required"
);

$input = new Zend_Filter_Input($filters, $validators, $data, $options);

// alternative method:

$input = new Zend_Filter_Input($filters, $validators, $data);
$input->setOptions($options);

Le résultat de la méthode getUnknown() est un tableau associatif dont les clés sont des noms de champs et les valeurs sont les valeurs de champs correspondants. Les noms de champs sont dans ce cas les clés du tableau au lieu des noms de règles, car tout champs n'ayant pas de règles définies est considéré comme un champs inconnu.

Tout champ non invalide, non absent et non inconnu, est considéré comme valide. Vous pouvez alors en récupérer la valeur via un accesseur magique. Des méthodes classiques existent aussi, comme getEscaped() et getUnescaped().

$m = $input->month;                 // donnée échappée (accesseur magique)
$m = $input->getEscaped('month');   // donnée échapée
$m = $input->getUnescaped('month'); // donnée non échappée

Par défaut, récupérer un champ le passe automatiquement au travers de Zend_Filter_HtmlEntities. Ce comportement est considéré comme défaut pour un affichage en HTML. Le filtre HtmlEntities réduit de manière significative les risques de sécurité liés à un affichage involontaire d'une valeur.

	Note
	La méthode getUnescaped() retourne le champ brut, vous devez alors prendre vos précautions lors d'un affichage HTML. Attention aux problèmes de sécurité XSS (Cross Site Scripting).

Il est possible de définir un autre filtre comme filtre par défaut pour récupération des champs. Ceci se fait via le constructeur :

$options = array('escapeFilter' => 'StringTrim');
$input = new Zend_Filter_Input($filters, $validators, $data, $options);

Aussi, la méthode setDefaultEscapeFilter() fait la même chose :

$input = new Zend_Filter_Input($filters, $validators, $data);
$input->setDefaultEscapeFilter(new Zend_Filter_StringTrim());

Il est possible de passer une chaine, ou directement un objet instance de Zend_Filter.

Les filtres d'échappement comme vus juste précédemment, doivent être spécifiés de cette manière là. S'ils avaient été spécifiés comme filtres dans le tableau de Zend_Filter_Input, ils auraient pu faire échouer les validateurs, car les filtres sont exécutés AVANT les validateurs. Aussi, il n'aurait plus été possible de proposer la donnée de sortie de manière échappée et non échappée. Ainsi, déclarer un filtre d'échappement des données devrait toujours être effectué en utilisant la méthode setDefaultEscapeFilter(), et non pas le tableau $filters.

Comme il n'y a qu'une seule méthode getEscaped(), il ne peut y avoir qu'un seul filtre utilisé pour l'échappement. Il est cependant possible d'utiliser une chaine de filtre, ou encore de dériver la classe Zend_Filter_Input en créant d'autres méthodes de récupération de données, plus spécifiques.

Si le nom de la règle d'un filtre ou validateur est différente du champs auquel elle doit s'appliquer, vous pouvez spécifier le nom du champ avec la méta commande "fields".

Vous pouvez spécifier cette méta commande en utilisant la constante de classe Zend_Filter_Input::FIELDS.

$filters = array(
    'month' => array(
        'Digits',        // nom du filtre à l'index [0]
        'fields' => 'mo' // nom du champ à l'index ['fields']
    )
);

Dans l'exemple ci dessus, la règle applique le filtre "digits" au champ d'entrée nommé "mo". La chaine "month" devient alors un simple mnémonique pour cette règle, elle n'est pas utilisée comme nom de champ si celui-ci est renseigné avec la méta commande "fields", mais elle est utilisée comme nom de règle.

La valeur par défaut de la méta commande "fields" est l'index de la règle courante. Dans l'exemple ci dessus, si la méta commande "fields" est omise, la règle s'appliquerait au champ "month".

Un autre usage de la méta commande "fields" est pour préciser les champs aux filtres ou validateurs qui en attendent plusieurs en entrée. Si la méta commande "fields" est un tableau, alors le filtre/validateur correspondant aura comme argument la valeur des champs. Pensez au cas où l'on demande à l'utilisateur de saisir 2 fois son mot de passe. Imaginons un validateur qui prend en paramètre un tableau de champs et retourne true si les champs sont égaux.

$validators = array(
    'password' => array(
        'StringEquals',
        'fields' => array('password1', 'password2')
    )
);
// Invoque la classe Zend_Validate_StringEquals, en lui passant un tableau contenant les valeurs des 
// champs 'password1' and 'password2'.

Si la validation échoue, alors le nom de la règle ('password') est utilisé dans le retour de getInvalid(), et non pas les noms des champs spécifiés dans "fields".

Si la valeur de cette méta commande est "required", alors le champ doit exister dans la donnée d'entrée. Autrement, il est reporté comme étant un champ manquant.

Vous pouvez spécifier cette méta commande avec la constante de classe Zend_Filter_Input::PRESENCE.

$validators = array(
    'month' => array(
        'digits',
        'presence' => 'required'
    )
);

La valeur par défaut de cette méta commande est "optional".

Si le champ n'est pas présent dans la donnée d'entrée mais que celui-ci possède une méta commande "default", alors il obtient la valeur de la méta commande.

Vous pouvez spécifier cette méta commande avec la constante de classe Zend_Filter_Input::DEFAULT_VALUE.

La valeur de cette méta commande ne s'applique qu'avant l'invocation des validateurs, et seulement pour la règle en cours.

$validators = array(
    'month' => array(
        'digits',
        'default' => '1'
    )
);

// pas de valeur pour le champ 'month'
$data = array();

$input = new Zend_Filter_Input(null, $validators, $data);
echo $input->month; // affiche 1

Si vous utilisez pour une règle la méta commande FIELDS afin de définir un tableau de champs, vous pouvez définir un tableau pour la méta commande DEFAULT_VALUE. Les valeurs par défaut seront alors les clés correspondantes à chaque champ manquant. Si FIELDS définit de multiples champs mais que DEFAULT_VALUE est un scalaire, alors cette valeur scalaire sera utilisée pour tous les champs manquants.

Il n'y a pas de valeur par défaut pour cette méta commande.

Par défaut, si un champ existe dans le tableau d'entrées, alors les validateurs lui sont appliqués, même si la valeur de ce champs est la chaine vide (''). Ceci peut mener à des échecs de validation. Par exemple un validateur digits (chiffres) va échouer sur une chaine vide (laissant croire que la donnée puisse être composée de lettres).

Si la chaine vide doit pouvoir être considérée comme valide, utilisez la méta commande "allowEmpty" avec la valeur true.

Vous pouvez spécifier cette méta commande avec la constante de classe Zend_Filter_Input::ALLOW_EMPTY

$validators = array(
    'address2' => array(
        'Alnum',
        'allowEmpty' => true
    )
);

La valeur par défaut de cette méta commande est false.

Dans la cas peut commun ou vous déclarez une règle de validation avec aucun validateurs, mais que la méta commande "allowEmpty" est mise à false (le champ est considéré invalide s'il est vide), Zend_Filter_Input retourne un message d'erreur par défaut que vous pouvez récupérer avec la méthode getMessages(). Ce message se change grâce à l'option "notEmptyMessage" spécifiée en constructeur de Zend_Filter_Input ou via la méthode setOptions().

$options = array(
    'notEmptyMessage' => "Une valeur non vide est requise pour le champ '%field%'"
);

$input = new Zend_Filter_Input($filters, $validators, $data, $options);

// Autre méthode :

$input = new Zend_Filter_Input($filters, $validators, $data);
$input->setOptions($options);

Par défaut, si une règle possède plus d'un validateur, tous sont appliqués à la donnée d'entrée, et les éventuels messages d'erreur résultants sont la somme de tous les messages individuels des validateurs.

Si la valeur de la méta commande "breakChainOnFailure" est true, la chaine de validation va se terminer dès lors qu'un des validateur termine sur un échec.

Vous pouvez spécifier cette méta commande au moyen de la constante de classe Zend_Filter_Input::BREAK_CHAIN

$validators = array(
    'month' => array(
        'Digits',
        new Zend_Validate_Between(1,12),
        new Zend_Validate_GreaterThan(0),
        'breakChainOnFailure' => true
    )
);
$input = new Zend_Filter_Input(null, $validators);

La valeur par défaut de cette méta commande est false.

La classe Zend_Validate est plus flexible lors du bris de la chaine d'exécution, par rapport à Zend_Filter_Input. Avec Zend_Validate, vous pouvez mettre l'option pour casser la chaine indépendamment pour chaque validateur. Avec Zend_Filter_Input, la méta commande "breakChainOnFailure" s'applique à tous les validateurs dans la règle. Pour un usage plus flexible, créez votre propre chaine de validation comme ceci :

// Créer une chaine de validation avec un attribut breakChainOnFailure non uniforme
$chain = new Zend_Validate();
$chain->addValidator(new Zend_Validate_Digits(), true);
$chain->addValidator(new Zend_Validate_Between(1,12), false);
$chain->addValidator(new Zend_Validate_GreaterThan(0), true);

// Déclare la règloe de validation en faisant référence à la chaine de validation ci dessus
$validators = array(
    'month' => $chain
);
$input = new Zend_Filter_Input(null, $validators);

Vous pouvez attribuer des messages d'erreur pour chaque validateur d'une règle grâce à la méta commande 'messages'. La valeur de cette méta commande varie si vous avez plusieurs validateurs dans une règle ou si vous voulez spécifier le message pour une erreur particulière concernant un des validateurs.

Vous pouvez utiliser la constante de classe Zend_Filter_Input::MESSAGES pour définir cette méta commande.

Voici un exemple simple qui enregistre un message d'erreur pour une validateur de chiffres.

$validators = array(
    'month' => array(
        'digits',
        'messages' => 'Un mois doit être un chiffre'
    )
);

Si vous possédez plusieurs validateurs dont vous voulez personnaliser les messages d'erreur, utilisez alors un tableau comme valeur de la méta commande 'messages'.

Chaque élément de ce tableau s'applique à un validateur au même niveau d'index. Ainsi, un validateur à l'index n verra son message d'erreur modifié si vous utilisez l'index n dans le tableau de la méta commande. Il est ainsi possible d'autoriser certains validateurs à faire usage de leur message d'erreur par défaut, alors que d'autres posséderont un message personnalisé.

$validators = array(
    'month' => array(
        'digits',
        new Zend_Validate_Between(1, 12),
        'messages' => array(
            // utilise le message par défaut du vaidateur [0]
            // Affecte un nouveau message pour le validateur [1]
            1 => 'Une valeur de mois doit être comprise entre 1 et 12'
        )
    )
);

Si un des validateurs a plusieurs messages d'erreur, ils sont identifiés par une clé. Il existe différente clé dans chaque classe de validateur, ceux-ci servent d'identifiants pour les messages d'erreur. Chaque classe validateur définit aussi des constante pour les clés des messages d'erreur. Cette constante peut être utilisée dans la méta commande 'messages' en lui passant un tableau associatif plutôt qu'une chaine.

$validators = array(
    'month' => array(
        'digits', new Zend_Validate_Between(1, 12),
        'messages' => array(
            'Un mois ne peut contenir que des chiffres',
            array(
                Zend_Validate_Between::NOT_BETWEEN =>
                    'La valeur %value% du mois doit être comprise entre %min% et %max%',
                Zend_Validate_Between::NOT_BETWEEN_STRICT =>
                    'La valeur %value% du mois doit être comprise strictement entre %min% et %max%'
            )
        )
    )
);

Vous devriez vous référer à la documentation de chaque validateur afin de savoir s'il retourne plusieurs messages d'erreur, les clés de ces messages et les jetons utilisables dans les modèles de message.

Les valeurs par défaut des méta commandes "allowEmpty", "breakChainOnFailure", et "presence" peuvent être dictées pour toutes les règles en utilisant l'argument $options du constructeur de Zend_Filter_Input.

// Tous les champs acceptent des valeurs vides
$options = array('allowEmpty' => true);

// Il est possible d'écraser le comportement pour une règle précise.
$validators = array(
    'month' => array(
        'Digits',
        'allowEmpty' => false
    )
);

$input = new Zend_Filter_Input($filters, $validators, $data, $options);

Les méta commandes "fields", "messages", et "default" ne bénéficient pas d'un tel raccourci.