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 <acronym>CAPTCHA</acronym> adapters. It provides mutators for
            specifying word length, session <acronym>TTL</acronym>, 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 "<classname>Zend_Form_Captcha_&lt;captcha ID&gt;</classname>").
        </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>setUseNumbers($numbers)</methodname> and
                    <methodname>getUseNumbers()</methodname> allow you to specify if numbers will be
                    considered as possible characters for the random work or only letters would be
                    used.
                </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 <acronym>CAPTCHA</acronym> 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 <acronym>CAPTCHA</acronym>. 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
                    <acronym>CAPTCHA</acronym> token. <methodname>getSession()</methodname> allows
                    you to retrieve the current session object.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            All word <acronym>CAPTCHA</acronym>s 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 <acronym>CAPTCHA</acronym> 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"><classname>Zend_Text_Figlet</classname></link> object.
            See the <link linkend="zend.text.figlet"><classname>Zend_Text_Figlet</classname></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 <classname>Zend_Captcha_Image</classname> 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
            <classname>Zend_Captcha_Image</classname> adapter can only generate
            <acronym>PNG</acronym> 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 <acronym>CAPTCHA</acronym> image may reside on the filesystem.
                    This is typically a longer than the session lifetime. Garbage
                    collection is run periodically each time the <acronym>CAPTCHA</acronym> 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
                    <command>1/$gcFreq</command> 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 <acronym>CAPTCHA</acronym> 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 <acronym>CAPTCHA</acronym>. 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 <acronym>CAPTCHA</acronym> 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 <acronym>CAPTCHA</acronym> 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 <acronym>CAPTCHA</acronym> images. The default is
                    "<filename>./images/captcha/</filename>", 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 <acronym>CAPTCHA</acronym> image to use for <acronym>HTML</acronym> markup.
                    The default is "<filename>/images/captcha/</filename>".
                </para>
            </listitem>

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

            <listitem>
                <para>
                    <methodname>setDotNoiseLevel($level)</methodname> and
                    <methodname>getDotNoiseLevel()</methodname>, along with
                    <methodname>setLineNoiseLevel($level)</methodname> and
                    <methodname>getLineNoiseLevel()</methodname>,
                    allow you to control how much "noise" in the form of random dots and lines the
                    image would contain. Each unit of <varname>$level</varname> produces one random
                    dot or line. The default is 100 dots and 5 lines. The noise is added twice -
                    before and after the image distortion transformation.
                </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 <acronym>CAPTCHA</acronym>s. 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>

            <listitem>
                <para>
                    <methodname>isValid($value, $context = null)</methodname> validates the user's
                    input against the ReCaptcha service.  <varname>$value</varname> is an array with the following
                    keys:
                    <itemizedlist>
                        <listitem>
                            <para>
                                <varname>recaptcha_challenge_field</varname> - Value of the ReCaptcha widget's
                                challenge field (hidden)
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <varname>recaptcha_response_field</varname> - Value of the ReCaptcha widget's
                                user input field
                            </para>
                        </listitem>
                    </itemizedlist>
                </para>
            </listitem>
        </itemizedlist>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->