L'utilisation des validateurs est assez simple. Il existe de multiples méthodes pour ajouter et manipuler les validateurs.

• isValid($files = null) : vérifie le(s) fichier(s) fourni(s) avec tout le jeu de validateurs paramétrés. $files peut être soit un vrai nom de fichier, soit des noms d'éléments de formulaire ou des noms de fichiers temporaires.

• addValidator($validator, $breakChainOnFailure, $options = null, $files = null) : ajoute le validateur à la pile des validateurs (optionnellement seul le(s) fichier(s) spécifié(s)). $validator peut être soit une instance d'un validateur réel, ou un nom court spécifiant le validateur (par exemple, "Count").

• addValidators(array $validators, $files = null) : ajoute les validateurs à la pile des validateurs. Chaque entrée peut être soit une paire type/options, ou un tableau avec la clé "validator" spécifiant le validateur (tous les autres options seront considérées comme des options du validateur au moment de l'instanciation).

• setValidators(array $validators, $files = null) : surcharge les validateurs existants avec les validateurs spécifiés. Les validateurs doivent respecter la même syntaxe que addValidators().

• hasValidator($name) : indique si un validateur est enregistré.

• getValidator($name) : retourne un validateur préalablement enregistré.

• getValidators($files = null) : retourne les validateurs enregistrés ; si $files est fourni, retourne les validateurs pour ce fichier en particulier ou pour tous les fichiers.

• removeValidator($name) : enlève le validateur préalablement enregistré.

• clearValidators() : efface tous les validateurs.

Généralement vous devriez simplement utiliser la méthode addValidators(), qui peut être appelée plusieurs fois.

Note: Notez que même si l'ajout du même validateur plusieurs fois est autorisé, faire ceci peut entraîner des problèmes si vous utilisez différentes options pour le même validateur.

Et pour finir vous pouvez tout simplement vérifier le(s) fichier(s) en appelant isValid().

Note: Notez que isValid() sera automatiquement appelé quand vous recevez les fichiers et qu'il n'a pas été appelé auparavant.

Quand une validation a échouée, c'est probablement intéressant d'avoir des informations sur les problèmes rencontrés. A cette fin, vous pouvez utiliser la méthode getMessages() qui retourne tous les messages de validation sous la forme d'un tableau, getErrors() qui retourne tous les codes d'erreurs et hasErrors() qui retourne TRUE dès qu'une erreur de validation est rencontrée.

Le validateur Count vérifie le nombre de fichiers fournis. Il supporte les clés d'options suivantes :

• min : paramètre le nombre minimum de fichiers à transférer.

  Note: Attention : quand vous utilisez cette option vous devez donner le nombre minimum au moment où vous appelez ce validateur la première fois ; sinon vous aurez une erreur en retour.
  

  Avec cette option vous pouvez définir le nombre de fichiers que vous souhaitez recevoir.

• max : paramètre le nombre maximum de fichiers à transférer.

  Avec cette option vous pouvez limiter le nombre de fichiers que vous acceptez mais vous permet aussi de détecter une possible attaque quand plus de fichiers, que votre formulaire n'en définit, sont fournis.

Vous pouvez initialiser ce validateur avec une chaîne ou un entier, la valeur sera utilisée en tant que max. Mais vous pouvez aussi utiliser les méthodes setMin() et setMax() pour paramétrer ces options plus tard et getMin() et getMax() pour les récupérer.

Note: Notez que ce validateur stocke le nombre de fichiers vérifiés en interne. Le fichier qui excédera le maximum sera retourné en tant qu'erreur.

Le validateur Crc32 vérifie le contenu du fichier transféré en le hachant. Ce validateur utilise l'extension de hachage de PHP avec l'algorithme crc32. Il supporte les options suivantes :

• * : vous pouvez paramétrer n'importe quelle clé ou utiliser un tableau numérique. Les valeurs seront utilisées pour vérifier la valeur de hachage.

  Vous pouvez paramétrer de multiples hachages en utilisant différentes clés. Chacun sera vérifié et seulement si tous échouent, la validation elle-même échouera.

Le validateur ExcludeExtension vérifie l'extension des fichiers fournis. Il supporte les options suivantes :

• * : vous pouvez paramétrer n'importe quelle clé ou utiliser un tableau numérique. Les valeurs seront utilisées en tant qu'extensions à vérifier que le fichier n'utilise pas.

• case : paramètre une validation qui tient compte de la casse. Par défaut, ce n'est pas sensible à la casse. Notez que cette clé est utilisée pour toutes les extensions.

Ce validateur accepte des extensions multiples soit sous la forme d'une chaîne utilisant le caractère virgule (",") comme séparateur ou sous la forme d'un tableau. Vous pouvez aussi utiliser les méthodes setExtension(), addExtension(), et getExtension() pour paramétrer et récupérer les extensions.

Dans certains cas, il est utile vérifier aussi la casse. A cette fin le constructeur autorise un second paramètre $case qui, s'il est réglé à TRUE, validera l'extension en vérifiant aussi la casse.

Note: Notez que ce validateur ne vérifie que l'extension de fichier. Il ne vérifie pas le type MIME réel du fichier.

Le validateur ExcludeMimeType vérifie le type MIME des fichiers transférés. Il supporte les options suivantes :

• * : vous pouvez paramétrer n'importe quelle clé ou utiliser un tableau numérique. Paramètre le type MIME à vérifier.

  Avec cette option vous pouvez définir le(s) type(s) MIME que vous souhaitez exclure.

• headerCheck : si spécifié à TRUE, cette option va vérifier l'information HTTP concernant le type de fichier quand les extensions fileInfo ou mimeMagic ne seront pas trouvées. La valeur par défaut de cette option est FALSE.

Ce validateur accepte des types MIME multiples soit sous la forme d'une chaîne utilisant le caractère virgule (",") comme séparateur ou sous la forme d'un tableau. Vous pouvez aussi utiliser les méthodes setMimeType(), addMimeType(), et getMimeType() pour paramétrer et récupérer les types MIME.

L'exemple ci-dessus montre qu'il est aussi possible de limiter le type MIME accepté à un groupe de type MIME. Pour refuser toutes les images utilisez simplement "image" en tant que type MIME. Ceci peut être appliqué à tous les groupes de type MIME comme "image", "audio", "video", "text" et plus encore.

Note: Notez que refuser un groupe de type MIME refusera tous les membres de ce groupe même si ce n'est pas votre intention. Par exemple quand vous refusez "image", vous refusez donc "image/jpeg" ou "image/vasa". Quand vous n'êtes pas sûr de vouloir refuser tous les types, vous devriez définir individuellement les types MIME plutôt que le groupe complet.

Le validateur Exists l'existence des fichiers fournis. Il supporte les options suivantes :

• * : vous pouvez paramétrer n'importe quelle clé ou utiliser un tableau numérique. Vérifie si le fichier existe dans le dossier fourni.

Ce validateur accepte des extensions multiples soit sous la forme d'une chaîne utilisant le caractère virgule (",") comme séparateur ou sous la forme d'un tableau. Vous pouvez aussi utiliser les méthodes setDirectory(), addDirectory(), et getDirectory() pour paramétrer et récupérer les extensions.

Note: Notez que ce validateur vérifie si le fichier existe dans tous les dossiers fournis. La validation échoue si le fichier est manquant dans l'un des dossiers.

Le validateur Extension vérifie l'=es extensions des fichiers qui ont été fournis. Il supporte les options suivantes :

• * : vous pouvez paramétrer n'importe quelle clé ou utiliser un tableau numérique. Paramètre l'extension à vérifier.

• case : paramètre une validation sensible à la casse. Par défaut, la validation n'est pas sensible à la casse. Notez que cette clé est utilisée pour toutes les extensions.

Ce validateur accepte des extensions multiples soit sous la forme d'une chaîne utilisant le caractère virgule (",") comme séparateur ou sous la forme d'un tableau. Vous pouvez aussi utiliser les méthodes setExtension(), addExtension(), et getExtension() pour paramétrer et récupérer les extensions.

Dans certains cas, il est utile vérifier aussi la casse. A cette fin le constructeur autorise un second paramètre $case qui, s'il est réglé à TRUE, validera l'extension en vérifiant aussi la casse.

Note: Notez que ce validateur ne vérifie que l'extension de fichier. Il ne vérifie pas le type MIME réel du fichier.

Le validateur FilesSize vérifie le poids total de tous les fichiers transférés. Il supporte les options suivantes :

• min : paramètre le poids minimum de tous les fichiers.

  Avec cette option vous pouvez définir le poids minimum de tous les fichiers que vous souhaitez transférer.

• max : paramètre le poids maximum de tous les fichiers.

  Avec cette option vous pouvez limiter le poids total des fichiers qui doivent être transférés, mais pas la taille individuelle de chaque fichier.

• bytestring : définit si un échec est retourné avec un taille plus facilement lisible pour l'utilisateur, ou avec une taille de fichier brute.

  Avec cette option vous pouvez en fait définir si l'utilisateur récupérera "10864" ou "10MB". La valeur par défaut est TRUE qui retournera "10MB".

Vous pouvez initialiser seulement avec une chaîne qui sera utilisée en tant que max. Mais vous pouvez aussi utiliser les méthodes setMin() et setMax() pour paramétrer ces options plus tard et getMin() et getMax() pour les récupérer.

La taille elle-même est acceptée en notation SI comme sur la plupart des systèmes d'exploitation. Au lieu de 20000 octets (NdT. : "bytes" en anglais), vous pouvez utiliser 20kB. Toutes les unités sont converties en utilisant 1024 comme valeur de base. Les unités suivantes sont acceptées : kB, MB, GB, TB, PB et EB. Comme mentionné précédemment vous devez noter que 1kB équivaut à 1024 octets.

Note: Notez que ce validateur stocke le poids des fichiers vérifiés en interne. Le fichier qui excédera le poids maximum sera retourné en tant qu'erreur.

Le validateur ImageSize vérifie la taille des images. Il supporte les options suivantes :

• minheight : paramètre la hauteur minimum d'une image.

• maxheight : paramètre la hauteur maximum d'une image.

• minwidth : paramètre la largeur minimum d'une image.

• maxwidth : paramètre la largeur maximum d'une image.

Vous pouvez aussi utiliser les méthodes setImageMin() et setImageMax() pour régler les valeurs minimum et maximum plus tard et getMin() et getMax() pour les récupérer.

Par commodité, il existe aussi les méthodes setImageWidth et setImageHeight qui paramètrent la largeur et la hauteur minimum et maximum. Bien sûr les méthodes associées getImageWidth et getImageHeight sont aussi disponibles.

Pour désactiver la validation d'une dimension, ne paramétrez pas l'option correspondante.

Le validateur IsCompressed vérifie si un fichier transféré est une archive compressée comme zip ou arc. Ce validateur est basée sur le validateur MimeType et supportent les mêmes méthodes et options. Vous pouvez limiter ce validateur à des types de compression particuliers avec les méthodes décrites ci-dessous.

Note: Notez qu'il n'y a pas de vérification si vous paramétrez un type de fichier qui n'est pas un type de compression. Ainsi il est donc possible de définir que les fichiers gif sont acceptés par ce validateur même si ce n'est pas logique.

Le validateur IsImage vérifie si un fichier transféré est une image comme gif ou jpeg. Ce validateur est basée sur le validateur MimeType et supportent les mêmes méthodes et options. Vous pouvez limiter ce validateur à des types d'image particuliers avec les méthodes décrites ci-dessous.

Note: Notez qu'il n'y a pas de vérification si vous paramétrez un type de fichier qui n'est pas un type d'image. Ainsi il est donc possible de définir que les fichiers zip sont acceptés par ce validateur même si ce n'est pas logique.

Le validateur Hash vérifie le contenu du fichier transféré en le hachant. Ce validateur utilise l'extension de hachage de PHP. Il supporte les options suivantes :

• * : vous pouvez paramétrer n'importe quelle clé ou utiliser un tableau numérique. Paramètre la valeur de hachage qui doit être vérifié.

  Vous pouvez paramétrer de multiples hachages en les fournissant sous la forme d'un tableau. Chacun sera vérifié et seulement si tous échouent, la validation elle-même échouera.

• algorithm : paramètre l'algorithme à utiliser pour hacher le contenu.

  Vous pouvez paramétrer de multiples algorithmes en utilisant la méthode addHash() plusieurs fois.

Note: Ce validateur supporte environ 34 algorithmes de hachage différents. Les plus connus sont "crc32", "md5" and "sha1". Si vous souhaitez connaître les autres algorithmes, voyez » la méthode hash_algos de PHP.

Le validateur Md5 vérifie le contenu du fichier transféré en le hachant. Ce validateur utilise l'extension de hachage de PHP avec l'algorithme md5. Il supporte les options suivantes :

• * : vous pouvez paramétrer n'importe quelle clé ou utiliser un tableau numérique. Paramètre la valeur de hachage qui doit être vérifié.

  Vous pouvez paramétrer de multiples hachages en les fournissant sous la forme d'un tableau. Chacun sera vérifié et seulement si tous échouent, la validation elle-même échouera.

Le validateur MimeType vérifie le type MIME des fichiers transférés. Il supporte les options suivantes :

• * : vous pouvez paramétrer n'importe quelle clé ou utiliser un tableau numérique. Paramètre le type MIME à contrôler.

  Avec cette option vous pouvez définir le type MIME des fichiers qui seront acceptés.

• headerCheck : si spécifié à TRUE, cette option va vérifier l'information HTTP concernant le type de fichier quand les extensions fileInfo ou mimeMagic ne seront pas trouvées. La valeur par défaut de cette option est FALSE.

• magicfile : le magicfile qui sera utilisé.

  Avec cette option vous pouvez définir le magicfile à utiliser. Quand il n'est pas utilisé ou vide, la constante MAGIC sera utilisée. Cette option est disponible à partir de la version 1.7.1 de Zend Framework.

Ce validateur accepte des types MIME multiples soit sous la forme d'une chaîne utilisant le caractère virgule (",") comme séparateur ou sous la forme d'un tableau. Vous pouvez aussi utiliser les méthodes setMimeType(), addMimeType(), et getMimeType() pour paramétrer et récupérer les types MIME.

Vous pouvez aussi paramétrer le magicfile qui sera utilisé par fileinfo avec l'option magicfile. De plus il existe les méthodes setMagicFile() et getMagicFile() qui permettent de paramétrer ou récupérer plus tard le paramètre magicfile. Ces méthodes sont disponibles à partir de la version Zend Framework 1.7.1.

L'exemple ci-dessus montre qu'il est aussi possible de limiter le type MIME accepté à un groupe de type MIME. Pour autoriser toutes les images utilisez simplement "image" en tant que type MIME. Ceci peut être appliqué à tous les groupes de type MIME comme "image", "audio", "video", "text" et plus encore.

Note: Notez qu'autoriser un groupe de type MIME acceptera tous les membres de ce groupe même si votre application ne les supporte pas. Par exemple quand vous autorisez "image", vous autorisez donc "image/xpixmap" ou "image/vasa", ce qui peut être problématique. Quand vous n'êtes pas sûr que votre application supporte tous les types, vous devriez définir individuellement les types MIME plutôt que le groupe complet.

Note: Ce composant utilise l'extension fileinfo si elle est disponible. Si ce n'est pas le cas, il utilisera alors la fonction mime_content_type. Et si l'appel de fonction échoue, il utilisera le type MIME fourni par HTTP.
Vous devez cependant être averti de possibles problèmes de sécurité si, ni fileinfo, ni mime_content_type ne sont disponibles : le type MIME fourni pas HTTP n'étant pas sécurisé et pouvant être facilement manipulé.

Le validateur NotExists l'existence des fichiers fournis. Il supporte les options suivantes :

• * : vous pouvez paramétrer n'importe quelle clé ou utiliser un tableau numérique. Vérifie si le fichier n'existe pas dans le dossier fourni.

Ce validateur accepte des extensions multiples soit sous la forme d'une chaîne utilisant le caractère virgule (",") comme séparateur ou sous la forme d'un tableau. Vous pouvez aussi utiliser les méthodes setDirectory(), addDirectory(), et getDirectory() pour paramétrer et récupérer les extensions.

Note: Notez que ce validateur vérifie si le fichier n'existe dans aucun des dossiers fournis. La validation échoue si le fichier existe dans l'un des dossiers.

Le validateur Sha1 vérifie le contenu du fichier transféré en le hachant. Ce validateur utilise l'extension de hachage de PHP avec l'algorithme sha1. Il supporte les options suivantes :

• * : vous pouvez paramétrer n'importe quelle clé ou utiliser un tableau numérique. Paramètre la valeur de hachage qui doit être vérifié.

  Vous pouvez paramétrer de multiples hachages en les fournissant sous la forme d'un tableau. Chacun sera vérifié et seulement si tous échouent, la validation elle-même échouera.

Le validateur Size vérifie le poids d'un fichier unique. Il supporte les options suivantes :

• min : paramètre le poids minimum du fichier.

• max : paramètre le poids maximum du fichier.

• bytestring : définit si un échec est retourné avec un taille plus facilement lisible pour l'utilisateur, ou avec une taille de fichier brute.

  Avec cette option vous pouvez en fait définir si l'utilisateur récupérera "10864" ou "10MB". La valeur par défaut est TRUE qui retournera "10MB".

Vous pouvez initialiser seulement avec une chaîne qui sera utilisée en tant que max. Mais vous pouvez aussi utiliser les méthodes setMin() et setMax() pour paramétrer ces options plus tard et getMin() et getMax() pour les récupérer.

Quand seule une chaîne est fournie, elle est utilisée en tant que max. Mais vous pouvez aussi utiliser les méthodes setMin() et setMax() pour paramétrer ces options plus tard et getMin() et getMax() pour les récupérer.

La taille elle-même est acceptée en notation SI comme sur la plupart des systèmes d'exploitation. Au lieu de 20000 octets, vous pouvez utiliser 20kB. Toutes les unités sont converties en utilisant 1024 comme valeur de base. Les unités suivantes sont acceptées : kB, MB, GB, TB, PB et EB. Comme mentionné précédemment vous devez noter que 1kB équivaut à 1024 octets.

Le validateur WordCount vérifie le nombre de mots à l'intérieur des fichiers fournis. Il supporte les options suivantes :

• min : spécifie le nombre de mots minimum qui doivent être trouvés.

• max : spécifie le nombre de mots maximum qui doivent être trouvés.

Si vous initialisez ce validateur avec une chaîne ou un entier, la valeur sera utilisée en tant que max. Mais vous pouvez aussi utiliser les méthodes setMin() et setMax() pour paramétrer ces options plus tard et getMin() et getMax() pour les récupérer.