# Zend_Service_ReCaptcha

## Einführung

`Zend_Service_ReCaptcha` bietet einen Client für das reCAPTCHA Web Service. Laut der reCAPTCHA Seite ist "reCAPTCHA ein freies CAPTCHA Service das hilft Bücher zu digitalisieren." Jedes reCAPTCHA verlangt das der Benutzer zwei Wörter eingibt, das erste ist das aktuelle CAPTCHA, und das zweite ist ein Wort von einem eingescannten Text bei dem Software für optische Zeichenerkennung (OCR) keine Identifizierung durchführen kann. Die Annahme ist das, wenn der Benutzer das erste Wort richtig angegeben hat, dass dann das zweite auch korrekt angegeben wird, und das dieses dann verwendet werden kann um OCR Software für die Digitalisierung von Büchern zu verbessern.

Um den reCAPTCHA Service zu verwenden muß man einen Account unterzeichnen und eine oder mehrere Domains beim Service registrieren um öffentliche und private Schlüssel zu erzeugen.

## Einfachste Verwendung

Ein `Zend_Service_ReCaptcha` Objekt instanzieren, und ihm den öffentlichen und privaten Schlüssel übergeben:

### Erstellung einer Instanz des reCAPTCHA Services

    $recaptcha = new Zend_Service_ReCaptcha($pubKey, $privKey);

Um das reCAPTCHA darzustellen, muß einfach die `getHTML()` Methode aufgerufen werden:

### Das reCAPTCHA darstellen

    echo $recaptcha->getHTML();

Wenn das Formular übertragen wurde, sollte man zwei Felder empfangen haben, 'recaptcha_challenge_field' und 'recaptcha_response_field'. Diese sind an die `verify()` Methode des reCAPTCHA Objekts zu übergeben:

### Das Formular Feld verifizieren

    $result = $recaptcha->verify(
        $_POST['recaptcha_challenge_field'],
        $_POST['recaptcha_response_field']
    );

Sobald man das Ergebnis hat, kann es getestet werden um zu sehen ob es gültig ist. Das Ergebnis ist ein `Zend_Service_ReCaptcha_Response` Objekt, welche eine `isValid()` Methode anbietet.

### Das reCAPTCHA prüfen

    if (!$result->isValid()) {
        // Fehlerhafte Prüfung
    }

Noch einfacher zu verwenden ist der ReCaptcha `Zend_Captcha` Adapter, oder man verwendet diesen Adapter als Backend für das CAPTCHA Formularelement. In jedem Fall werden die Details der Darstellung und Prüfung des reCAPTCHA automatisch durchgeführt.

## Email Adressen verstecken

`Zend_Service_ReCaptcha_MailHide` kann verwendet werden um Email Adressen zu verstecken. Es ersetzt den Teil der Email Adresse mit einem Link der ein Popup Fenster mit einer reCAPTCHA Challenge öffnet. Das Lösen der Challenge gibt die komplette Email Adresse zurück.

Um diese Komponente zu verwenden benötigt man einen Account um öffentliche und private Schlüssel für die Mailhide API erstellen.

### Verwenden der Mail Hide Komponente

    // Die Mail Adresse die wir verstecken wollen
    $mail = 'mail@example.com';

    // Eine Instanz der Mailhide Komponente erstellen, dieser die öffentlichen und
    // privaten Schlüssel übergeben sowie die Mail Adresse die man verstecken will
    $mailHide = new Zend_Service_ReCaptcha_Mailhide();
    $mailHide->setPublicKey($pubKey);
    $mailHide->setPrivateKey($privKey);
    $mailHide->setEmail($mail);

    // Es darstellen
    print($mailHide);

Das obige Beispiel zeigt "m...@example.com" wobei "..." einen Link enthält der sich mit einem Popup Fenster und einer reCAPTCHA Challenge öffnet.

Der öffentliche Schlüssel, der private Schlüssel, und die Email Adresse können auch im Konstruktor der Klasse spezifiziert werden. Es existiert ein viertes Argument das es erlaubt einige Optionen für die Komponente zu setzen. Die vorhandenen Optionen sind in der folgenden Tabelle aufgelistet:

### Zend_Service_ReCaptcha_MailHide options

Option | Beschreibung | Erwartete Werte | Standard Werte
--- | --- | --- | ---
linkTitle | Das Titel Attribut des Links | string | 'Reveal this e-mail address'
linkHiddenText | Der Text welche den Popup Link enthält | string | '...'
popupWidth | Die Breite des Popup Fensters | int | 500
popupHeight | Die Höhe des Popup Fensters | int | 300

Die Konfigurations Optionen können gesetzt werden indem Sie als viertes Argument an den Konstruktor gesendet werden oder indem die `setOptions($options)` aufgerufen wird, welche ein assoziatives Array oder eine Instanz von Zend_Config entgegen nimmt.

### Viele versteckte Email Adressen erzeugen

    // Eine Instanz der Mailhide Komponente erstellen, dieser die öffentlichen und
    // privaten Schlüssel übergeben sowie einige Konfigurations Optionen
    $mailHide = new Zend_Service_ReCaptcha_Mailhide();
    $mailHide->setPublicKey($pubKey);
    $mailHide->setPrivateKey($privKey);
    $mailHide->setOptions(array(
        'linkTitle' => 'Click me',
        'linkHiddenText' => '+++++',
    ));

    // Die Mail Adressen die wir verstecken wollen
    $mailAddresses = array(
        'mail@example.com',
        'johndoe@example.com',
        'janedoe@example.com',
    );

    foreach ($mailAddresses as $mail) {
        $mailHide->setEmail($mail);
        print($mailHide);
    }