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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.service.recaptcha">
    <title>Zend_Service_ReCaptcha</title>

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

        <para>
            <classname>Zend_Service_ReCaptcha</classname> provides a client for the <ulink
                url="http://recaptcha.net/">reCAPTCHA Web Service</ulink>.
            Per the reCAPTCHA site, "reCAPTCHA is a free CAPTCHA service that
            helps to digitize books." Each reCAPTCHA requires the user to input
            two words, the first of which is the actual CAPTCHA, and the second
            of which is a word from some scanned text that Optical Character
            Recognition (OCR) software has been unable to identify.
            The assumption is that if a user correctly provides the first
            word, the second is likely correctly entered as well, and can be
            used to improve OCR software for digitizing books.
        </para>

        <para>
            In order to use the reCAPTCHA service, you will need to <ulink
                url="http://recaptcha.net/whyrecaptcha.html">sign up for an
                account</ulink> and register one or more domains with the
            service in order to generate public and private keys.
        </para>
    </sect2>

    <sect2 id="zend.service.recaptcha.simplestuse">
        <title>Simplest use</title>

        <para>
            Instantiate a <classname>Zend_Service_ReCaptcha</classname> object, passing it
            your public and private keys:
        </para>

        <example id="zend.service.recaptcha.example-1">
            <title>Creating an instance of the reCAPTCHA service</title>

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

        <para>
            To render the reCAPTCHA, simply call the <methodname>getHTML()</methodname>
            method:
        </para>

        <example id="zend.service.recaptcha.example-2">
            <title>Displaying the reCAPTCHA</title>

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

        <para>
            When the form is submitted, you should receive two fields,
            'recaptcha_challenge_field' and 'recaptcha_response_field'. Pass
            these to the reCAPTCHA object's <methodname>verify()</methodname> method:
        </para>

        <example id="zend.service.recaptcha.example-3">
            <title>Verifying the form fields</title>

            <programlisting language="php"><![CDATA[
$result = $recaptcha->verify(
    $_POST['recaptcha_challenge_field'],
    $_POST['recaptcha_response_field']
);
]]></programlisting>
        </example>

        <para>
            Once you have the result, test against it to see if it is valid. The
            result is a <classname>Zend_Service_ReCaptcha_Response</classname> object,
            which provides an <methodname>isValid()</methodname> method.
        </para>

        <example id="zend.service.recaptcha.example-4">
            <title>Validating the reCAPTCHA</title>

            <programlisting language="php"><![CDATA[
if (!$result->isValid()) {
    // Failed validation
}
]]></programlisting>
        </example>

        <para>
            It is even simpler to use <link
                linkend="zend.captcha.adapters.recaptcha">the reCAPTCHA</link>
            <classname>Zend_Captcha</classname> adapter, or to use that adapter as a
            backend for the <link
                linkend="zend.form.standardElements.captcha">CAPTCHA form
                element</link>. In each case, the details of rendering and
            validating the reCAPTCHA are automated for you.
        </para>
    </sect2>

    <sect2 id="zend.service.recaptcha.mailhide">
        <title>Hiding email addresses</title>

        <para>
            <classname>Zend_Service_ReCaptcha_MailHide</classname> can be used to hide email
            addresses. It will replace a part of an email address with a link that opens a popup
            window with a reCAPTCHA challenge. Solving the challenge will reveal the complete
            email address.
        </para>

        <para>
            In order to use this component you will need
            <ulink url="http://recaptcha.net/whyrecaptcha.html">an account</ulink> to generate
            public and private keys for the mailhide <acronym>API</acronym>.
        </para>

        <example id="zend.service.recaptcha.mailhide.example-1">
            <title>Using the mail hide component</title>

            <programlisting language="php"><![CDATA[
// The mail address we want to hide
$mail = 'mail@example.com';

// Create an instance of the mailhide component, passing it your public
// and private keys, as well as the mail address you want to hide
$mailHide = new Zend_Service_ReCaptcha_MailHide();
$mailHide->setPublicKey($pubKey);
$mailHide->setPrivateKey($privKey);
$mailHide->setEmail($mail);

// Display it
print($mailHide);
]]></programlisting>
        </example>

        <para>
            The example above will display "m...@example.com" where "..." has a link that opens up
            a popup window with a reCAPTCHA challenge.
        </para>

        <para>
            The public key, private key, and the email address can also be specified in the
            constructor of the class. A fourth argument also exists that enables you to set some
            options for the component. The available options are listed in the following table:

            <table id="zend.service.recaptcha.mailhide.options.table">
                <title>Zend_Service_ReCaptcha_MailHide options</title>

                <tgroup cols="4">
                    <thead>
                        <row>
                            <entry>Option</entry>
                            <entry>Description</entry>
                            <entry>Expected Values</entry>
                            <entry>Default Value</entry>
                        </row>
                    </thead>

                    <tbody>
                        <row>
                            <entry>linkTitle</entry>
                            <entry>The title attribute of the link</entry>
                            <entry>string</entry>
                            <entry>'Reveal this e-mail address'</entry>
                        </row>

                        <row>
                            <entry>linkHiddenText</entry>
                            <entry>The text that includes the popup link</entry>
                            <entry>string</entry>
                            <entry>'...'</entry>
                        </row>

                        <row>
                            <entry>popupWidth</entry>
                            <entry>The width of the popup window</entry>
                            <entry>int</entry>
                            <entry>500</entry>
                        </row>

                        <row>
                            <entry>popupHeight</entry>
                            <entry>The height of the popup window</entry>
                            <entry>int</entry>
                            <entry>300</entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </para>

        <para>
            The configuration options can be set by sending them as the fourth argument to the
            constructor or by calling <methodname>setOptions($options)</methodname>, which takes
            an associative array or an instance of <link linkend="zend.config">Zend_Config</link>.
        </para>

        <example id="zend.service.recaptcha.mailhide.example-2">
            <title>Generating many hidden email addresses</title>

            <programlisting language="php"><![CDATA[
// Create an instance of the mailhide component, passing it your public
// and private keys, as well as some configuration options
$mailHide = new Zend_Service_ReCaptcha_MailHide();
$mailHide->setPublicKey($pubKey);
$mailHide->setPrivateKey($privKey);
$mailHide->setOptions(array(
    'linkTitle' => 'Click me',
    'linkHiddenText' => '+++++',
));

// The mail addresses we want to hide
$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:
-->