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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.captcha.adapters">
    <title>CAPTCHA Adapters</title>

    <para>
        The following adapters are shipped with Zend Framework by default.
    </para>

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

        <para>
            <classname>Zend_Captcha_Word</classname> is an abstract adapter that serves as the base
            class for most other CAPTCHA adapters. It provides mutators for
            specifying word length, session TTL, the session namespace object
            to use, and the session namespace class to use for persistence if
            you do not wish to use <classname>Zend_Session_Namespace</classname>.
            <classname>Zend_Captcha_Word</classname> encapsulates validation logic.
        </para>

        <para>
            By default, the word length is 8 characters, the session timeout is
            5 minutes, and <classname>Zend_Session_Namespace</classname> is used for persistence
            (using the namespace "Zend_Form_Captcha_&lt;captcha ID&gt;").
        </para>

        <para>
            In addition to the methods required by the
            <classname>Zend_Captcha_Adapter</classname> interface,
            <classname>Zend_Captcha_Word</classname> exposes the following methods:
        </para>

        <itemizedlist>
            <listitem><para>
                <methodname>setWordLen($length)</methodname> and
                <methodname>getWordLen()</methodname> allow you to specify the length of the
                generated "word" in characters, and to retrieve the current value.
            </para></listitem>

            <listitem><para>
                <methodname>setTimeout($ttl)</methodname> and <methodname>getTimeout()</methodname>
                allow you to specify the time-to-live of the session token, and
                to retrieve the current value. <varname>$ttl</varname> should be
                specified in seconds.
            </para></listitem>

            <listitem><para>
                <methodname>setSessionClass($class)</methodname> and
                <methodname>getSessionClass()</methodname> allow you to specify an
                alternate <classname>Zend_Session_Namespace</classname> implementation to
                use to persist the CAPTCHA token and to retrieve the
                current value.
            </para></listitem>

            <listitem><para>
                <methodname>getId()</methodname> allows you to retrieve the current token
                identifier.
            </para></listitem>

            <listitem><para>
                <methodname>getWord()</methodname> allows you to retrieve the generated
                word to use with the CAPTCHA. It will generate the word for you if
                none has been generated yet.
            </para></listitem>

            <listitem><para>
                <methodname>setSession(Zend_Session_Namespace $session)</methodname> allows
                you to specify a session object to use for persisting the
                CAPTCHA token. <methodname>getSession()</methodname> allows you to retrieve
                the current session object.
            </para></listitem>
        </itemizedlist>

        <para>
            All word CAPTCHAs allow you to pass an array of options to the
            constructor, or, alternately, pass them to
            <methodname>setOptions()</methodname>. You can also pass a
            <classname>Zend_Config</classname> object to <methodname>setConfig()</methodname>. By
            default, the <emphasis>wordLen</emphasis>, <emphasis>timeout</emphasis>, and
            <emphasis>sessionClass</emphasis> keys may all be used. Each concrete
            implementation may define additional keys or utilize the options in
            other ways.
        </para>

        <note>
        <para>
            <classname>Zend_Captcha_Word</classname> is an abstract class and may not be
            instantiated directly.
        </para>
        </note>
    </sect2>

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

        <para>
            The <classname>Zend_Captch_Dumb</classname> adapter is mostly self-descriptive. It
            provides a random string that must be typed in reverse to validate. As such, it's
            not a good CAPTCHA solution and should only be used for
            testing. It extends <classname>Zend_Captcha_Word</classname>.
        </para>
    </sect2>

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

        <para>
            The <classname>Zend_Captcha_Figlet</classname> adapter utilizes <link
                linkend="zend.text.figlet"><classname>Zend_Text_Figlet</classname></link> to present
            a figlet to the user.
        </para>

        <para>
            Options passed to the constructor will also be passed to the <link
                linkend="zend.text.figlet">Zend_Text_Figlet</link> object. See
                the <link linkend="zend.text.figlet">Zend_Text_Figlet</link>documentation for
            details on what configuration options are available.
        </para>
    </sect2>

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

        <para>
            The Zend_Captcha_Image adapter takes the generated word and renders it as an
            image, performing various skewing permutations to make it
            difficult to automatically decipher. It
            requires the <ulink url="http://php.net/gd">GD extension</ulink>
            compiled with TrueType or Freetype support. Currently, the Zend_Captcha_Image
            adapter can only generate PNG images.
        </para>

        <para>
            <classname>Zend_Captcha_Image</classname> extends
            <classname>Zend_Captcha_Word</classname>, and additionally exposes the
            following methods:
        </para>

        <itemizedlist>
            <listitem><para>
                <methodname>setExpiration($expiration)</methodname> and
                <methodname>getExpiration()</methodname> allow you to specify a maximum
                lifetime the CAPTCHA image may reside on the filesystem. This is
                typically a longer than the session lifetime. Garbage
                collection is run periodically each time the CAPTCHA object is
                invoked, deleting all images that have expired.
                Expiration values should be specified in seconds.
            </para></listitem>

            <listitem><para>
                <methodname>setGcFreq($gcFreq)</methodname> and <methodname>getGcFreg()</methodname>
                allow you to specify how frequently garbage collection should
                run. Garbage collection will run every <emphasis>1/$gcFreq</emphasis>
                calls. The default is 100.
            </para></listitem>

            <listitem><para>
                <methodname>setFont($font)</methodname> and <methodname>getFont()</methodname> allow
                you to specify the font you will use. <varname>$font</varname>
                should be a fully qualified path to the font file.
                This value is required; the CAPTCHA will throw an
                exception during generation if the font file has not been specified.
            </para></listitem>

            <listitem><para>
                <methodname>setFontSize($fsize)</methodname> and
                <methodname>getFontSize()</methodname> allow you to specify the font size in pixels
                for generating the CAPTCHA. The default is 24px.
            </para></listitem>

            <listitem><para>
                <methodname>setHeight($height)</methodname> and <methodname>getHeight()</methodname>
                allow you to specify the height in pixels of the generated
                CAPTCHA image. The default is 50px.
            </para></listitem>

            <listitem><para>
                <methodname>setWidth($width)</methodname> and <methodname>getWidth()</methodname>
                allow you to specify the width in pixels of the generated
                CAPTCHA image. The default is 200px.
            </para></listitem>

            <listitem><para>
                <methodname>setImgDir($imgDir)</methodname> and <methodname>getImgDir()</methodname>
                allow you to specify the directory for storing CAPTCHA images.
                The default is "./images/captcha/", relative to the bootstrap script.
            </para></listitem>

            <listitem><para>
                <methodname>setImgUrl($imgUrl)</methodname> and <methodname>getImgUrl()</methodname>
                allow you to specify the relative path to a CAPTCHA image to
                use for HTML markup. The default is "/images/captcha/".
            </para></listitem>

            <listitem><para>
                <methodname>setSuffix($suffix)</methodname> and <methodname>getSuffix()</methodname>
                allow you to specify the filename suffix for the CAPTCHA image. The
                default is ".png". Note: changing this value will not change the
                type of the generated image.
            </para></listitem>
        </itemizedlist>

        <para>
            All of the above options may be passed to the
            constructor by simply removing the 'set' method prefix and casting
            the initial letter to lowercase: "suffix", "height", "imgUrl", etc.
        </para>
    </sect2>

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

        <para>
            The <classname>Zend_Captcha_ReCaptcha</classname> adapter uses <link
                linkend="zend.service.recaptcha">Zend_Service_ReCaptcha</link>
            to generate and validate CAPTCHAs. It exposes the following
            methods:
        </para>

        <itemizedlist>
            <listitem><para>
                <methodname>setPrivKey($key)</methodname> and <methodname>getPrivKey()</methodname>
                allow you to specify the private key to use for the ReCaptcha
                service. This must be specified during construction, although it
                may be overridden at any point.
            </para></listitem>

            <listitem><para>
                <methodname>setPubKey($key)</methodname> and <methodname>getPubKey()</methodname>
                allow you to specify the public key to use with the ReCaptcha
                service. This must be specified during construction, although it
                may be overridden at any point.
            </para></listitem>

            <listitem><para>
                <methodname>setService(Zend_Service_ReCaptcha $service)</methodname> and
                <methodname>getService()</methodname> allow you to set and get
                the ReCaptcha service object.
            </para></listitem>
        </itemizedlist>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->