PHP

Für PHP stehen zwei Pakete bereit. Beide prüfen das Token auf dem Server und geben dasselbe Ergebnisobjekt zurück.

Paket wählen

Wählen Sie das Paket zur PHP-Version Ihrer Anwendung:

Paket	PHP	Technik
myra-security-gmbh/eu-captcha	ab Version 8.0	Benannte Argumente, Typangaben, HTTP über Guzzle (guzzlehttp/guzzle ^6.0 oder ^7.0)
myra-security-gmbh/eu-captcha-old	ab Version 5.0	Ohne weitere Abhängigkeiten, HTTP über file_get_contents() mit einem Stream-Kontext

Voraussetzungen

Die folgenden Voraussetzungen müssen erfüllt sein:

Voraussetzung	Wert
PHP	ab Version 8.0 für eu-captcha, ab Version 5.0 für eu-captcha-old
Composer	Zugriff auf die Kommandozeile des Servers
Zugangsdaten	Öffentlicher Sitekey und Secret aus der Ansicht Details

Paket installieren

Installieren Sie das Paket für PHP 8:

composer require myra-security-gmbh/eu-captcha

Für PHP 5 bis PHP 7 installieren Sie stattdessen:

composer require myra-security-gmbh/eu-captcha-old

Widget einbinden

Ergänzen Sie jede Seite mit einem zu schützenden Formular um den Skript-Verweis:

<script src="https://cdn.eu-captcha.eu/verify.js" async defer></script>

Fügen Sie das Widget in das Formular ein:

<div class="eu-captcha" data-sitekey="EUCAPTCHA_SITE_KEY"></div>

Note

Bei einer Single-Page-Anwendung mit React, Vue oder Angular binden Sie das Widget über das jeweilige npm-Paket ein. Das PHP-Paket übernimmt dann allein die serverseitige Prüfung.

Token prüfen

Prüfen Sie das übermittelte Token auf dem Server:

<?php

use Myrasec\EuCaptcha;

$captcha = new EuCaptcha(
    sitekey: EUCAPTCHA_SITE_KEY,
    secret:  EUCAPTCHA_SECRET_KEY,
);

$result = $captcha->validate();

if (!$result->success()) {
    // Reject the form submission
}

Mit eu-captcha-old übergeben Sie die Werte stattdessen als assoziatives Feld:

<?php

use Myrasec\EuCaptcha;

$captcha = new EuCaptcha([
    'sitekey' => EUCAPTCHA_SITE_KEY,
    'secret'  => EUCAPTCHA_SECRET_KEY,
]);

$result = $captcha->validate();

validate() liest das Token aus $_POST['eu-captcha-response']. Ist $_POST leer, wertet die Methode den Rumpf der Anfrage als JSON aus. Die IP-Adresse des Besuchers ermittelt die Methode aus den Kopfzeilen der Anfrage.

Optionen

Die folgenden Optionen stehen zur Verfügung:

Option	Typ	Vorgabe	Wirkung
sitekey	string	—	Öffentlicher Sitekey. Der Wert ist erforderlich.
secret	string	—	Geheimer Schlüssel. Der Wert ist erforderlich und darf nicht im Browser erscheinen.
failDefault	bool	true	Rückgabewert für den Netzwerk- und den Token-Zustand, wenn die API nicht erreichbar ist. true lässt die Absendung zu, false weist sie ab.
checkCdnHeaders	bool	true	Ermittelt die IP-Adresse des Besuchers aus den Kopfzeilen HTTP_CLIENT_IP, HTTP_X_FORWARDED_FOR und HTTP_X_REAL_IP, bevor REMOTE_ADDR verwendet wird. Setzen Sie den Wert auf false, wenn der Server nicht hinter einem vorgelagerten System steht oder Sie die IP-Adresse selbst übergeben.

Nur eu-captcha für PHP 8 kennt zusätzlich die folgenden Optionen:

Option	Typ	Vorgabe	Wirkung
verifyUrl	string	Adresse der Produktivumgebung	Überschreibt die Adresse des Endpunkts /verify. Verwenden Sie die Option für Tests.
credentialsUrl	string	Adresse der Produktivumgebung	Überschreibt die Adresse des Endpunkts /verify-credentials.
client	?Client	null	Eigene Instanz von Guzzle für abweichende Einstellungen oder für Tests.

Das Ergebnisobjekt

validate() gibt ein Objekt EuCaptchaResult mit drei Methoden zurück:

Methode	Gibt true zurück, wenn
success()	die API erreichbar war und das Token gültig ist.
successNetwork()	der Aufruf der API ohne Netzwerk- oder Übertragungsfehler abgeschlossen wurde.
successToken()	die API das übermittelte Token als gültig gemeldet hat.

Die getrennte Abfrage unterscheidet eine nicht bestandene Challenge von einer Störung der API:

<?php

$result = $captcha->validate();

if (!$result->successNetwork()) {
    // Could not reach the API — consider logging or alerting
}

if (!$result->successToken()) {
    // Token was rejected — the submission is likely automated
}

Token und IP-Adresse selbst übergeben

Bei abweichenden Feldnamen übergeben Sie Token und IP-Adresse selbst:

<?php

$token    = $_POST['my-captcha-field'] ?? '';
$clientIp = $_SERVER['REMOTE_ADDR'];

$result = $captcha->validate($token, $clientIp);

Zugangsdaten prüfen

Mit verifyCredentials() prüfen Sie Sitekey und Secret ohne ein Token des Browsers, zum Beispiel beim Start der Anwendung:

<?php

$captcha = new EuCaptcha(sitekey: EUCAPTCHA_SITE_KEY, secret: EUCAPTCHA_SECRET_KEY);

if (!$captcha->verifyCredentials()) {
    // Credentials are invalid or the API is unreachable — log and alert
}

Bei einem Netzwerk- oder API-Fehler gibt die Methode false zurück und löst keine Ausnahme aus. Der Aufruf ist damit auch während der Initialisierung sicher.

Siehe Endpunkt /verify-credentials.

Symfony und Laravel

Für beide Rahmenwerke siehe Symfony und Laravel.

Vollständiges Beispiel

Siehe React und PHP.