ALTCHA Spam-Schutz: Erweiterbarkeit

Erweiterungspunkte des ALTCHA Spam-Schutz Moduls für OXID 7: eigene Formulare über SpamProtectionFacade prüfen, Widget in eigenen Templates verwenden, Ablehnungsgründe und Fehlermeldungs-Schlüssel.

English Version

Zurück zur Übersicht

ALTCHA Spam-Schutz: Erweiterbarkeit

Live Demo: Teste dieses und weitere Plugins live — ohne Installation, ohne Risiko: demo.markus-michalski.net

Das Modul schützt von sich aus nur Kontakt, Newsletter und Registrierung. Für eigene Formulare kannst du dieselbe Prüfkette nutzen. Die Klassen sind kein dokumentiertes Public API mit Stabilitätsgarantie, sie liegen im Namensraum Mmd\AltchaIntegration und werden hier so beschrieben, wie sie im Code stehen.

Eigenes Formular serverseitig prüfen

Der Service SpamProtectionFacade ist im Container öffentlich registriert und führt die gesamte Prüfkette aus. Eine eigene Controller-Erweiterung ruft ihn vor der eigentlichen Verarbeitung auf:

use Mmd\AltchaIntegration\Service\SpamProtectionFacade;
use Mmd\AltchaIntegration\Struct\SpamCheckRequest;
use OxidEsales\Eshop\Core\Registry;
use OxidEsales\EshopCommunity\Internal\Container\ContainerFactory;

$facade = ContainerFactory::getInstance()
    ->getContainer()
    ->get(SpamProtectionFacade::class);

$request = Registry::getRequest();

$result = $facade->validate(new SpamCheckRequest(
    action: 'my_form',
    ipAddress: $clientIp,
    altchaPayload: (string) $request->getRequestParameter('altcha'),
    honeypotValue: (string) $request->getRequestParameter($facade->getHoneypotFieldName()),
    formData: [
        'email' => $email,
        'firstName' => $firstName,
        'lastName' => $lastName,
    ],
));

if (!$result->isValid()) {
    // $result->reason und $result->retryAfterSeconds auswerten
}

Feld von `SpamCheckRequest`	Bedeutung
`action`	Name des Formulars, höchstens 50 Zeichen. Das Rate Limit zählt pro Aktion und Client getrennt
`ipAddress`	Client-Adresse. Das Modul ermittelt sie in seinen eigenen Erweiterungen aus `X-Forwarded-For` (erster Eintrag) oder `REMOTE_ADDR`
`altchaPayload`	Inhalt des POST-Felds `altcha`
`honeypotValue`	Inhalt des Honeypot-Felds
`formData`	Optional. Ausgewertet werden nur `email`, `firstName`, `lastName` und `billingAddress` mit `street` und `city`. Ist das Array leer, entfällt die Inhaltsvalidierung

Ist der Spam-Schutz insgesamt ausgeschaltet, liefert validate() immer ein gültiges Ergebnis.

Ablehnungsgründe

$result->reason enthält einen dieser Werte:

Grund	Ursache	Meldungsschlüssel in den mitgelieferten Controllern
`honeypot_triggered`	Honeypot-Feld nicht leer	`MMD_ALTCHA_ERROR_SPAM_DETECTED`
`content_validation_failed`	Mindestens zwei Felder auffällig	`MMD_ALTCHA_ERROR_CONTENT_VALIDATION`
`altcha_missing`	Feld `altcha` leer	`MMD_ALTCHA_ERROR_VERIFICATION_FAILED`
`altcha_invalid`	Lösung nicht als Base64 oder JSON lesbar, ein Pflichtfeld fehlt, der Algorithmus ist nicht `SHA-256`, oder Signatur oder Hash stimmen nicht	`MMD_ALTCHA_ERROR_VERIFICATION_FAILED`
`altcha_expired`	Challenge zu alt	`MMD_ALTCHA_ERROR_GENERIC`
`altcha_replay`	Challenge schon verwendet	`MMD_ALTCHA_ERROR_GENERIC`
`rate_limit_exceeded`	Zu viele Anfragen, `retryAfterSeconds` ist gesetzt	`MMD_ALTCHA_ERROR_RATE_LIMITED`, dahinter `MMD_ALTCHA_RETRY_AFTER`

Die Übersetzungen der Schlüssel stehen in translations/de/mmd_altcha_lang.php und translations/en/mmd_altcha_lang.php. Die Schlüssel MMD_ALTCHA_ERROR_CHALLENGE_EXPIRED und MMD_ALTCHA_ERROR_CHALLENGE_REUSED sind dort zwar definiert, werden von den mitgelieferten Controllern aber nicht verwendet.

Das Widget lässt sich in jedes Twig-Template einbinden. Beispiel und Voraussetzungen stehen auf der Seite Storefront. Das Widget fügt das POST-Feld altcha dem umgebenden Formular selbst hinzu.

Erweiterte OXID-Klassen

Eine Übersicht der erweiterten Core-Klassen steht auf der Seite Technik. Wenn dein Shop dieselben Klassen ebenfalls erweitert, bestimmt die Modulreihenfolge im Admin, welche Erweiterung zuerst läuft.