documentation/manual/fr/module_specs/Zend_Validate-WritingValidators.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- EN-Revision: 20799 -->
   3 <!-- Reviewed: no -->
   4 <sect1 id="zend.validate.writing_validators">
   5     <title>Écrire des validateurs</title>
   6
   7     <para>
   8         <classname>Zend_Validate</classname> fournit un ensemble de validateurs habituellement
   9         nécessaires, mais inévitablement, les développeurs souhaiteront écrire des validateurs sur
  10         mesure pour leurs besoins particuliers. La méthode d'écriture d'un validateur personnalisé
  11         est décrit dans cette section.
  12     </para>
  13
  14     <para>
  15         <classname>Zend_Validate_Interface</classname> définit trois méthodes,
  16         <methodname>isValid()</methodname>, <methodname>getMessages()</methodname>, et <methodname>getErrors()</methodname>, qui peuvent
  17         être implémentées par des classes d'utilisateur afin de créer les objets de validation sur
  18         mesure. Un objet qui implémente l'interface <classname>Zend_Validate_Interface</classname>
  19         peut être ajouté à une chaîne de validateur avec
  20         <methodname>Zend_Validate::addValidator()</methodname>. De tels objets peuvent également être
  21         employés avec <link
  22         linkend="zend.filter.input"><classname>Zend_Filter_Input</classname></link>.
  23     </para>
  24
  25     <para>
  26         Comme vous avez déjà pu déduire de la description ci-dessus de
  27         <classname>Zend_Validate_Interface</classname>, les classes de validation fournie avec Zend
  28         Framework retourne une valeur booléenne pour savoir si une valeur est validée ou non. Elles
  29         fournissent également des informations sur la raison pour laquelle la validation a échoué
  30         sur une valeur. La mise à disposition de ces raisons d'échec de validation peut être
  31         utilisée par une application dans différents buts, tels que fournir des statistiques pour
  32         l'analyse de la facilité d'utilisation.
  33     </para>
  34
  35     <para>
  36         La fonctionnalité de base de message d'échec de validation est implémentée dans
  37         <classname>Zend_Validate_Abstract</classname>. Pour inclure cette fonctionnalité en créant
  38         une classe de validation, étendez simplement <classname>Zend_Validate_Abstract</classname>.
  39         Dans la classe étendue vous implémenteriez la logique de la méthode <methodname>isValid()</methodname>
  40         et définiriez les variables de message et les modèles de message qui correspondent aux types
  41         d'échecs de validation qui peuvent se produire. Si une valeur ne passe pas vos essais de
  42         validation, alors <methodname>isValid()</methodname> devrait renvoyer <constant>FALSE</constant>. Si la valeur
  43         passe vos essais de validation, alors <methodname>isValid()</methodname> devrait renvoyer
  44         <constant>TRUE</constant>.
  45     </para>
  46
  47     <para>
  48         En général, la méthode <methodname>isValid()</methodname> ne devrait lever aucune exception,
  49         excepté où il est impossible de déterminer si la valeur d'entrée est valide. Quelques
  50         exemples de cas raisonnables pour lever une exception pourraient être si un fichier ne peut
  51         pas être ouvert, un serveur de <acronym>LDAP</acronym> ne pourraient pas être contacté, ou une connexion de
  52         base de données est indisponible, où quand une telle chose peut être exigée pour que le
  53         succès ou l'échec de validation soit déterminé.
  54     </para>
  55
  56     <example id="zend.validate.writing_validators.example.simple">
  57         <title>Création d'une simple classe de validation</title>
  58
  59         <para>
  60             L'exemple suivant démontre comment un validateur personnalisé très simple pourrait
  61             être écrit. Dans ce cas-ci les règles de validation sont simplement que la valeur
  62             d'entrée doit être une valeur en virgule flottante. <programlisting language="php"><![CDATA[
  63 class MonValidateur_Float extends Zend_Validate_Abstract
  64 {
  65     const FLOAT = 'float';
  66
  67     protected $_messageTemplates = array(
  68         self::FLOAT => "'%value%' n'est pas une valeur en virgule flottante"
  69     );
  70
  71     public function isValid($value)
  72     {
  73         $this->_setValue($value);
  74
  75         if (!is_float($value)) {
  76             $this->_error();
  77             return false;
  78         }
  79
  80         return true;
  81     }
  82 }
  83 ]]></programlisting> La classe définit un modèle pour son message unique d'échec de validation,
  84             qui inclut le paramètre magique intégré, <code>%value%</code>. L'appel à
  85             <methodname>_setValue()</methodname> prépare l'objet pour insérer automatiquement la valeur examinée
  86             dans le message d'échec, si la validation de la valeur échoue. L'appel à
  87             <methodname>_error()</methodname> trace la raison d'échec de validation. Puisque cette classe
  88             définit seulement un message d'échec, il n'est pas nécessaire de fournir à
  89             <methodname>_error()</methodname> le nom du modèle de message d'échec.
  90         </para>
  91     </example>
  92
  93     <example id="zend.validate.writing_validators.example.conditions.dependent">
  94         <title>Écriture d'une classe de validation ayant des conditions de dépendances</title>
  95
  96         <para>
  97             L'exemple suivant démontre un ensemble plus complexe de règles de validation, où
  98             on l'exige que la valeur d'entrée doit être numérique et dans la plage des valeurs
  99             limites minimum et maximum. Une valeur d'entrée ferait échouer la validation pour
 100             exactement une des raisons suivantes : <itemizedlist>
 101                     <listitem>
 102                         <para>La valeur d'entrée n'est pas numérique.</para>
 103                     </listitem>
 104
 105                     <listitem>
 106                     <para>
 107                         La valeur d'entrée est inférieure que la valeur permise
 108                         minimum.
 109                     </para>
 110                 </listitem>
 111
 112                 <listitem>
 113                     <para>
 114                         La valeur d'entrée est supérieure que la valeur permise
 115                         maximum.
 116                     </para>
 117                 </listitem>
 118                 </itemizedlist>
 119             </para>
 120
 121         <para>
 122             Ces raisons d'échec de validation sont alors traduites dans les définitions de la
 123             classe : <programlisting language="php"><![CDATA[
 124 class MonValidateur_NumericBetween extends Zend_Validate_Abstract
 125 {
 126     const MSG_NUMERIC = 'msgNumeric';
 127     const MSG_MINIMUM = 'msgMinimum';
 128     const MSG_MAXIMUM = 'msgMaximum';
 129
 130     public $minimum = 0;
 131     public $maximum = 100;
 132
 133     protected $_messageVariables = array(
 134         'min' => 'minimum',
 135         'max' => 'maximum'
 136     );
 137
 138     protected $_messageTemplates = array(
 139         self::MSG_NUMERIC => "'%value%' n'est pas numérique",
 140         self::MSG_MINIMUM => "'%value%' doit être supérieure à '%min%'",
 141         self::MSG_MAXIMUM => "'%value%' doit être inférieure à '%max%'"
 142     );
 143
 144     public function isValid($value)
 145     {
 146         $this->_setValue($value);
 147
 148         if (!is_numeric($value)) {
 149             $this->_error(self::MSG_NUMERIC);
 150             return false;
 151         }
 152
 153         if ($value < $this->minimum) {
 154             $this->_error(self::MSG_MINIMUM);
 155             return false;
 156         }
 157
 158         if ($value > $this->maximum) {
 159             $this->_error(self::MSG_MAXIMUM);
 160             return false;
 161         }
 162
 163         return true;
 164     }
 165 }
 166 ]]></programlisting> Les propriétés publiques <varname>$minimum</varname> et <varname>$maximum</varname> ont
 167             été établies pour fournir les frontières minimum et maximum d'une valeur pour qu'elle
 168             soit validée avec succès. La classe définit également deux variables de message qui
 169             correspondent aux propriétés publiques et permettent que <code>min</code> et
 170             <code>max</code> soient employés dans des modèles de message en tant que paramètres
 171             magiques, comme avec <code>value</code>.
 172         </para>
 173
 174         <para>
 175             Noter que si n'importe quel élément de la validation vérifié dans
 176             <methodname>isValid()</methodname> échoue, un message approprié d'échec est préparé, et la méthode
 177             renvoie immédiatement <constant>FALSE</constant>. Ces règles de validation sont donc
 178             séquentiellement dépendantes. C'est-à-dire, que si un essai échoue, il n'y a aucun
 179             besoin d'examiner les règles suivantes de validation. Ce besoin peut exister, cependant.
 180             L'exemple suivant illustre comment écrire une classe ayant des règles indépendantes de
 181             validation, où l'objet de validation peut renvoyer des raisons multiples pour lesquelles
 182             une tentative particulière de validation a échoué.
 183         </para>
 184     </example>
 185
 186     <example id="zend.validate.writing_validators.example.conditions.independent">
 187         <title>Validation avec des conditions indépendantes, avec raisons multiples
 188         d'échec</title>
 189
 190         <para>
 191             Considérons l'écriture d'une classe de validation pour le contrôle de résistance
 192             d'un mot de passe - quand un utilisateur est requis afin de choisir un mot de passe qui
 193             respecte certains critères pour aider à la sécurisation des comptes d'utilisateur.
 194             Supposons que les critères de sécurité de mot de passe imposent que le mot de passe :
 195             <itemizedlist>
 196                     <listitem>
 197                         <para>est au moins une longueur de 8 caractères,</para>
 198                     </listitem>
 199
 200                     <listitem>
 201                         <para>contient au moins une lettre majuscule,</para>
 202                     </listitem>
 203
 204                     <listitem>
 205                         <para>contient au moins une lettre minuscule,</para>
 206                     </listitem>
 207
 208                     <listitem>
 209                         <para>et contient au moins un caractère de chiffre.</para>
 210                     </listitem>
 211                 </itemizedlist>
 212             </para>
 213
 214         <para>
 215             La classe suivante implémente ces critères de validation : <programlisting
 216             role="php"><![CDATA[
 217 class MonValidateur_PasswordStrength extends Zend_Validate_Abstract
 218 {
 219     const LENGTH = 'length';
 220     const UPPER  = 'upper';
 221     const LOWER  = 'lower';
 222     const DIGIT  = 'digit';
 223
 224     protected $_messageTemplates = array(
 225         self::LENGTH =>
 226             "'%value%' doit avoir une longueur d'au moins 8 caractères",
 227         self::UPPER  =>
 228             "'%value%' doit contenir au moins une lettre majuscule",
 229         self::LOWER  =>
 230             "'%value%' doit contenir au moins une lettre minuscule",
 231         self::DIGIT  =>
 232             "'%value%' doit contenir au moins un chiffre"
 233     );
 234
 235     public function isValid($value)
 236     {
 237         $this->_setValue($value);
 238
 239         $isValid = true;
 240
 241         if (strlen($value) < 8) {
 242             $this->_error(self::LENGTH);
 243             $isValid = false;
 244         }
 245
 246         if (!preg_match('/[A-Z]/', $value)) {
 247             $this->_error(self::UPPER);
 248             $isValid = false;
 249         }
 250
 251         if (!preg_match('/[a-z]/', $value)) {
 252             $this->_error(self::LOWER);
 253             $isValid = false;
 254         }
 255
 256         if (!preg_match('/\d/', $value)) {
 257             $this->_error(self::DIGIT);
 258             $isValid = false;
 259         }
 260
 261         return $isValid;
 262     }
 263 }
 264 ]]></programlisting>Noter que les quatre critères d'essais dans <methodname>isValid()</methodname> ne
 265             renvoient pas immédiatement <constant>FALSE</constant>. Ceci permet à la classe de validation de
 266             fournir toutes les raisons pour lesquelles le mot de passe d'entrée n'a pas réussi à
 267             remplir les conditions de validation. Si, par exemple, un utilisateur entre la chaîne
 268             "<code>#$%</code>" comme mot de passe, <methodname>isValid()</methodname> entraînera que les quatre
 269             messages d'échec de validation seront retournés lors de l'appel suivant à
 270             <methodname>getMessages()</methodname>.
 271         </para>
 272     </example>
 273 </sect1>