Filter und Hooks

Das Procaptcha-Plugin führt neue WordPress-Filter und Hooks ein, die es Ihnen ermöglichen, sein Verhalten anzupassen.

1. CAPTCHA-Sichtbarkeit

Standardmäßig wird Procaptcha nur nicht autorisierten Benutzern angezeigt.

Um dieses Verhalten zu steuern, können Sie neben den Plugin-Einstellungen auch den is_captcha_present-Hook verwenden. Um beispielsweise Procaptcha für alle erforderlich zu machen, fügen Sie folgenden Code zur functions.php-Datei Ihres Themes hinzu:

add_filter('prosopo/procaptcha/is_captcha_present', '__return_true');`

2. Benutzerdefinierte Fehlermeldung

Sie können die Standard-Fehlermeldung anpassen, indem Sie diesen Code zur functions.php-Datei Ihres Themes hinzufügen:

add_filter('prosopo/procaptcha/validation_error_message', function (string $message): string {
    return __('Custom error message', 'my-theme');
});

3. Anpassen von Procaptcha-Attributen

Über die Stilpräferenzen in den Plugin-Einstellungen hinaus können Sie alle unterstützten Procaptcha-Datenattribute mit dem prosopo/procaptcha/captcha_attributes-Filter anpassen.

add_filter('prosopo/procaptcha/captcha_attributes', function (array $attributes): array {
    $attributes['language'] = 'de';
    return $attributes;
});

4. Abgleich der Besucher-IP

Ist der IP-Abgleich aktiv, sendet das Plugin die IP-Adresse des Besuchers mit jeder Verifizierungsanfrage, und Procaptcha lehnt ein Token ab, das von einer anderen IP gelöst wurde. Er ist standardmäßig aus: Die meisten Websites laufen hinter Cloudflare oder einem anderen Proxy, und würde die Adresse des Proxys statt der des Besuchers gesendet, würden echte Besucher abgelehnt.

Zum Einschalten öffnen Sie Einstellungen > Prosopo Procaptcha > General und wählen unter Abgleich der Besucher-IP, woher die IP des Besuchers stammt:

An – Website läuft hinter Cloudflare: der Header CF-Connecting-IP.
An – Website läuft hinter einem anderen Proxy: die erste Adresse im Header X-Forwarded-For.
An – Besucher verbinden sich direkt: REMOTE_ADDR.

Wählen Sie nur einen Header, den Ihr Proxy setzt, da Besucher diese Header selbst senden können. Fehlt der Header oder ist er keine gültige IP-Adresse, wird nichts gesendet und das Token ohne IP-Abgleich verifiziert.

Für andere Konfigurationen erhält der Filter prosopo/procaptcha/visitor_ip die IP aus der Einstellung (leer, wenn sie aus ist) und REMOTE_ADDR. Geben Sie die zu sendende IP zurück oder einen leeren String, um keine zu senden:

add_filter('prosopo/procaptcha/visitor_ip', function (string $ip, string $remote_addr): string {
    return $_SERVER['HTTP_TRUE_CLIENT_IP'] ?? $ip;
}, 10, 2);

Version 1.23.0 hat standardmäßig REMOTE_ADDR gesendet. Aktualisieren Sie auf 1.24.0 oder neuer, wenn Ihre Website hinter einem Proxy läuft.

5. Verifizierungsergebnis

Ab Version 1.24.0 wird die Action prosopo/procaptcha/verification_result nach jeder Verifizierungsanfrage mit dem Ergebnis und der API-Antwort ausgeführt. So können Sie den Score oder den Grund für eine abgelehnte Übermittlung erfassen. Wenn WP_DEBUG aktiv ist, werden fehlgeschlagene Verifizierungen außerdem ins Debug-Log geschrieben.

add_action('prosopo/procaptcha/verification_result', function (bool $verified, array $response): void {
    // $response: verified, status, score, reason, error, sessionId
    if (! $verified) {
        error_log('Procaptcha rejected a submission: ' . ($response['reason'] ?? 'unknown'));
    }
}, 10, 2);

6. JavaScript-Ereignisse

Ab Version 1.24.0 löst das Widget diese Ereignisse aus, die bis zum Formular und zum Dokument aufsteigen:

prosopo-procaptcha:filled: Der Besucher hat das CAPTCHA gelöst. event.detail.token enthält das Token.
prosopo-procaptcha:cleared: Das Token ist abgelaufen, im Widget ist ein Fehler aufgetreten oder es wurde zurückgesetzt.

Ein Token kann nur einmal verifiziert werden. Das Plugin setzt das CAPTCHA nach AJAX-Übermittlungen der unterstützten Formular-Plugins zurück. Lösen Sie bei eigenen AJAX-Formularen prosopo-procaptcha:reset auf dem Formular aus (oder auf einem Element, das das CAPTCHA enthält, oder auf document, um alle zurückzusetzen):

document.addEventListener('prosopo-procaptcha:filled', (event) => {
    console.log('Token received', event.detail.token);
});

document.addEventListener('prosopo-procaptcha:cleared', (event) => {
    console.log('Token expired or the widget was reset', event.target);
});

// Reset the captcha in a form, e.g. after your own AJAX submission.
form.dispatchEvent(new Event('prosopo-procaptcha:reset'));

7. Formulare mit Procaptcha in Tests

Wenn Ihre Tests Formulare mit Procaptcha umfassen, können Sie das Procaptcha umgehen, indem Sie die folgende Konstante zu Ihrer wp-config.php-Datei hinzufügen:

define('PROSOPO_PROCAPTCHA_ALLOW_BYPASS', true);

Fügen Sie in Ihren Tests ein input[name=procaptcha-response]-Element mit dem Wert bypass zu jedem Formular hinzu, um den Procaptcha-Abschluss zu simulieren.

Wichtig: Diese Bypass-Konstante sollte nur in Entwicklungsumgebungen verwendet werden.