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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- EN-Revision: 21819 -->
   3 <!-- Reviewed: no -->
   4 <sect1 id="zend.service.recaptcha">
   5     <title>Zend_Service_ReCaptcha</title>
   6
   7     <sect2 id="zend.service.recaptcha.introduction">
   8         <title>Einführung</title>
   9
  10         <para>
  11             <classname>Zend_Service_ReCaptcha</classname> bietet einen Client für das <ulink
  12                 url="http://recaptcha.net/">reCAPTCHA Web Service</ulink>. Laut der reCAPTCHA Seite
  13             ist "reCAPTCHA ein freies CAPTCHA Service das hilft Bücher zu digitalisieren." Jedes
  14             reCAPTCHA verlangt das der Benutzer zwei Wörter eingibt, das erste ist das aktuelle
  15             CAPTCHA, und das zweite ist ein Wort von einem eingescannten Text bei dem Software für
  16             optische Zeichenerkennung (OCR) keine Identifizierung durchführen kann. Die Annahme ist
  17             das, wenn der Benutzer das erste Wort richtig angegeben hat, dass dann das zweite auch
  18             korrekt angegeben wird, und das dieses dann verwendet werden kann um OCR Software für
  19             die Digitalisierung von Büchern zu verbessern.
  20         </para>
  21
  22         <para>
  23             Um den reCAPTCHA Service zu verwenden muß man
  24             <ulink url="http://recaptcha.net/whyrecaptcha.html">einen Account unterzeichnen</ulink>
  25             und eine oder mehrere Domains beim Service registrieren um öffentliche und private
  26             Schlüssel zu erzeugen.
  27         </para>
  28     </sect2>
  29
  30     <sect2 id="zend.service.recaptcha.simplestuse">
  31         <title>Einfachste Verwendung</title>
  32
  33         <para>
  34             Ein <classname>Zend_Service_ReCaptcha</classname> Objekt instanzieren, und ihm den
  35             öffentlichen und privaten Schlüssel übergeben:
  36         </para>
  37
  38         <example id="zend.service.recaptcha.example-1">
  39             <title>Erstellung einer Instanz des reCAPTCHA Services</title>
  40
  41             <programlisting language="php"><![CDATA[
  42 $recaptcha = new Zend_Service_ReCaptcha($pubKey, $privKey);
  43 ]]></programlisting>
  44         </example>
  45
  46         <para>
  47             Um das reCAPTCHA darzustellen, muß einfach die <methodname>getHTML()</methodname>
  48             Methode aufgerufen werden:
  49         </para>
  50
  51         <example id="zend.service.recaptcha.example-2">
  52             <title>Das reCAPTCHA darstellen</title>
  53
  54             <programlisting language="php"><![CDATA[
  55 echo $recaptcha->getHTML();
  56 ]]></programlisting>
  57         </example>
  58
  59         <para>
  60             Wenn das Formular übertragen wurde, sollte man zwei Felder empfangen haben,
  61             'recaptcha_challenge_field' und 'recaptcha_response_field'. Diese sind an die
  62             <methodname>verify()</methodname> Methode des reCAPTCHA Objekts zu übergeben:
  63         </para>
  64
  65         <example id="zend.service.recaptcha.example-3">
  66             <title>Das Formular Feld verifizieren</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             Sobald man das Ergebnis hat, kann es getestet werden um zu sehen ob es gültig ist. Das
  78             Ergebnis ist ein <classname>Zend_Service_ReCaptcha_Response</classname> Objekt, welche
  79             eine <methodname>isValid()</methodname> Methode anbietet.
  80         </para>
  81
  82         <example id="zend.service.recaptcha.example-4">
  83             <title>Das reCAPTCHA prüfen</title>
  84
  85             <programlisting language="php"><![CDATA[
  86 if (!$result->isValid()) {
  87     // Fehlerhafte Prüfung
  88 }
  89 ]]></programlisting>
  90         </example>
  91
  92         <para>
  93             Noch einfacher zu verwenden ist
  94             <link linkend="zend.captcha.adapters.recaptcha">der ReCaptcha</link>
  95             <classname>Zend_Captcha</classname> Adapter, oder man verwendet diesen Adapter als
  96             Backend für das <link
  97                 linkend="zend.form.standardElements.captcha">CAPTCHA Formularelement</link>.
  98             In jedem Fall werden die Details der Darstellung und Prüfung des reCAPTCHA
  99             automatisch durchgeführt.
 100         </para>
 101     </sect2>
 102
 103     <sect2 id="zend.service.recaptcha.mailhide">
 104         <title>Email Adressen verstecken</title>
 105
 106         <para>
 107             <classname>Zend_Service_ReCaptcha_MailHide</classname> kann verwendet werden um Email
 108             Adressen zu verstecken. Es ersetzt den Teil der Email Adresse mit einem Link der ein
 109             Popup Fenster mit einer reCAPTCHA Challenge öffnet. Das Lösen der Challenge gibt die
 110             komplette Email Adresse zurück.
 111         </para>
 112
 113         <para>
 114             Um diese Komponente zu verwenden benötigt man
 115             <ulink url="http://recaptcha.net/whyrecaptcha.html">einen Account</ulink> um
 116             öffentliche und private Schlüssel für die Mailhide <acronym>API</acronym> erstellen.
 117         </para>
 118
 119         <example id="zend.service.recaptcha.mailhide.example-1">
 120             <title>Verwenden der Mail Hide Komponente</title>
 121
 122             <programlisting language="php"><![CDATA[
 123 // Die Mail Adresse die wir verstecken wollen
 124 $mail = 'mail@example.com';
 125
 126 // Eine Instanz der Mailhide Komponente erstellen, dieser die öffentlichen und
 127 // privaten Schlüssel übergeben sowie die Mail Adresse die man verstecken will
 128 $mailHide = new Zend_Service_ReCaptcha_Mailhide();
 129 $mailHide->setPublicKey($pubKey);
 130 $mailHide->setPrivateKey($privKey);
 131 $mailHide->setEmail($mail);
 132
 133 // Es darstellen
 134 print($mailHide);
 135 ]]></programlisting>
 136         </example>
 137
 138         <para>
 139             Das obige Beispiel zeigt "m...@example.com" wobei "..." einen Link enthält der sich
 140             mit einem Popup Fenster und einer reCAPTCHA Challenge öffnet.
 141         </para>
 142
 143         <para>
 144             Der öffentliche Schlüssel, der private Schlüssel, und die Email Adresse können auch im
 145             Konstruktor der Klasse spezifiziert werden. Es existiert ein viertes Argument das es
 146             erlaubt einige Optionen für die Komponente zu setzen. Die vorhandenen Optionen sind in
 147             der folgenden Tabelle aufgelistet:
 148
 149             <table id="zend.service.recaptcha.mailhide.options.table">
 150                 <title>Zend_Service_ReCaptcha_MailHide options</title>
 151
 152                 <tgroup cols="4">
 153                     <thead>
 154                         <row>
 155                             <entry>Option</entry>
 156                             <entry>Beschreibung</entry>
 157                             <entry>Erwartete Werte</entry>
 158                             <entry>Standard Werte</entry>
 159                         </row>
 160                     </thead>
 161
 162                     <tbody>
 163                         <row>
 164                             <entry>linkTitle</entry>
 165                             <entry>Das Titel Attribut des Links</entry>
 166                             <entry>string</entry>
 167                             <entry>'Reveal this e-mail address'</entry>
 168                         </row>
 169
 170                         <row>
 171                             <entry>linkHiddenText</entry>
 172                             <entry>Der Text welche den Popup Link enthält</entry>
 173                             <entry>string</entry>
 174                             <entry>'...'</entry>
 175                         </row>
 176
 177                         <row>
 178                             <entry>popupWidth</entry>
 179                             <entry>Die Breite des Popup Fensters</entry>
 180                             <entry>int</entry>
 181                             <entry>500</entry>
 182                         </row>
 183
 184                         <row>
 185                             <entry>popupHeight</entry>
 186                             <entry>Die Höhe des Popup Fensters</entry>
 187                             <entry>int</entry>
 188                             <entry>300</entry>
 189                         </row>
 190                     </tbody>
 191                 </tgroup>
 192             </table>
 193         </para>
 194
 195         <para>
 196             Die Konfigurations Optionen können gesetzt werden indem Sie als viertes Argument an den
 197             Konstruktor gesendet werden oder indem die <methodname>setOptions($options)</methodname>
 198             aufgerufen wird, welche ein assoziatives Array oder eine Instanz von
 199             <link linkend="zend.config">Zend_Config</link> entgegen nimmt.
 200         </para>
 201
 202         <example id="zend.service.recaptcha.mailhide.example-2">
 203             <title>Viele versteckte Email Adressen erzeugen</title>
 204
 205             <programlisting language="php"><![CDATA[
 206 // Eine Instanz der Mailhide Komponente erstellen, dieser die öffentlichen und
 207 // privaten Schlüssel übergeben sowie einige Konfigurations Optionen
 208 $mailHide = new Zend_Service_ReCaptcha_Mailhide();
 209 $mailHide->setPublicKey($pubKey);
 210 $mailHide->setPrivateKey($privKey);
 211 $mailHide->setOptions(array(
 212     'linkTitle' => 'Click me',
 213     'linkHiddenText' => '+++++',
 214 ));
 215
 216 // Die Mail Adressen die wir verstecken wollen
 217 $mailAddresses = array(
 218     'mail@example.com',
 219     'johndoe@example.com',
 220     'janedoe@example.com',
 221 );
 222
 223 foreach ($mailAddresses as $mail) {
 224     $mailHide->setEmail($mail);
 225     print($mailHide);
 226 }
 227 ]]></programlisting>
 228         </example>
 229     </sect2>
 230 </sect1>