Installation für Agenturen

Diese Anleitung richtet sich ausschließlich an Agenturen und technische Shop-Administratoren mit Datei-, Composer- und Konsolenzugriff. Einstellungen und Verhalten aus Betreibersicht sind unter Bedienung für Shop-Betreiber beschrieben.

Paket passend zur OXID-Hauptversion wählen

Verwenden Sie ausschließlich das zur Shop-Hauptversion gehörende Paket:

Paketauswahl
Shop	Ausgabe	Ziel
OXID eShop 7 ab 7.1	Twig	`vendor/ecs/mathecaptcha`
OXID eShop 6 ab 6.1	Smarty	`source/modules/ecs/MatheCaptcha`

Warnung

Die OXID-6- und OXID-7-Pakete sind nicht austauschbar. Sichern Sie vor Installation und Update mindestens die Projekt-composer.json, die Shopdatenbank, die OXID-Konfiguration und den vorhandenen Modulordner.

Voraussetzungen

Prüfen Sie vor der Installation:

Das OXID-7-Paket verlangt PHP ab Version 8.0; maßgeblich bleiben die höheren Anforderungen der eingesetzten OXID-Version.
Ein vollständiges Datenbankbackup und ein Wiederherstellungsweg wurden geprüft.
Der Webserver-PHP-Prozess benötigt Schreibrechte auf das Compile-Verzeichnis und – bei aktiviertem Protokoll – auf das Shop-Logverzeichnis (source/log/).
Das Modul erweitert Storefront-Formulare über Template-Blöcke des Standard-Themes (OXID 7: Twig, OXID 6: Smarty). Stark angepasste oder eigene Themes benötigen eine individuelle Einbindung des Blocks mathcaptcha beziehungsweise der Captcha-Ausgabe.
Die Captcha-Prüfung nutzt die Besucher-Session. Sessions müssen im Frontend funktionieren; Seiten-Caches vor den geschützten Formularen sind zu prüfen.

OXID 7 installieren

1. Moduldateien kopieren

Kopieren Sie das vollständige Twig-Paket nach:

vendor/ecs/mathecaptcha

Prüfen Sie danach insbesondere metadata.php, composer.json, services.yaml, src, translations und views des ausgelieferten OXID-7-Pakets.

2. Namespace in der Projekt-composer.json registrieren

Ergänzen Sie in der composer.json des Shop-Hauptverzeichnisses unter autoload / psr-4:

"Ecs\\MatheCaptcha\\": "vendor/ecs/mathecaptcha/src/"

Vollständiges Beispiel mit einem vorhandenen Namespace:

{
    "autoload": {
        "psr-4": {
            "Vorhandener\\Namespace\\": "vendor/vorhandener/anbieter/modul/src/",
            "Ecs\\MatheCaptcha\\": "vendor/ecs/mathecaptcha/src/"
        }
    }
}

Der Eintrag gehört in die Projekt-composer.json, nicht in die Datei des Moduls. Vorhandene Namespaces bleiben erhalten. Ein zusätzlicher Eintrag unter require für das Modul selbst ist bei dieser manuellen Installation nicht notwendig.

3. Autoloader und Modul installieren

Führen Sie im Shop-Hauptverzeichnis aus:

composer dump-autoload
vendor/bin/oe-console oe:module:install vendor/ecs/mathecaptcha
vendor/bin/oe-console oe:module:activate ecs_mathecaptcha
vendor/bin/oe-console oe:cache:clear

Alternativ kann die Aktivierung nach oe:module:install im Admin unter Erweiterungen ‣ Module erfolgen.

4. OXID-7-Installation kontrollieren

Prüfen Sie mindestens:

Das Modul ist im Admin sichtbar und aktiv; die Moduleinstellungen zeigen die Gruppe „Grundeinstellungen“ mit den Captcha-Optionen.
Das Kontaktformular zeigt die Rechenaufgabe; eine falsche Antwort wird mit einer Fehlermeldung abgelehnt, eine richtige angenommen.
Bei aktiviertem Protokoll wird source/log/eascap.log geschrieben.
Der Shopcache wurde geleert.

OXID 6 installieren

1. Moduldateien kopieren

Kopieren Sie das vollständige Smarty-Paket nach:

source/modules/ecs/MatheCaptcha

Prüfen Sie mindestens metadata.php, composer.json, Component, Controller, Core, translations und views. Die Klassen des Smarty-Pakets liegen direkt im Modulordner, nicht in einem src-Unterverzeichnis.

2. Namespace in der Projekt-composer.json registrieren

Ergänzen Sie in der composer.json des Shop-Hauptverzeichnisses unter autoload / psr-4:

"Ecs\\MatheCaptcha\\": "./source/modules/ecs/MatheCaptcha/"

Vollständiges Beispiel:

{
    "autoload": {
        "psr-4": {
            "Vorhandener\\Namespace\\": "./source/modules/vorhandenes/modul/",
            "Ecs\\MatheCaptcha\\": "./source/modules/ecs/MatheCaptcha/"
        }
    }
}

Alle vorhandenen Namespaces bleiben erhalten. Ein zusätzlicher Eintrag unter require ist für die manuelle Installation nicht notwendig.

3. Autoloader und Modulkonfiguration installieren

Führen Sie im Shop-Hauptverzeichnis aus:

composer dump-autoload
vendor/bin/oe-console oe:module:install-configuration source/modules/ecs/MatheCaptcha
vendor/bin/oe-console oe:module:activate ecs_mathecaptcha

Leeren Sie anschließend die temporären Shopdateien beziehungsweise den OXID-Cache mit dem in der jeweiligen OXID-6-Umgebung vorgesehenen Verfahren.

4. OXID-6-Installation kontrollieren

Prüfen Sie mindestens:

Modul und Moduleinstellungen sind im Admin sichtbar.
Die geschützten Formulare zeigen die Rechenaufgabe ohne Smarty-Fehler.
Die OXID-Views wurden aktualisiert und die temporären Shopdateien geleert.

Bemerkung

Die OXID-6-Variante schützt zusätzlich das Empfehlungsformular (suggest); die OXID-7-Version erweitert dafür die Preisalarm- und Registrierungs-Controller direkt und bietet ein einstellbares IP-Rate-Limit. Die Klassennamen-Liste der OXID-7-Grundeinstellungen enthält suggest deshalb nicht mehr in der Vorgabe.

Datenbankänderung und Aktivierungsereignisse

Das Modul legt keine eigenen Datenbankfelder oder Tabellen an. Die Captcha-Prüfung erfolgt ausschließlich serverseitig; es werden keine Captcha-Daten in der Datenbank abgelegt. Das optionale Protokoll schreibt in die Datei source/log/eascap.log im Shop-Logverzeichnis und rotiert sie ab etwa 10 MB in eine umbenannte Sicherungsdatei. Bei der Aktivierung leert das Modul das Compile-Verzeichnis; bei der Deaktivierung entfernt es seine Template-Block-Einträge aus oxtplblocks und leert das Compile-Verzeichnis erneut:

DELETE FROM oxtplblocks WHERE OXMODULE = 'ecs_mathecaptcha';

Modul aktualisieren

OXID 7 aktualisieren

Deaktivieren Sie das Modul für den Dateiaustausch. Ersetzen Sie den vollständigen Ordner vendor/ecs/mathecaptcha durch das aktuelle OXID-7-/Twig-Paket. Führen Sie danach aus:

composer dump-autoload
vendor/bin/oe-console oe:module:install vendor/ecs/mathecaptcha
vendor/bin/oe-console oe:module:activate ecs_mathecaptcha
vendor/bin/oe-console oe:cache:clear

OXID 6 aktualisieren

Deaktivieren Sie das Modul und ersetzen Sie source/modules/ecs/MatheCaptcha vollständig durch das aktuelle OXID-6-/Smarty-Paket. Führen Sie danach aus:

composer dump-autoload
vendor/bin/oe-console oe:module:install-configuration source/modules/ecs/MatheCaptcha
vendor/bin/oe-console oe:module:activate ecs_mathecaptcha

Leeren Sie anschließend die temporären Shopdateien.

Nach jedem Update

Prüfen Sie die Moduleinstellungen, insbesondere die Klassennamen-Liste der geschützten Formulare.
Testen Sie mindestens ein geschütztes Formular mit falscher und mit richtiger Antwort.
Kontrollieren Sie bei aktiviertem Protokoll die Schreibrechte auf source/log/.

Datenaufbewahrung bei Deaktivierung

Eine normale Deaktivierung stellt die Standard-Formulare des Themes wieder her. Das Modul speichert keine Datensätze in der Datenbank; die Moduleinstellungen bleiben in der OXID-Konfiguration erhalten und werden bei einer erneuten Aktivierung wieder verwendet. Eine vorhandene Protokolldatei source/log/eascap.log wird bei der Deaktivierung nicht gelöscht – entfernen Sie sie bei Bedarf manuell.