<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 21829 -->
<!-- Reviewed: no -->
<sect1 id="zend.filter.input">
    <title>Zend_Filter_Input</title>

    <para>
        <classname>Zend_Filter_Input</classname> propose une manière générique de déclarer des
        filtres et des validateurs, de les appliquer comme un ensemble, à une collection de données,
        et enfin de récupérer ces données validées et filtrées. Les valeurs sont retournées
        échappées par défaut, pour une meilleure sécurité relative au HTML.
    </para>

    <para>
        Considérez cette classe comme une boite noire dans laquelle va passer une variable de
        collection, typiquement un tableau <acronym>PHP</acronym> représentant des données externes. Les données
        arrivent dans l'application depuis une source externe, donc potentiellement dangereuse,
        comme des variables de requête <acronym>HTTP</acronym>, d'un service Web, d'un fichier, ou autre. L'application
        demande alors à la boite noire l'accès à une ou plusieurs données, en spécifiant sous quelle
        forme elle s'attend à voir la donnée. La boite inspecte alors la donnée pour la valider, et
        ne la laisse sortir que si celle-ci respecte les règles que l'application demande. Grâce à
        une simple classe et un mécanisme facile, ceci encourage les développeurs à prendre des
        bonnes pratiques au regard de la sécurité des applications.
    </para>

    <itemizedlist>
        <listitem>
            <para>
                <emphasis>Les filtres</emphasis> transforment les entrées en supprimant ou
                changeant des caractères dans leurs valeurs. Le but est de "normaliser" les valeurs
                jusqu'à ce qu'elles correspondent aux attentes exigées. Par exemple si une chaine
                d'entiers (numériques) est attendue, et que la donnée d'entrée est "abc123", alors
                en sortie du filtre la valeur "123" sera proposée.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>Les validateurs</emphasis> vérifient la validité d'une donnée, sans
                la transformer. Si la validation échoue, le validateur renseignera sur les problèmes
                rencontrés.
            </para>
        </listitem>

        <listitem>
            <para>
                <emphasis>Les échappeurs</emphasis> transforment une valeur en supprimant
                certains caractères qui peuvent avoir une signification spéciale dans un contexte
                donné. Par exemple, les caractères '&lt;' et '&gt;' délimitent les balises HTML,
                ainsi si une donnée contenant ces caractères est affichée directement dans un
                navigateur, la sortie peut être corrompue et mener à des problèmes de sécurité.
                Échapper les caractères est le fait de leur enlever toute signification spéciale,
                ils seront traités comme des caractères tout à fait normaux.
            </para>
        </listitem>
    </itemizedlist>

    <para>Pour utiliser <classname>Zend_Filter_Input</classname>&#160;:</para>

    <orderedlist numeration="arabic">
        <listitem>
            <para>Déclarez des règles de filtre et de validateur</para>
        </listitem>

        <listitem>
            <para>
                Ajoutez des filtres et des validateurs dans
                <classname>Zend_Filter_Input</classname>
            </para>
        </listitem>

        <listitem>
            <para>Passer les données d'entrée à <classname>Zend_Filter_Input</classname></para>
        </listitem>

        <listitem>
            <para>Récupérez les données valides et/ou des rapports divers</para>
        </listitem>
    </orderedlist>

    <para>Les sections suivantes expliquent comment manipuler la classe.</para>

    <sect2 id="zend.filter.input.declaring">
        <title>Déclarer des règles de filtre et de validateur</title>

        <para>
            Avant de créer une instance de <classname>Zend_Filter_Input</classname>, déclarez
            deux tableaux de règles pour les filtres, et les validateurs. Ce tableau associatif met
            en relation le champ de la donnée dans le tableau originel et le nom du
            filtre/validateur.
        </para>

        <para>
            L'exemple qui suit indique que le champ "month" est filtré par un
            <classname>Zend_Filter_Digits</classname>, et le champ "account" est filtré par un
            <classname>Zend_Filter_StringTrim</classname>. Puis, une règle de validation
            s'appliquera au champ "account", celui-ci sera validé s'il ne contient que des
            caractères alphabétiques (lettres).
        </para>

        <programlisting language="php"><![CDATA[
$filters = array(
    'month'   => 'Digits',
    'account' => 'StringTrim'
);

$validators = array(
    'account' => 'Alpha'
);
]]></programlisting>

        <para>
            Chaque clé du tableau <varname>$filters</varname> représente une donnée à laquelle sera
            appliqué le filtre correspondant en valeur de tableau.
        </para>

        <para>Le filtre peut être déclaré selon différents formats&#160;:</para>

        <itemizedlist>
            <listitem>
                <para>
                    Une chaine de caractères, qui sera transformée en nom de classe.
                    <programlisting language="php"><![CDATA[
$validators = array(
    'month'   => 'Digits',
);
]]></programlisting>
                </para>
            </listitem>

            <listitem>
                <para>
                    Un objet instance d'une classe implémentant
                    <classname>Zend_Filter_Interface</classname> ou
                    <classname>Zend_Validate_Interface</classname>.
                    <programlisting language="php"><![CDATA[
$digits = new Zend_Validate_Digits();

$validators = array(
    'month'   => $digits
);
]]></programlisting>
                </para>
            </listitem>

            <listitem>
                <para>
                    Un tableau, pour déclarer une chaine de filtres ou validateurs. Les
                    éléments de ce tableau peuvent être des chaînes représentant des noms de classe,
                    ou des objets directement. Aussi, vous pouvez utiliser comme valeur un tableau
                    contenant le nom du filtre ou validateur, et d'éventuels arguments à passer à
                    son constructeur.
                    <programlisting language="php"><![CDATA[
$validators = array(
    'month'   => array(
        'Digits',                // chaine
        new Zend_Validate_Int(), // objet
        array('Between', 1, 12)  // chaine + arguments pour le constructeur
    )
);
]]></programlisting>
                </para>
            </listitem>
        </itemizedlist>

        <note>
            <para>
                Si vous choisissez de déclarer un filtre ou validateur avec des arguments de
                constructeur, alors la règle générale devra elle aussi utiliser un tableau pour
                sa/ses déclarations de filtres ou validateurs.
            </para>
        </note>

        <para>
            Un joker "<code>*</code> " peut être utilisé dans le tableau des filtres ou des
            validateurs. Ceci aura pour effet d'appliquer le validateur ou le filtre à toutes les
            entrées du tableau traité. Notez que l'ordre des filtres / validateurs est important
            dans le tableau, car il seront appliqués dans l'ordre dans lequel ils ont été
            déclarés.
        </para>

        <programlisting language="php"><![CDATA[
$filters = array(
    '*'     => 'StringTrim',
    'month' => 'Digits'
);
]]></programlisting>
    </sect2>

    <sect2 id="zend.filter.input.running">
        <title>Créer le processeur de filtres et validateurs</title>

        <para>
            Lorsque vos tableaux de filtres et de validateurs ont été construits, passez les
            en argument au constructeur de <classname>Zend_Filter_Input</classname>. Ceci va
            retourner un objet pré-configuré qui saura alors traiter tout un tableau de données
            d'entrée.
        </para>

        <programlisting language="php"><![CDATA[
$input = new Zend_Filter_Input($filters, $validators);
]]></programlisting>

        <para>
            Les données d'entrée peuvent être placées dans le troisième paramètre du
            constructeur. Ces données possèdent en clé leur nom, et en valeur leur valeur.
            Typiquement, les tableaux superglobaux <varname>$_GET</varname> et <varname>$_POST</varname>
            possèdent la structure idéale pour passer dans
            <classname>Zend_Filter_Input</classname>.
        </para>

        <programlisting language="php"><![CDATA[
$data = $_GET;
$input = new Zend_Filter_Input($filters, $validators, $data);
]]></programlisting>

        <para>
            Aussi, la méthode <methodname>setData()</methodname> accepte les données de la même manière
            que le troisième argument du constructeur.
        </para>

        <programlisting language="php"><![CDATA[
$input = new Zend_Filter_Input($filters, $validators);
$newData = $_POST;
$input->setData($newData);
]]></programlisting>

        <para>
            La méthode <methodname>setData()</methodname> réaffecte une nouveau tableau de valeurs
            d'entrée dans l'objet <classname>Zend_Filter_Input</classname>, en écrasant toute autre
            source s'y trouvant. Ceci est pratique afin de réutiliser des règles communes de filtres
            / validateurs, sur différentes sources.
        </para>
    </sect2>

    <sect2 id="zend.filter.input.results">
        <title>Récupérer les champs validés/filtré, et les éventuels rapports</title>

        <para>
            Une fois l'objet configuré, et le tableau de données d'entrée passé, vous pouvez
            récupérer les rapports concernant les champs absents, invalides ou inconnus. Vous pouvez
            évidemment aussi récupérer les valeurs validées/filtrées des champs d'entrée
            valides.
        </para>

        <sect3 id="zend.filter.input.results.isvalid">
            <title>Demander si l'entrée est valide</title>

            <para>
                Si toutes les données d'entrée passent les règles de validation la méthode
                <methodname>isValid()</methodname> retourne <constant>TRUE</constant>. Si n'importe quelle donnée
                d'entrée n'est pas validée, ou est manquante, alors <methodname>isValid()</methodname> retourne
                <constant>FALSE</constant>.
            </para>

            <programlisting language="php"><![CDATA[
if ($input->isValid()) {
  echo "OK\n";
}
]]></programlisting>

            <para>
                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.
            </para>

            <programlisting language="php"><![CDATA[
if ($input->isValid('month')) {
  echo "Le champ 'month' est OK\n";
}
]]></programlisting>
        </sect3>

        <sect3 id="zend.filter.input.results.reports">
            <title>Récupérer les infos des champs invalides, absents ou inconnus</title>

            <itemizedlist>
                <listitem>
                    <para>
                        Les champs <emphasis>invalides</emphasis> sont ceux qui ne passent pas
                        un ou plusieurs critères définis par les validateurs.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Les champs <emphasis>absents</emphasis> sont ceux qui ne sont pas
                        présents dans la donnée d'entrée, alors que la méta commande
                        <code>'presence'=&gt;'required'</code> était présente (voyez <link
                        linkend="zend.filter.input.metacommands.presence">la section</link> sur les
                        méta commandes).
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Les champs <emphasis>inconnus</emphasis> sont ceux présents dans la
                        donnée d'entrée alors que aucun validateur ni filtre ne lui avait attribué
                        de règle.
                    </para>
                </listitem>
            </itemizedlist>

            <programlisting language="php"><![CDATA[
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();
}
]]></programlisting>

            <para>
                Les valeurs retournées par <methodname>getMessages()</methodname> 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.
            </para>

            <para>
                La méthode <methodname>getMessages()</methodname> retourne la fusion des tableaux
                retournés par <methodname>getInvalid()</methodname> et <methodname>getMissing()</methodname>. 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.
            </para>

            <para>
                La méthode <methodname>getErrors()</methodname> 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 <xref
                linkend="zend.validate.introduction.using" /> pour plus d'information.
            </para>

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

            <programlisting language="php"><![CDATA[
$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);
]]></programlisting>

            <para>
                And you can also add a translator which gives you the ability to provide multiple
                languages for the messages which are returned by
                <classname>Zend_Filter_Input</classname>.
            </para>

            <programlisting language="php"><![CDATA[
$translate = new Zend_Translate_Adapter_Array(array(
    'content' => array(
        Zend_Filter_Input::MISSING_MESSAGE => "Where is the field?"
    )
);

$input = new Zend_Filter_Input($filters, $validators, $data);
$input->setTranslator($translate);
]]></programlisting>

            <para>
                When you are using an application wide translator, then it will also be used by
                <classname>Zend_Filter_Input</classname>. In this case you will not have to set the
                translator manually.
            </para>

            <para>
                Le résultat de la méthode <methodname>getUnknown()</methodname> 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.
            </para>
        </sect3>

        <sect3 id="zend.filter.input.results.escaping">
            <title>Récupérer les champs valides</title>

            <para>
                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 <methodname>getEscaped()</methodname> et
                <methodname>getUnescaped()</methodname>.
            </para>

            <programlisting language="php"><![CDATA[
$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
]]></programlisting>

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

            <note>
                <para>
                    La méthode <methodname>getUnescaped()</methodname> 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).
                </para>
            </note>

            <warning>
                <title>Escaping unvalidated fields</title>

                <para>
                    As mentioned before <methodname>getEscaped()</methodname> returns only validated
                    fields. Fields which do not have an associated validator can not be received
                    this way. Still, there is a possible way. You can add a empty validator for all
                    fields.
                </para>

            <programlisting language="php"><![CDATA[
$validators = array('*' => array());

$input = new Zend_Filter_Input($filters, $validators, $data, $options);
]]></programlisting>

                <para>
                    But be warned that using this notation introduces a security leak which could
                    be used for cross-site scripting attacks. Therefor you should always set
                    individual validators for each field.
                </para>
            </warning>

            <para>
                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 :
            </para>

            <programlisting language="php"><![CDATA[
$options = array('escapeFilter' => 'StringTrim');
$input = new Zend_Filter_Input($filters, $validators, $data, $options);
]]></programlisting>

            <para>
                Aussi, la méthode <methodname>setDefaultEscapeFilter()</methodname> fait la même chose
                :
            </para>

            <programlisting language="php"><![CDATA[
$input = new Zend_Filter_Input($filters, $validators, $data);
$input->setDefaultEscapeFilter(new Zend_Filter_StringTrim());
]]></programlisting>

            <para>
                Il est possible de passer une chaine, ou directement un objet instance de
                <classname>Zend_Filter</classname>.
            </para>

            <para>
                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
                <classname>Zend_Filter_Input</classname>, ils auraient pu faire échouer les
                validateurs, car les filtres sont exécutés <emphasis>AVANT</emphasis> 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
                <methodname>setDefaultEscapeFilter()</methodname>, et non pas le tableau
                <varname>$filters</varname>.
            </para>

            <para>
                Comme il n'y a qu'une seule méthode <methodname>getEscaped()</methodname>, 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
                <classname>Zend_Filter_Input</classname> en créant d'autres méthodes de récupération
                de données, plus spécifiques.
            </para>
        </sect3>
    </sect2>

    <sect2 id="zend.filter.input.metacommands">
        <title>Utiliser des méta commandes pour contrôler les règles des filtres et
        validateurs</title>

        <para>
            En plus de déclarer un mapping entre des champs d'un tableau, et des validateurs
            et des filtres, il est possible d'utiliser des méta commandes pour contrôler le
            comportement de Zend_Filter_Input. Les méta commandes se présentent sous la forme de
            chaînes dans le tableau des filtres ou des validateurs.
        </para>

        <sect3 id="zend.filter.input.metacommands.fields">
            <title>La méta commande <constant>FIELDS</constant></title>

            <para>
                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".
            </para>

            <para>
                Vous pouvez spécifier cette méta commande en utilisant la constante de classe
                <classname>Zend_Filter_Input::FIELDS</classname>.
            </para>

            <programlisting language="php"><![CDATA[
$filters = array(
    'month' => array(
        'Digits',        // nom du filtre à l'index [0]
        'fields' => 'mo' // nom du champ à l'index ['fields']
    )
);
]]></programlisting>

            <para>
                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.
            </para>

            <para>
                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".
            </para>

            <para>
                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 <constant>TRUE</constant> si les champs sont égaux.
            </para>

            <programlisting language="php"><![CDATA[
$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'.
]]></programlisting>

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

        <sect3 id="zend.filter.input.metacommands.presence">
            <title>Méta commande <constant>PRESENCE</constant></title>

            <para>
                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.
            </para>

            <para>
                Vous pouvez spécifier cette méta commande avec la constante de classe
                <classname>Zend_Filter_Input::PRESENCE</classname>.
            </para>

            <programlisting language="php"><![CDATA[
$validators = array(
    'month' => array(
        'digits',
        'presence' => 'required'
    )
);
]]></programlisting>

            <para>La valeur par défaut de cette méta commande est "optional".</para>
        </sect3>

        <sect3 id="zend.filter.input.metacommands.default">
            <title>La méta commande <constant>DEFAULT_VALUE</constant></title>

            <para>
                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.
            </para>

            <para>
                Vous pouvez spécifier cette méta commande avec la constante de classe
                <classname>Zend_Filter_Input::DEFAULT_VALUE</classname>.
            </para>

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

            <programlisting language="php"><![CDATA[
$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
]]></programlisting>

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

            <para>Il n'y a pas de valeur par défaut pour cette méta commande.</para>
        </sect3>

        <sect3 id="zend.filter.input.metacommands.allow-empty">
            <title>La méta commande <constant>ALLOW_EMPTY</constant></title>

            <para>
                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
                (<code>''</code>). 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).
            </para>

            <para>
                Si la chaine vide doit pouvoir être considérée comme valide, utilisez la méta
                commande "allowEmpty" avec la valeur <constant>TRUE</constant>.
            </para>

            <para>
                Vous pouvez spécifier cette méta commande avec la constante de classe
                <classname>Zend_Filter_Input::ALLOW_EMPTY</classname>
            </para>

            <programlisting language="php"><![CDATA[
$validators = array(
    'address2' => array(
        'Alnum',
        'allowEmpty' => true
    )
);
]]></programlisting>

            <para>La valeur par défaut de cette méta commande est <constant>FALSE</constant>.</para>

            <para>
                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 à <constant>FALSE</constant>
                (le champ est considéré invalide s'il est vide),
                <classname>Zend_Filter_Input</classname> retourne un message d'erreur par défaut que
                vous pouvez récupérer avec la méthode <methodname>getMessages()</methodname>. Ce message se
                change grâce à l'option "notEmptyMessage" spécifiée en constructeur de
                <classname>Zend_Filter_Input</classname> ou via la méthode
                <methodname>setOptions()</methodname>.
            </para>

            <programlisting language="php"><![CDATA[
$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);
]]></programlisting>
        </sect3>

        <sect3 id="zend.filter.input.metacommands.break-chain">
            <title>La méta commande <constant>BREAK_CHAIN</constant></title>

            <para>
                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.
            </para>

            <para>
                Si la valeur de la méta commande "<code>breakChainOnFailure</code>" est
                <constant>TRUE</constant>, la chaine de validation va se terminer dès lors qu'un des
                validateur termine sur un échec.
            </para>

            <para>
                Vous pouvez spécifier cette méta commande au moyen de la constante de classe
                <classname>Zend_Filter_Input::BREAK_CHAIN</classname>
            </para>

            <programlisting language="php"><![CDATA[
$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);
]]></programlisting>

            <para>La valeur par défaut de cette méta commande est <constant>FALSE</constant>.</para>

            <para>
                La classe <classname>Zend_Validate</classname> est plus flexible lors du bris
                de la chaine d'exécution, par rapport à <classname>Zend_Filter_Input</classname>.
                Avec <classname>Zend_Validate</classname>, vous pouvez mettre l'option pour casser
                la chaine indépendamment pour chaque validateur. Avec
                <classname>Zend_Filter_Input</classname>, 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 :
            </para>

            <programlisting language="php"><![CDATA[
// 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);
]]></programlisting>
        </sect3>

        <sect3 id="zend.filter.input.metacommands.messages">
            <title>La méta commande <constant>MESSAGES</constant></title>

            <para>
                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.
            </para>

            <para>
                Vous pouvez utiliser la constante de classe
                <classname>Zend_Filter_Input::MESSAGES</classname> pour définir cette méta
                commande.
            </para>

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

            <programlisting language="php"><![CDATA[
$validators = array(
    'month' => array(
        'digits',
        'messages' => 'Un mois doit être un chiffre'
    )
);
]]></programlisting>

            <para>
                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'.
            </para>

            <para>
                Chaque élément de ce tableau s'applique à un validateur au même niveau
                d'index. Ainsi, un validateur à l'index <emphasis>n</emphasis> verra son message
                d'erreur modifié si vous utilisez l'index <emphasis>n</emphasis> 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é.
            </para>

            <programlisting language="php"><![CDATA[
$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'
        )
    )
);
]]></programlisting>

            <para>
                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.
            </para>

            <programlisting language="php"><![CDATA[
$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%'
            )
        )
    )
);
]]></programlisting>

            <para>
                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.
            </para>

            <para>
                Si vous n'avez qu'un seul validateur dans vos règles de validation ou que
                tous les validateurs ont le même message de paramétrer, alors ils peuvent
                être référencés la construction additionnelle de type tableau&#160;:
            </para>

            <programlisting language="php"><![CDATA[
$validators = array(
    'month' => array(
        new Zend_Validate_Between(1, 12),
        'messages' => 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%'
        )
    )
);
]]></programlisting>
        </sect3>

        <sect3 id="zend.filter.input.metacommands.global">
            <title>Utiliser des options pour définir des méta commandes pour toutes les
            règles</title>

            <para>
                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
                <varname>$options</varname> du constructeur de
                <classname>Zend_Filter_Input</classname>.
            </para>

            <programlisting language="php"><![CDATA[
// 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);
]]></programlisting>

            <para>
                Les méta commandes "fields", "messages", et "default" ne bénéficient pas d'un
                tel raccourci.
            </para>
        </sect3>
    </sect2>

    <sect2 id="zend.filter.input.namespaces">
        <title>Ajouter des espaces de noms comme noms de classes</title>

        <para>
            Par défaut, l'ajout d'un validateur ou d'un filtre sous forme de chaine, va faire
            en sort que <classname>Zend_Filter_Input</classname> cherche une correspondance sous
            l'espace de nom <classname>Zend_Filter_*</classname> et
            <classname>Zend_Validate_*</classname>.
        </para>

        <para>
            Si vous écrivez vos propres filtres (ou validateurs), la classe peut exister dans
            un autre espace de nom que <classname>Zend_Filter</classname> ou
            <classname>Zend_Validate</classname>. Il est alors possible de dire à
            <classname>Zend_Filter_Input</classname> de chercher dans ces espaces là. Ceci se fait
            via son constructeur&#160;:
        </para>

        <programlisting language="php"><![CDATA[
$options = array('filterNamespace' => 'My_Namespace_Filter', 'validatorNamespace' => 'My_Namespace_Validate');
$input = new Zend_Filter_Input($filters, $validators, $data, $options);
]]></programlisting>

        <para>
            Alternativement, vous pouvez utiliser les méthodes
            <methodname>addValidatorPrefixPath($prefix, $path)</methodname> ou
            <methodname>addFilterPrefixPath($prefix, $path)</methodname>, qui proxie directement le chargeur de
            plugin utilisé par <classname>Zend_Filter_Input</classname> :
        </para>

        <programlisting language="php"><![CDATA[
$input->addValidatorPrefixPath('Autre_Namespace', 'Autre/Namespace');
$input->addFilterPrefixPath('Foo_Namespace', 'Foo/Namespace');

// Maitenant l'ordre de recherche des validateurs est :
// 1. My_Namespace_Validate
// 2. Autre_Namespace
// 3. Zend_Validate

// L'ordre de recherche des filtres est :
// 1. My_Namespace_Filter
// 2. Foo_Namespace
]]></programlisting>

        <para>
            Il n'est pas possible de supprimer les espaces de nommage
            <classname>Zend_Filter</classname> et <classname>Zend_Validate</classname>. Les espaces
            définis par l'utilisateur sont cherchés en premiers, les espaces de nom Zend sont
            cherchés en derniers.
        </para>

        <note>
            <para>
                A partir de la version 1.5, la fonction <methodname>addNamespace($namespace)</methodname>
                est dépréciée et échangée avec le chargeur de plugin et les méthodes
                <code>addFilterPrefixPath</code> et <code>addValidatorPrefixPath</code> ont été
                ajoutées. De même la constante
                <classname>Zend_Filter_Input::INPUT_NAMESPACE</classname> est aussi dépréciée. Les
                constantes <classname>Zend_Filter_Input::VALIDATOR_NAMESPACE</classname> et
                <classname>Zend_Filter_Input::FILTER_NAMESPACE</classname> sont disponibles à partir
                de la version 1.7.0.
            </para>
        </note>

        <note>
            <para>
                A partir de la version 1.0.4,
                <classname>Zend_Filter_Input::NAMESPACE</classname>, ayant une valeur
                <code>namespace</code>, a été changé par
                <classname>Zend_Filter_Input::INPUT_NAMESPACE</classname>, ayant une valeur
                <code>inputNamespace</code>, dans le but de se conformer à la réservation du mot clé
                <code>namespace</code> par <acronym>PHP</acronym> 5.3.
            </para>
        </note>
    </sect2>
</sect1>