ReCaptcha

Das Modul recaptcha beinhaltet einen Tag, der sich nahtlos in die APF-Formulare integriert. Die Konfiguration des Feldes und der Validierung kann dabei wie gewohnt vorgenommen werden.

ReCaptcha ist ein CAPTCHA-Service, der unter http://www.google.com/recaptcha von Google angeboten wird. Der vom Service angebotene Touring-Test gilt als derzeit sicherste Implementierung zur Abwehr von SPAM.

Die folgenden Kapitel beschreiben die Einbindung und Konfiguration im Detail.

1. ReCaptcha-Key

Um ReCaptcha nutzen zu können, registrieren Sie bitte zunächst einen Account unter https://www.google.com/recaptcha/admin/create. Falls Sie noch keinen Google-Account besitzten, haben Sie dort die Möglichkeit einen solchen zu erstellen.

ReCaptcha-Key Antragsformular

Füllen Sie das angezeigte Formularfeld aus und bestätigen Sie die Eingabe mit Klick auf den Button. Anschließend wird Ihnen der generierte Schlüssel angezeigt. Sofern der Schlüssel für mehrere Domains gelten soll, befolgen Sie die beschriebenen Anweisungen.

Speichern oder merken Sie sich die generierten Schlüssel, denn Sie werden sie im Folgenden zur Konfiguration des ReCaptcha-Feldes brauchen.

2. Einbindung

2.1. Basis-Konfiguration

Die Implementierung der APF-ReCaptcha-Funktionalität basiert auf der externen Bibliothek recaptcha, die unter https://github.com/google/recaptcha/ bezogen werden kann.

Zur Aktivierung der Funktionalität laden Sie sich die Bibliothek bitte von der angebenen Adresse herunter und legen diese in Ihrem Projekt ab. Alternativ können Sie die Bibliothek mit composer installieren.

Um die Bibliothek nutzen zu können, fügen Sie den Installations-Pfad zu Ihrem Autoloader hinzu:

PHP-Code
RootClassLoader::addLoader( new StandardClassLoader( 'ReCaptcha', __DIR__ . '/vendor/ReCaptcha' ) );

2.2. Nutzung innerhalb von Formularen

Zur Einbindung des ReCaptcha-Service bringt das Modul einen Tag mit, der sich nicht wesentlich von anderen Tags der Formular-Unterstützung unterscheidet. Er hat folgende Signatur:

APF-Template
<form:recaptcha name="" public-key="" private-key="" [theme="dark|light"] [lang=""] [size="compact|normal"] [tabindex=""] [valmarkerclass=""] />
Beschreibung der Attribute:
  • name: Name des ReCaptcha-Controls. Zur Referenzierung von Validatoren notwendig. (Zeichen: [A-Za-z0-9_-])
  • public-key: Öffentlicher Schlüssel zur Nutzung des ReCaptcha-Service. (Zeichen: [A-Za-z0-9-])
  • private-key: Privater Schlüssel zur Nutzung des ReCaptcha-Service. (Zeichen: [A-Za-z0-9-])
  • theme: Name des Themes. Standard: light. (Zeichen: dark|light)
  • lang: Ausgewählte Sprache zur Anzeige. Sofern nicht angegeben wird die aktuelle Sprache des Dokuments genutzt. Weitere Hinweise hierzu finden Sie in Kapitel 4.2.
  • size: Größe der Anzeige. Standard: normal. (Zeichen: compact|normal)
  • tabindex: Referenziert die Position des Feldes für die Nutzung der Tab-Taste. (Zeichen: [0-9])
  • valmarkerclass: CSS-Klasse, die zur Markierung des Controls im Fehlerfall genutzt wird. Standard: apf-form-error (Zeichen: [A-Za-z0-9-_])
Details zur Konfiguration entnehmen Sie bitte der Dokumentation unter https://developers.google.com/recaptcha/docs/display#config.

Das Feld lässt sich wie folgt nutzen:

APF-Template
<html:form name="newsletter-signup"> <form:error> <p class="error"> Das Formular wurde <strong>nicht</strong> korrekt ausgefüllt! </p> </form:error> <form:success> <p class="error"> Das Formular wurde korrekt ausgefüllt. </p> </form:success> <p> <label for="email">E-Mail-Adresse</label> <form:text name="email" id="email"/> </p> <p> <form:recaptcha name="re-captcha" public-key="123456789012341-0000000000-ABCDE8764Rfc3" private-key="123456Rt3012341-1111111111-ABCDE8764Rfc-P" /> </p> <p> <form:button name="send" value="Abschicken" /> <form:addvalidator class="APF\tools\form\validator\TextLengthValidator" control="email" button="send" /> <form:addvalidator class="APF\tools\form\validator\EMailValidator" control="email" button="send" /> <form:addvalidator class="APF\modules\recaptcha\pres\validator\ReCaptchaValidator" control="re-captcha" button="send" /> </p> </html:form>
Bitte beachten Sie, dass die angegebenen Public- und Private-Keys Beispiele sind und nicht für Ihr Applikation genutzt werden können. Bitte registrieren Sie zur Einbindung ein Key-Paar wie im Kapitel 1 beschrieben.

Zur Anzeige und Verarbeitung des Formulars ist folgender (Document-)Controller notwendig:

PHP-Code
class NewsletterController extends BaseDocumentController { public function transformContent() { $this->getForm('newsletter-signup')->transformOnPlace(); } }

3. Validierung

Wie in Kapitel 2 bereits angedeutet, beinhaltet das Modul recaptcha einen Validator für das ReCaptcha-Control. Wie im Modul CAPTCHA-Taglib (für Formulare) ist es auch hier zwingend notwendig einen Validator zu definieren.

Wird kein Validator für das ReCaptcha-Feld im Formular definiert, ist es wirkungslos und Angreifer können das Formlar ungeschützt aufrufen.

Die Validierung basiert - genauso wie die Generierung der Ausgabe - auf der recaptcha PHP library. Zur einfacheren Verwendung und Einbindung beinhaltet das vorliegende Modul einen Wrapper für APF-Formular-Validatoren. Dieser kann wie folgt auf ein Formular-Element angewendet werden:

APF-Template
<form:addvalidator class="APF\modules\recaptcha\pres\validator\ReCaptchaValidator" control="..." button="..." />

Das Attribut control referenziert das gewünschte ReCaptcha-Feld (siehe Kapitel 2) und button denjenigen Button, der das Validierungs-Event auslösen soll. Details zu Formular-Validatoren finden Sie unter Formulare.

4. Anpassung

Das Google ReCaptcha-Feld lässt sich sehr einfach anpassen. Hierzu stehen bei der Nutzung des APF-Formular-Element eigene Attribute zur Verfügung.

4.1. Themes

Das ReCaptcha-Element verfügt gemäß Dokumentation unter https://developers.google.com/recaptcha/docs/display#config über folgende Themes:

  • light (standard)
  • dark

Diese können mit Hilfe des Attributes theme des <form:recaptcha />-Tags definiert werden.

4.2. Internationalisierung

Das ReCaptcha-Element unterstützt bereits viele Sprachen out-of-the-box. Bei der Generierung des Feldes übergibt der <form:recaptcha />-Tag die aktuell ausgewählte Sprache aus dem Feld $this->language. Zur Steuerung der Sprache können Sie z.B. den unter http://wiki.adventure-php-framework.org/Sprache_per_FC-Action_%C3%A4ndern beschriebenen Code nutzen.

Nutzen Sie keine dynamische Sprachumschaltung, so ist die Sprache entscheiden, die in der Bootstrap-Datei per

PHP-Code
$fC = Singleton::getInstance(Frontcontroller::class); ... $fC->setLanguage('xyz'); ...

definiert wird.

4.3. Tab-Index

Das ReCaptcha-Element unterstützt die Definition der Feld-Reihenfolge für die Verwendung der Tab-Taste. Um den Index festzulegen, definieren Sie bitte das tabindex-Attribut des <form:recaptcha />-Feldes mit der gewünschten Nummer.

Kommentare

Möchten Sie den Artikel eine Anmerkung hinzufügen, oder haben Sie ergänzende Hinweise? Dann können Sie diese hier einfügen. Die bereits verfassten Anmerkungen und Kommentare finden Sie in der untenstehenden Liste.
Für diesen Artikel liegen aktuell keine Kommentare vor.