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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24604 -->
<sect1 id="zend.captcha.adapters">
    <title>CAPTCHA アダプタ</title>

    <para>
        次のアダプタが、Zend Framework に同梱されています。
    </para>

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

        <para>
            <classname>Zend_Captcha_Word</classname> は抽象アダプタで、
            その他の大半の <acronym>CAPTCHA</acronym> アダプタの基底クラスとなります。
            指定できる機能は、単語の長さやセッションの有効期限、
            使用するセッション名前空間オブジェクト、
            <classname>Zend_Session_Namespace</classname> を使いたくない場合に使用するセッション名前空間クラスです。
            <classname>Zend_Captcha_Word</classname> は、すべての検証ロジックをカプセル化します。
        </para>

        <para>
            デフォルトでは、単語の長さは 8 文字です。またセッションのタイムアウトは
            5 分、情報の永続化には <classname>Zend_Session_Namespace</classname> を使用します
            (使用する名前空間は "<classname>Zend_Form_Captcha_&lt;captcha ID&gt;</classname>" です)。
        </para>

        <para>
            <classname>Zend_Captcha_Adapter</classname> インターフェイスのメソッドのほかに、
            <classname>Zend_Captcha_Word</classname> は次のメソッドを公開しています。
        </para>

        <itemizedlist>
            <listitem><para>
                <methodname>setWordLen($length)</methodname> と <methodname>getWordLen()</methodname>
                で、生成される "単語" の文字数を設定したり現在の値を取得したりします。
            </para></listitem>

            <listitem><para>
                <methodname>setTimeout($ttl)</methodname> と <methodname>getTimeout()</methodname>
                で、セッショントークンの有効期限を設定したり現在の値を取得したりします。
                <varname>$ttl</varname> は秒数で指定します。
            </para></listitem>

            <!-- TODO : to be translated -->
            <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> と
                <methodname>getSessionClass()</methodname> で、
                <acronym>CAPTCHA</acronym> トークンの永続化に使用する
                <classname>Zend_Session_Namespace</classname> の実装を設定したり
                現在の値を取得したりします。
            </para></listitem>

            <listitem><para>
                <methodname>getId()</methodname> で、現在のトークン識別子を取得します。
            </para></listitem>

            <listitem><para>
                <methodname>getWord()</methodname> で、<acronym>CAPTCHA</acronym>
                に使用するために生成した単語を取得します。
                まだ生成されていない場合は、まず生成してからそれを返します。
            </para></listitem>

            <listitem><para>
                <methodname>setSession(Zend_Session_Namespace $session)</methodname>
                で、<acronym>CAPTCHA</acronym> トークンの永続化に使用するセッションオブジェクトを設定します。
                <methodname>getSession()</methodname> で、現在のセッションオブジェクトを取得します。
            </para></listitem>
        </itemizedlist>

        <para>
            すべての Word <acronym>CAPTCHA</acronym> は、コンストラクタにオプションの配列を渡すことができます。
            別の方法として、その配列を <methodname>setOptions()</methodname>
            で渡す (あるいは <classname>Zend_Config</classname> オブジェクトを
            <methodname>setConfig()</methodname> で渡す) こともできます。
            デフォルトで、
            <emphasis>wordLen</emphasis>、<emphasis>timeout</emphasis> および
            <emphasis>sessionClass</emphasis> のキーをすべて使用します。
            各具象実装では、それ以外のキーを使用したり
            違う方法でオプションを使用したりしているかもしれません。
        </para>

        <note>
        <para>
            <classname>Zend_Captcha_Word</classname> は抽象クラスであり、
            直接そのインスタンスを作成することはできません。
        </para>
        </note>
    </sect2>

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

        <para>
            <classname>Zend_Captch_Dumb</classname> アダプタは、その名が示すとおりのものです。
            ランダムな文字列を用意し、それを逆からタイプさせることで検証を行います。
            これは <acronym>CAPTCHA</acronym> の手法としてはあまりよいものではないので、
            テスト用に使うのみにしておきましょう。
            あるいは、ほかに手がない場合の最後の手段としてのみ使うようにしましょう。
            このアダプタは <classname>Zend_Captcha_Word</classname> を継承しています。
        </para>
    </sect2>

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

        <para>
            <classname>Zend_Captcha_Figlet</classname> アダプタは、<link
                linkend="zend.text.figlet">Zend_Text_Figlet</link>
            を使用して Figlet をユーザに表示します。
        </para>

        <para>
            コンストラクタに渡されたオプションは、アダプタが使用する <link
                linkend="zend.text.figlet"><classname>Zend_Text_Figlet</classname></link>
            オブジェクトにも渡されます。
            使用できる設定オプションについては、
            <link linkend="zend.text.figlet"><classname>Zend_Text_Figlet</classname></link>
            のドキュメントを参照ください。
        </para>
    </sect2>

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

        <para>
            <classname>Zend_Captcha_Image</classname> アダプタは、
            生成された単語を受け取ってそれを画像としてレンダリングし、
            それをいろいろな方法で歪めて自動判読を困難にします。
            これを使用するには、
            <ulink url="http://php.net/gd">GD 拡張モジュール</ulink>
            を TrueType あるいは Freetype のサポートつきでコンパイルする必要があります。
            現在、<classname>Zend_Captcha_Image</classname> アダプタが生成できるのは
            <acronym>PNG</acronym> 画像のみです。
        </para>

        <para>
            <classname>Zend_Captcha_Image</classname> は
            <classname>Zend_Captcha_Word</classname> を継承しており、
            さらに次のメソッドを公開しています。
        </para>

        <itemizedlist>
            <listitem><para>
                <methodname>setExpiration($expiration)</methodname> と
                <methodname>getExpiration()</methodname> で、
                <acronym>CAPTCHA</acronym> 画像をファイルシステム上に残す期間を設定します。
                通常、これはセッションの有効期間より長くします。
                <acronym>CAPTCHA</acronym> オブジェクトが起動されるたびにガベージコレクションが働き、
                期限切れとなった画像が削除されます。
                値は秒数で指定します。
            </para></listitem>

            <listitem><para>
                <methodname>setGcFreq($gcFreq)</methodname> と <methodname>getGcFreg()</methodname>
                で、ガベージコレクションが働く頻度を設定します。ガベージコレクションは、
                <command>1/$gcFreq</command> 回のコールごとに実行されます。
                デフォルトは 100 です。
            </para></listitem>

            <listitem><para>
                <methodname>setFont($font)</methodname> と <methodname>getFont()</methodname>
                で、使用するフォントを指定します。<varname>$font</varname> には、
                使用するフォントのパスをフルパス形式で指定する必要があります。
                この値を設定しなければ、<acronym>CAPTCHA</acronym> の生成時に例外がスローされます。
                フォントは必須です。
            </para></listitem>

            <listitem><para>
                <methodname>setFontSize($fsize)</methodname> と <methodname>getFontSize()</methodname>
                で、<acronym>CAPTCHA</acronym> を生成する際に使用するフォントのサイズをピクセル単位で設定します。
                デフォルトは 24px です。
            </para></listitem>

            <listitem><para>
                <methodname>setHeight($height)</methodname> と <methodname>getHeight()</methodname>
                で、生成される <acronym>CAPTCHA</acronym> 画像の高さをピクセル単位で指定します。
                デフォルトは 50px です。
            </para></listitem>

            <listitem><para>
                <methodname>setWidth($width)</methodname> と <methodname>getWidth()</methodname>
                で、生成される <acronym>CAPTCHA</acronym> 画像の幅をピクセル単位で指定します。
                デフォルトは 200px です。
            </para></listitem>

            <listitem><para>
                <methodname>setImgDir($imgDir)</methodname> と <methodname>getImgDir()</methodname>
                で、<acronym>CAPTCHA</acronym> 画像を保存するディレクトリを指定します。
                デフォルトは "<filename>./images/captcha/</filename>"
                で、これは起動スクリプトからの相対パスとなります。
            </para></listitem>

            <listitem><para>
                <methodname>setImgUrl($imgUrl)</methodname> と <methodname>getImgUrl()</methodname>
                で、<acronym>HTML</acronym> マークアップ時に使用する
                <acronym>CAPTCHA</acronym> 画像への相対パスを指定します。
                デフォルトは "<filename>/images/captcha/</filename>" です。
            </para></listitem>

            <listitem><para>
                <methodname>setSuffix($suffix)</methodname> と <methodname>getSuffix()</methodname>
                で、<acronym>CAPTCHA</acronym> 画像ファイル名の拡張子を指定します。デフォルトは
                "<filename>.png</filename>" です。注意: これを変更したからといって、
                生成される画像の形式が変わるわけではありません。
            </para></listitem>

            <!-- TODO : to be translated -->
            <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>
            上のすべてのオプションは、コンストラクタのオプションとして指定できます。
            その際には、メソッド名の先頭の 'set' を取り除いて先頭を小文字にした名前
            ("suffix", "height", "imgUrl" など) を使用します。
        </para>
    </sect2>

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

        <para>
            <classname>Zend_Captcha_ReCaptcha</classname> アダプタは、<link
                linkend="zend.service.recaptcha">Zend_Service_ReCaptcha</link>
            を使用して <acronym>CAPTCHA</acronym> の生成と検証を行います。
            次のメソッドを公開しています。
        </para>

        <itemizedlist>
            <listitem><para>
                <methodname>setPrivKey($key)</methodname> と <methodname>getPrivKey()</methodname>
                で、ReCaptcha サービスで使用する秘密鍵を指定します。
                これはオブジェクトの作成時に指定する必要がありますが、
                その後いつでも上書きできます。
            </para></listitem>

            <listitem><para>
                <methodname>setPubKey($key)</methodname> と <methodname>getPubKey()</methodname>
                で、ReCaptcha サービスで使用する公開鍵を指定します。
                これはオブジェクトの作成時に指定する必要がありますが、
                その後いつでも上書きできます。
            </para></listitem>

            <listitem><para>
                <methodname>setService(Zend_Service_ReCaptcha $service)</methodname> と
                <methodname>getService()</methodname> で、
                ReCaptcha サービスオブジェクトを取得したり取得したりします。
            </para></listitem>

            <!-- TODO : to be translated -->
            <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:
-->