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 sind erfüllt:

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 mit der Versionsangabe ^2.0.1:

composer require "myra-security-gmbh/eu-captcha:^2.0.1"

Achtung

Ohne die Versionsangabe ^2.0.1 installiert Composer unter PHP 5 bis PHP 7 ohne Hinweis die alte Version 1.x. Deren Klasse EU_Captcha passt nicht zu den Beispielen dieser Seite. Die Versionsangabe schließt außerdem Version 2.0.0 aus: Sie sendet Anfragefelder, die die API ablehnt, sodass jede Prüfung fehlschlägt. Behalten Sie die Anführungszeichen bei, damit cmd.exe unter Windows das Zeichen ^ nicht entfernt.

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

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

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>

Hinweis

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']. Fehlt dieses Feld in $_POST, wertet die Methode den Rumpf der Anfrage als JSON aus. Bei eu-captcha geschieht das nur, wenn der Medientyp der Anfrage application/json ist oder auf +json endet, etwa application/vnd.api+json. Parameter wie charset bleiben unberücksichtigt. Nur ein einfacher Wert gilt als Token. Ein Feld oder ein Objekt an dieser Stelle übergeht die Methode. Findet die Methode kein Token, sendet sie ein leeres Token an die API. Die API zählt den Versuch dann trotzdem. 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.
`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`.

Nur eu-captcha für PHP 8 kennt zusätzlich die folgende Option:

Option	Typ	Vorgabe	Wirkung
`client`	`?Client`	`null`	Eigene Instanz von Guzzle für abweichende Einstellungen oder für Tests.

Das Ergebnisobjekt

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

Methode	Gibt `true` zurück, wenn
`success()`	die API erreichbar war, das Token gültig ist und die API `train` nicht gesetzt hat.
`successNetwork()`	der Aufruf der API ohne Netzwerk- oder Übertragungsfehler abgeschlossen wurde.
`successToken()`	die API das übermittelte Token als gültig gemeldet hat.
`isTrain()`	die API das Feld `train` gesetzt hat. Die API hat das Token dann nicht geprüft. Ohne Antwort der API gibt die Methode `null` zurück.

success() wertet eine Antwort mit train: true als Fehlschlag. successToken() gibt dagegen den unveränderten Wert success der Antwort zurück.

Die API setzt train, wenn für den Sitekey der Trainingsmodus aktiv oder der Schutz abgeschaltet ist. Ein unbekannter Sitekey oder ein falsches Secret setzt train nicht. Die Prüfung schlägt dann mit success: false fehl.

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.

PHP