repo_zf1Php7/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>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">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 <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 <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 <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>
        </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>
        </itemizedlist>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->