repo_zf1/documentation/manual/ja/module_specs/Zend_Service-ReCaptcha.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24249 -->
<sect1 id="zend.service.recaptcha">
    <title>Zend_Service_ReCaptcha(日本語)</title>

    <sect2 id="zend.service.recaptcha.introduction">
        <title>導入</title>

        <para>
            <classname>Zend_Service_ReCaptcha</classname> は <ulink
                url="http://recaptcha.net/">reCAPTCHA Web Service</ulink>
            用のクライアントです。reCAPTCHA のサイトによると、
            "reCAPTCHA is a free CAPTCHA service that
            helps to digitize books
            (reCAPTCHA はフリーな CAPTCHA サービスで、
            書籍の電子化を支援しています)" とのことです。
            reCAPTCHA は、ユーザにふたつの単語を入力させます。
            ひとつは実際の CAPTCHA で、もうひとつはスキャンされたテキスト
            (OCR ソフトウェアで認識できないもの) の単語です。
            ユーザが最初の単語を正しく入力したら、
            おそらく 2 番目の単語も正しく入力してくれるものとみなせます。
            その入力内容を使って、OCR ソフトウェアの能力を向上させるわけです。
        </para>

        <para>
            reCAPTCHA サービスを使用するには、<ulink
                url="http://recaptcha.net/whyrecaptcha.html">アカウントのサインアップ
                </ulink>
            が必要です。また公開鍵と秘密鍵を作成するには、
            サービスを使用するドメインを登録しなければなりません。
        </para>
    </sect2>

    <sect2 id="zend.service.recaptcha.simplestuse">
        <title>単純な使用法</title>

        <para>
            <classname>Zend_Service_ReCaptcha</classname> オブジェクトのインスタンスを作成し、
            公開鍵と秘密鍵を渡します。
        </para>


        <example id="zend.service.recaptcha.example-1">
            <title>reCAPTCHA サービスのインスタンスの作成</title>

            <programlisting language="php"><![CDATA[
$recaptcha = new Zend_Service_ReCaptcha($pubKey, $privKey);
]]></programlisting>
        </example>

        <para>
            reCAPTCHA をレンダリングするには、
            <methodname>getHTML()</methodname> メソッドをコールするだけです。
        </para>

        <example id="zend.service.recaptcha.example-2">
            <title>reCAPTCHA の表示</title>

            <programlisting language="php"><![CDATA[
echo $recaptcha->getHTML();
]]></programlisting>
        </example>

        <para>
            フォームから送信されてきた内容のうち、
            'recaptcha_challenge_field' と 'recaptcha_response_field'
            のふたつのフィールドの内容を受け取らなければなりません。
            これらを、reCAPTCHA オブジェクトの <methodname>verify()</methodname>
            メソッドに渡します。
        </para>

        <example id="zend.service.recaptcha.example-3">
            <title>フォームフィールドの検証</title>
            <programlisting language="php"><![CDATA[
$result = $recaptcha->verify(
    $_POST['recaptcha_challenge_field'],
    $_POST['recaptcha_response_field']
);
]]></programlisting>
        </example>

        <para>
            結果が得られたら、正しいものだったかどうかを確認します。結果は
            <classname>Zend_Service_ReCaptcha_Response</classname> オブジェクトとなり、
            このオブジェクトは <methodname>isValid()</methodname> メソッドを提供しています。
        </para>

        <example id="zend.service.recaptcha.example-4">
            <title>reCAPTCHA の検証</title>

            <programlisting language="php"><![CDATA[
if (!$result->isValid()) {
    // 検証に失敗
}
]]></programlisting>
        </example>

        <para>
            <link
                linkend="zend.captcha.adapters.recaptcha">reCAPTCHA</link>
            <classname>Zend_Captcha</classname> アダプタを使うか、そのアダプタを
            <link
                linkend="zend.form.standardElements.captcha">CAPTCHA
                フォーム要素</link>
            のバックエンドとして使うことがもっと簡単です。
            どちらの場合でも、reCAPTCHA のレンダリングや検証は自動化されます。
        </para>
    </sect2>

    <sect2 id="zend.service.recaptcha.mailhide">
        <title>メールアドレスの隠蔽</title>

        <para>
            <classname>Zend_Service_ReCaptcha_MailHide</classname> を使うと、
            メールアドレスを隠蔽できます。メールアドレスの一部分を、
            reCAPTCHA チャレンジのポップアップウィンドウに置き換えます。
            チャレンジを解決すると、完全なメールアドレスがあらわれるというわけです。
        </para>

        <para>
            このコンポーネントを使うには、
            mailhide <acronym>API</acronym> 用の公開キーと秘密キーを生成するための
            <ulink url="http://recaptcha.net/whyrecaptcha.html">アカウント</ulink>
            が必要です。
        </para>

        <example id="zend.service.recaptcha.mailhide.example-1">
            <title>mail hide コンポーネントの使用法</title>

            <programlisting language="php"><![CDATA[
// 隠したいメールアドレス
$mail = 'mail@example.com';

// mailhide コンポーネントのインスタンスを作成し、公開キーと秘密キー
// そして隠したいメールアドレスを渡します
$mailHide = new Zend_Service_ReCaptcha_MailHide();
$mailHide->setPublicKey($pubKey);
$mailHide->setPrivateKey($privKey);
$mailHide->setEmail($mail);

// 表示します
print($mailHide);
]]></programlisting>
        </example>

        <para>
            上の例の表示は "m...@example.com" のようになり、 "..."
            のリンクは reCAPTCHA チャレンジのポップアップウィンドウを表示します。
        </para>

        <para>
            公開キーと秘密キーそしてメールアドレスは、クラスのコンストラクタで指定することもできます。
            4 番目の引数も存在し、ここでコンポーネントのオプションを設定できます。
            使用できるオプションは次の表のとおりです。

            <table id="zend.service.recaptcha.mailhide.options.table">
                <title>Zend_Service_ReCaptcha_MailHide のオプション</title>

                <tgroup cols="4">
                    <thead>
                        <row>
                            <entry>オプション</entry>
                            <entry>説明</entry>
                            <entry>期待する値</entry>
                            <entry>デフォルト値</entry>
                        </row>
                    </thead>

                    <tbody>
                        <row>
                            <entry>linkTitle</entry>
                            <entry>リンクの title 属性</entry>
                            <entry>文字列</entry>
                            <entry>'Reveal this e-mail address'</entry>
                        </row>

                        <row>
                            <entry>linkHiddenText</entry>
                            <entry>ポップアップリンクを含める文字列</entry>
                            <entry>文字列</entry>
                            <entry>'...'</entry>
                        </row>

                        <row>
                            <entry>popupWidth</entry>
                            <entry>ポップアップウィンドウの幅</entry>
                            <entry>int</entry>
                            <entry>500</entry>
                        </row>

                        <row>
                            <entry>popupHeight</entry>
                            <entry>ポップアップウィンドウの高さ</entry>
                            <entry>int</entry>
                            <entry>300</entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </para>

        <para>
            オプションの設定は、コンストラクタの 4 番目の引数で指定する以外にも
            <methodname>setOptions($options)</methodname> メソッドで行うこともできます。
            このメソッドには、連想配列あるいは <link linkend="zend.config">Zend_Config</link>
            のインスタンスを渡します。
        </para>

        <example id="zend.service.recaptcha.mailhide.example-2">
            <title>多数の隠しメールアドレスの作成</title>

            <programlisting language="php"><![CDATA[
// mailhide コンポーネントのインスタンスを作成し、公開キーと秘密キー
// そして隠したいメールアドレスを渡します
$mailHide = new Zend_Service_ReCaptcha_MailHide();
$mailHide->setPublicKey($pubKey);
$mailHide->setPrivateKey($privKey);
$mailHide->setOptions(array(
    'linkTitle' => 'Click me',
    'linkHiddenText' => '+++++',
));

// 隠したいメールアドレス
$mailAddresses = array(
    'mail@example.com',
    'johndoe@example.com',
    'janedoe@example.com',
);

foreach ($mailAddresses as $mail) {
    $mailHide->setEmail($mail);
    print($mailHide);
}
]]></programlisting>
        </example>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->