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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.service.recaptcha">
   4     <title>Zend_Service_ReCaptcha</title>
   5
   6     <sect2 id="zend.service.recaptcha.introduction">
   7         <title>Introduction</title>
   8
   9         <para>
  10             <classname>Zend_Service_ReCaptcha</classname> provides a client for the <ulink
  11                 url="http://recaptcha.net/">reCAPTCHA Web Service</ulink>.
  12             Per the reCAPTCHA site, "reCAPTCHA is a free CAPTCHA service that
  13             helps to digitize books." Each reCAPTCHA requires the user to input
  14             two words, the first of which is the actual CAPTCHA, and the second
  15             of which is a word from some scanned text that Optical Character
  16             Recognition (OCR) software has been unable to identify.
  17             The assumption is that if a user correctly provides the first
  18             word, the second is likely correctly entered as well, and can be
  19             used to improve OCR software for digitizing books.
  20         </para>
  21
  22         <para>
  23             In order to use the reCAPTCHA service, you will need to <ulink
  24                 url="http://recaptcha.net/whyrecaptcha.html">sign up for an
  25                 account</ulink> and register one or more domains with the
  26             service in order to generate public and private keys.
  27         </para>
  28     </sect2>
  29
  30     <sect2 id="zend.service.recaptcha.simplestuse">
  31         <title>Simplest use</title>
  32
  33         <para>
  34             Instantiate a <classname>Zend_Service_ReCaptcha</classname> object, passing it
  35             your public and private keys:
  36         </para>
  37
  38         <example id="zend.service.recaptcha.example-1">
  39             <title>Creating an instance of the reCAPTCHA service</title>
  40
  41             <programlisting language="php"><![CDATA[
  42 $recaptcha = new Zend_Service_ReCaptcha($pubKey, $privKey);
  43 ]]></programlisting>
  44         </example>
  45
  46         <para>
  47             To render the reCAPTCHA, simply call the <methodname>getHTML()</methodname>
  48             method:
  49         </para>
  50
  51         <example id="zend.service.recaptcha.example-2">
  52             <title>Displaying the reCAPTCHA</title>
  53
  54             <programlisting language="php"><![CDATA[
  55 echo $recaptcha->getHTML();
  56 ]]></programlisting>
  57         </example>
  58
  59         <para>
  60             When the form is submitted, you should receive two fields,
  61             'recaptcha_challenge_field' and 'recaptcha_response_field'. Pass
  62             these to the reCAPTCHA object's <methodname>verify()</methodname> method:
  63         </para>
  64
  65         <example id="zend.service.recaptcha.example-3">
  66             <title>Verifying the form fields</title>
  67
  68             <programlisting language="php"><![CDATA[
  69 $result = $recaptcha->verify(
  70     $_POST['recaptcha_challenge_field'],
  71     $_POST['recaptcha_response_field']
  72 );
  73 ]]></programlisting>
  74         </example>
  75
  76         <para>
  77             Once you have the result, test against it to see if it is valid. The
  78             result is a <classname>Zend_Service_ReCaptcha_Response</classname> object,
  79             which provides an <methodname>isValid()</methodname> method.
  80         </para>
  81
  82         <example id="zend.service.recaptcha.example-4">
  83             <title>Validating the reCAPTCHA</title>
  84
  85             <programlisting language="php"><![CDATA[
  86 if (!$result->isValid()) {
  87     // Failed validation
  88 }
  89 ]]></programlisting>
  90         </example>
  91
  92         <para>
  93             It is even simpler to use <link
  94                 linkend="zend.captcha.adapters.recaptcha">the reCAPTCHA</link>
  95             <classname>Zend_Captcha</classname> adapter, or to use that adapter as a
  96             backend for the <link
  97                 linkend="zend.form.standardElements.captcha">CAPTCHA form
  98                 element</link>. In each case, the details of rendering and
  99             validating the reCAPTCHA are automated for you.
 100         </para>
 101     </sect2>
 102
 103     <sect2 id="zend.service.recaptcha.mailhide">
 104         <title>Hiding email addresses</title>
 105
 106         <para>
 107             <classname>Zend_Service_ReCaptcha_MailHide</classname> can be used to hide email
 108             addresses. It will replace a part of an email address with a link that opens a popup
 109             window with a reCAPTCHA challenge. Solving the challenge will reveal the complete
 110             email address.
 111         </para>
 112
 113         <para>
 114             In order to use this component you will need
 115             <ulink url="http://recaptcha.net/whyrecaptcha.html">an account</ulink> to generate
 116             public and private keys for the mailhide API.
 117         </para>
 118
 119         <example id="zend.service.recaptcha.mailhide.example-1">
 120             <title>Using the mail hide component</title>
 121
 122             <programlisting language="php"><![CDATA[
 123 // The mail address we want to hide
 124 $mail = 'mail@example.com';
 125
 126 // Create an instance of the mailhide component, passing it your public
 127 // and private keys, as well as the mail address you want to hide
 128 $mailHide = new Zend_Service_ReCaptcha_Mailhide();
 129 $mailHide->setPublicKey($pubKey);
 130 $mailHide->setPrivateKey($privKey);
 131 $mailHide->setEmail($mail);
 132
 133 // Display it
 134 print($mailHide);
 135 ]]></programlisting>
 136         </example>
 137
 138         <para>
 139             The example above will display "m...@example.com" where "..." has a link that opens up
 140             a popup window with a reCAPTCHA challenge.
 141         </para>
 142
 143         <para>
 144             The public key, private key, and the email address can also be specified in the
 145             constructor of the class. A fourth argument also exists that enables you to set some
 146             options for the component. The available options are listed in the following table:
 147
 148             <table id="zend.service.recaptcha.mailhide.options.table">
 149                 <title>Zend_Service_ReCaptcha_MailHide options</title>
 150
 151                 <tgroup cols="4">
 152                     <thead>
 153                         <row>
 154                             <entry>Option</entry>
 155                             <entry>Description</entry>
 156                             <entry>Expected Values</entry>
 157                             <entry>Default Value</entry>
 158                         </row>
 159                     </thead>
 160
 161                     <tbody>
 162                         <row>
 163                             <entry>linkTitle</entry>
 164                             <entry>The title attribute of the link</entry>
 165                             <entry>string</entry>
 166                             <entry>'Reveal this e-mail address'</entry>
 167                         </row>
 168
 169                         <row>
 170                             <entry>linkHiddenText</entry>
 171                             <entry>The text that includes the popup link</entry>
 172                             <entry>string</entry>
 173                             <entry>'...'</entry>
 174                         </row>
 175
 176                         <row>
 177                             <entry>popupWidth</entry>
 178                             <entry>The width of the popup window</entry>
 179                             <entry>int</entry>
 180                             <entry>500</entry>
 181                         </row>
 182
 183                         <row>
 184                             <entry>popupHeight</entry>
 185                             <entry>The height of the popup window</entry>
 186                             <entry>int</entry>
 187                             <entry>300</entry>
 188                         </row>
 189                     </tbody>
 190                 </tgroup>
 191             </table>
 192         </para>
 193
 194         <para>
 195             The configuration options can be set by sending them as the fourth argument to the
 196             constructor or by calling <methodname>setOptions($options)</methodname>, which takes
 197             an associative array or an instance of <link linkend="zend.config">Zend_Config</link>.
 198         </para>
 199
 200         <example id="zend.service.recaptcha.mailhide.example-2">
 201             <title>Generating many hidden email addresses</title>
 202
 203             <programlisting language="php"><![CDATA[
 204 // Create an instance of the mailhide component, passing it your public
 205 // and private keys, as well as some configuration options
 206 $mailHide = new Zend_Service_ReCaptcha_Mailhide();
 207 $mailHide->setPublicKey($pubKey);
 208 $mailHide->setPrivateKey($privKey);
 209 $mailHide->setOptions(array(
 210     'linkTitle' => 'Click me',
 211     'linkHiddenText' => '+++++',
 212 ));
 213
 214 // The mail addresses we want to hide
 215 $mailAddresses = array(
 216     'mail@example.com',
 217     'johndoe@example.com',
 218     'janedoe@example.com',
 219 );
 220
 221 foreach ($mailAddresses as $mail) {
 222     $mailHide->setEmail($mail);
 223     print($mailHide);
 224 }
 225 ]]></programlisting>
 226         </example>
 227     </sect2>
 228 </sect1>
 229 <!--
 230 vim:se ts=4 sw=4 et:
 231 -->