repo_zf1/documentation/manual/fr/module_specs/Zend_Captcha-Adapters.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 24604 -->
<!-- Reviewed: no -->
<sect1 id="zend.captcha.adapters">
    <title>Adaptateurs CAPTCHA</title>

    <para>Les adaptateurs suivants sont fournis dans Zend Framework par défaut.</para>

    <sect2 id="zend.captcha.adapters.word">
        <title>Zend_Captcha_Word</title>

        <para>
            <classname>Zend_Captcha_Word</classname> est un adaptateur abstrait qui sert de classe
            de base pour la plupart des autres adaptateurs <acronym>CAPTCHA</acronym>. Il fournit
            des mutateurs permettant de spécifier la taille du mot le <acronym>TTL</acronym> de
            session, l'objet d'espace de noms de session à utiliser, et la classe d'espace de noms
            de session à utiliser pour la persistance si vous ne souhaitez pas utiliser
            <classname>Zend_Session_Namespace</classname> pour la persistance.
            <classname>Zend_Captcha_Word</classname> encapsule toute la logique de validation.
        </para>

        <para>
            Par défaut la taille du mot est de 8 caractères, le timeout de session est de 5
            minutes et l'objet d'espace de nom de session utilisé est
            <classname>Zend_Session_Namespace</classname> (avec l'espace de nom
            ("<classname>Zend_Form_Captcha_&lt;captcha ID&gt;</classname>").
        </para>

        <para>
            En plus des méthodes standards fournies par
            <classname>Zend_Captcha_Adapter</classname>, <classname>Zend_Captcha_Word</classname>
            propose les méthodes suivantes&#160;:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>setWordLen($length)</methodname> et
                    <methodname>getWordLen()</methodname> vous permettent de piloter la taille du
                    "mot" généré, en caractères.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setTimeout($ttl)</methodname> et
                    <methodname>getTimeout()</methodname> vous donnent la main sur le temps-de-vie
                    du jeton de session. <varname>$ttl</varname> est exprimé en secondes.
                </para>
            </listitem>
             <listitem>
                 <para>
                    <methodname>setUseNumbers($numbers)</methodname> et
                    <methodname>getUseNumbers()</methodname> vous permettent de spécifier les
                    chiffres seront considérés comme des caractères possibles pour la partie
                    aléatoire ou si seules les lettres seront utilisées.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setSessionClass($class)</methodname> et
                    <methodname>getSessionClass()</methodname>
                    vous permettent de piloter la classe de session, si vous désirez utiliser une
                    alternative à <classname>Zend_Session_Namespace</classname>, ceci dans le but
                    de faire persister le jeton <acronym>CAPTCHA</acronym> en session.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>getId()</methodname> retourne l'identifiant du jeton actuel.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>getWord()</methodname> retourne le mot généré utilisé avec le
                    <acronym>CAPTCHA</acronym>. Il sera généré pour vous si aucun n'existe déjà.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setSession(Zend_Session_Namespace $session)</methodname> permet
                    d'injecter un objet de session qui sera utilisé pour faire persister le jeton
                    de <acronym>CAPTCHA</acronym>. <methodname>getSession()</methodname> retourne
                    l'objet de session actuellement utilisé.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Tous les <acronym>CAPTCHA</acronym> Word vous autorisent à passer un tableau d'options
            au constructeur, ou à <methodname>setOptions()</methodname> (un objet
            <classname>Zend_Config</classname> peut être utilisé avec
            <methodname>setConfig()</methodname>).
            Par défaut, les clés <emphasis>timeout</emphasis> <emphasis>wordLen</emphasis> et
            <emphasis>sessionClass</emphasis> seront utilisées.
        </para>

        <note>
            <para>
                <classname>Zend_Captcha_Word</classname> est une classe abstraite et ne peut être
                utilisée directement.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.captcha.adapters.dumb">
        <title>Zend_Captcha_Dumb</title>

        <para>
            L'adaptateur <classname>Zend_Captch_Dumb</classname> propose une chaîne aléatoire qui
            doit être ressaisie, mais inversée. Ce n'est pas une solution
            <acronym>CAPTCHA</acronym> idéale (un robot peut la détourner), il devrait être utilisé
            comme solution de remplacement extrême, ou pour les tests. Il étend
            <classname>Zend_Captcha_Word</classname>.
        </para>
    </sect2>

    <sect2 id="zend.captcha.adapters.figlet">
        <title>Zend_Captcha_Figlet</title>

        <para>
            L'adaptateur <classname>Zend_Captcha_Figlet</classname> utilise
            <link linkend="zend.text.figlet"><classname>Zend_Text_Figlet</classname></link> pour
            présenter un captcha. Seuls les caractères alphabétiques sont utilisables.
        </para>

        <para>
            Les options passées au constructeur le seront pour l'objet
            <link linkend="zend.text.figlet"><classname>Zend_Text_Figlet</classname></link> que
            l'adaptateur va utiliser. Voyez la documentation de <link
                linkend="zend.text.figlet"><classname>Zend_Text_Figlet</classname></link>pour plus
            d'informations.
        </para>
    </sect2>

    <sect2 id="zend.captcha.adapters.image">
        <title>Zend_Captcha_Image</title>

        <para>
            L'adaptateur <classname>Zend_Captcha_Image</classname> prend le mot généré et le
            transforme en image difficile à analyser pour un programme informatique (robot). Pour
            cela, il nécessite l'<ulink url="http://php.net/gd">extension GD</ulink>,
            compilée avec le support TrueType et Freetype. Actuellement, l'adaptateur
            <classname>Zend_Captcha_Image</classname> ne génère que des images
            <acronym>PNG</acronym>.
        </para>

        <para>
            <classname>Zend_Captcha_Image</classname> étend
            <classname>Zend_Captcha_Word</classname>, et propose les méthodes additionnelles
            suivantes&#160;:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>setExpiration($expiration)</methodname> et
                    <methodname>getExpiration()</methodname> vous autorisent à manipuler le temps
                    maximum que l'image <acronym>CAPTCHA</acronym> doit rester
                    sur le disque. En général, il s'agit d'un temps supérieur à celui de la
                    session. Un ramasse-miettes passe régulièrement à chaque instanciation de
                    l'objet <acronym>CAPTCHA</acronym> Image : il détruit les images arrivées à
                    expiration. La période d'expiration doit être exprimée en secondes.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setGcFreq($gcFreq)</methodname> et
                    <methodname>getGcFreg()</methodname> vous
                    permettent de manipuler la fréquence de collecte du ramasse-miettes des images.
                    Le ramasse-miettes passera à une fréquence de <command>1/$gcFreq</command>.
                    Par défaut 1&#160;/&#160;100, soit toutes les 100 requêtes.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setFont($font)</methodname> et <methodname>getFont()</methodname>
                    vous donnent le moyen de manipuler la police que vous souhaitez utiliser.
                    <varname>$font</varname> doit indiquer le chemin complet vers la police à
                    utiliser pour générer le <acronym>CAPTCHA</acronym>.
                    Une exception sera levée si vous ne spécifiez pas ce paramètre.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setFontSize($fsize)</methodname> et
                    <methodname>getFontSize()</methodname> servent pour spécifier et récupérer la
                    taille de la police à utiliser (en pixels) pour générer l
                    <acronym>CAPTCHA</acronym>. Par défaut&#160;: 24px.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setHeight($height)</methodname> et
                    <methodname>getHeight()</methodname> servent pour spécifier et récupérer la
                    hauteur de la police à utiliser (en pixels) pour générer le
                    <acronym>CAPTCHA</acronym>. Par défaut&#160;: 50px.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setWidth($width)</methodname> et
                    <methodname>getWidth()</methodname> servent pour spécifier et récupérer la
                    largeur de la police à utiliser (en pixels) pour générer le
                    <acronym>CAPTCHA</acronym>. Par défaut&#160;: 200px.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setImgDir($imgDir)</methodname> et
                    <methodname>getImgDir()</methodname> vous permettent de manipuler le dossier
                    dans lequel les images <acronym>CAPTCHA</acronym> générées
                    seront stockées. Par défaut, il s'agit de
                    "<filename>./images/captcha/</filename>", qui devrait être
                    pris relativement au fichier de bootstrap du site.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setImgUrl($imgUrl)</methodname> et
                    <methodname>getImgUrl()</methodname> vous donnent le moyen de manipuler le
                    chemin relatif à utiliser pour la balise <acronym>HTML</acronym> servant
                    à afficher l'image du <acronym>CAPTCHA</acronym>. Par défaut, il s'agit de
                    "<filename>/images/captcha/</filename>".
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setSuffix($suffix)</methodname> et
                    <methodname>getSuffix()</methodname> vous donnent
                    la main sur le suffixe à utiliser pour le nom du fichier de l'image générée par
                    le <acronym>CAPTCHA</acronym>. Il s'agit par défaut de
                    "<filename>.png</filename>". Note : changer ceci ne changera pas
                    le type de l'image générée.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setDotNoiseLevel($level)</methodname> et
                    <methodname>getDotNoiseLevel()</methodname>, avec
                    <methodname>setLineNoiseLevel($level)</methodname> et
                    <methodname>getLineNoiseLevel()</methodname>, vous permettent de contrôler le
                    niveau de bruit sous forme de points et de lignes que l'image va contenir.
                    Chaque unité de <varname>$level</varname> produit un point ou une ligne
                    aléatoire. Les valeurs par défaut sont 100 points et 5 lignes. Le bruit est
                    ajouté deux fois&#160;: avant et après la transformation de l'image.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Toutes les options ci-dessus peuvent aussi être passées en constructeur.
            Supprimer la partie "set" de leur méthodes, et passez leur première lettre en minuscule
            pour avoir les clés du tableau d'options que le constructeur utilise. ("suffix",
            "height", "imgUrl", etc...).
        </para>
    </sect2>

    <sect2 id="zend.captcha.adapters.recaptcha">
        <title>Zend_Captcha_ReCaptcha</title>

        <para>
            L'adaptateur <classname>Zend_Captcha_ReCaptcha</classname> utilise
            <link linkend="zend.service.recaptcha">Zend_Service_ReCaptcha</link> pour générer des
            <acronym>CAPTCHA</acronym>. Les méthodes suivantes lui sont propres&#160;:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>setPrivKey($key)</methodname> et
                    <methodname>getPrivKey()</methodname> vous
                    permettent de gérer la clé privée utilisée avec le service ReCaptcha. Cette clé
                    doit être spécifiée en constructeur, mais peut être ensuite modifiée.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setPubKey($key)</methodname> et
                    <methodname>getPubKey()</methodname> vous permettent
                    de gérer la clé publique utilisée avec le service ReCaptcha. Cette clé doit
                    être spécifiée en constructeur, mais peut être ensuite modifiée.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setService(Zend_Service_ReCaptcha $service)</methodname> et
                    <methodname>getService()</methodname> vous permettent d'interagir directement
                    avec l'objet service ReCaptcha utilisé par l'adaptateur.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>isValid($value, $context = null)</methodname> valide l'entrée
                    de l'utilisateur avec le service ReCaptcha. <varname>$value</varname> est un
                    tableau avec les clés suivantes&#160;:
                    <itemizedlist>
                        <listitem>
                            <para>
                                <varname>recaptcha_challenge_field</varname> - valeur du champs
                                de challenge de l'élément ReCaptcha (caché)
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <varname>recaptcha_response_field</varname> - valeur du champs
                                correspondant à l'entré utilisateur de l'élément ReCaptcha
                            </para>
                        </listitem>
                    </itemizedlist>
                </para>
            </listitem>
        </itemizedlist>
    </sect2>
</sect1>