Installation für Agenturen

Diese Anleitung richtet sich ausschließlich an Agenturen und technische Shop-Administratoren mit Datei-, Composer-, Konsolen- und Datenbankzugriff. Einstellungen und tägliche Abläufe für Shop-Betreiber 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/xrechnung`
OXID eShop 6 ab 6.1	Smarty	`source/modules/ecs/xRechnung`

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.
xRechnung benötigt die horstoeko-ZUGFeRD-Bibliotheken. Deren Einbindung unterscheidet sich zwischen OXID 7 (im Shopprojekt) und OXID 6 (außerhalb des Shopprojekts) – siehe die jeweiligen Abschnitte.
Ein vollständiges Datenbankbackup und ein Wiederherstellungsweg wurden geprüft.
Der Webserver-PHP-Prozess benötigt Schreibrechte auf das Compile-Verzeichnis.
Optional: Für die Einbettung der XML-Rechnung in PDF-Rechnungen muss das Modul Documents installiert und aktiv sein.

OXID 7 installieren

1. Moduldateien kopieren

Kopieren Sie das vollständige Twig-Paket nach:

vendor/ecs/xrechnung

Prüfen Sie danach insbesondere metadata.php, composer.json, services.yaml, assets, src 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\\xRechnung\\": "vendor/ecs/xrechnung/src/"

Vollständiges Beispiel mit einem vorhandenen Namespace:

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

Der Eintrag gehört in die Projekt-composer.json, nicht in die Datei des Moduls. Vorhandene Namespaces bleiben erhalten.

3. ZUGFeRD-Bibliotheken installieren

xRechnung benötigt die horstoeko-Pakete. Installieren Sie sie im Hauptverzeichnis des Shops:

composer require horstoeko/zugferd:^1.0 horstoeko/zugferdublbridge:^1.0 horstoeko/zugferdvisualizer:^1.0

Dadurch werden automatisch auch Unterabhängigkeiten wie dompdf/dompdf, mpdf/mpdf und psr/log mitinstalliert.

4. Autoloader und Modul installieren

Führen Sie im Shop-Hauptverzeichnis aus:

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

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

5. OXID-7-Installation kontrollieren

Prüfen Sie mindestens:

Das Modul ist im Admin sichtbar und aktiv; die Moduleinstellungen zeigen die Gruppe „Allgemein“.
In der Bestellübersicht einer Bestellung erscheint der Block „X-Rechnung“ mit den Feldern und den Schaltflächen Ansehen, Versenden und Herunterladen.
Der Shopcache wurde geleert.

OXID 6 installieren

1. Moduldateien kopieren

Kopieren Sie das vollständige Smarty-Paket nach:

source/modules/ecs/xRechnung

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

2. ZUGFeRD-Bibliotheken außerhalb des Shopprojekts installieren

Achtung

Unter OXID 6 ist die Einbindung der horstoeko-Pakete im Shopprojekt nicht möglich (Versionskonflikt mit der dortigen Symfony-Version). Sie werden deshalb in einem eigenen Ordner neben dem Shopprojekt installiert.

Wechseln Sie per SSH in das Verzeichnis, in dem auch der Shopprojekt- Ordner liegt, und erstellen Sie dort den Ordner zugferd:

www
├── zugferd
├── Shopprojekt-Ordner
│     ├── source
│     ├── vendor

mkdir zugferd
cd zugferd
composer require horstoeko/zugferd horstoeko/zugferdublbridge horstoeko/zugferdvisualizer

Das Modul lädt den ZUGFeRD-Autoloader aus diesem Schwesterordner. Er muss dauerhaft bestehen bleiben und darf nicht verschoben werden.

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

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

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

Vollständiges Beispiel:

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

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

4. 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/xRechnung
vendor/bin/oe-console oe:module:activate ecs_xrechnung

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

5. OXID-6-Installation kontrollieren

Prüfen Sie mindestens:

Modul und Moduleinstellungen sind im Admin sichtbar.
Der „X-Rechnung“-Block erscheint in der Bestellübersicht und eine Testausgabe (Ansehen/Herunterladen) funktioniert ohne Fehler.
Die OXID-Views wurden aktualisiert und die temporären Shopdateien geleert.

Datenbankänderung und Aktivierungsereignisse

Bei der Aktivierung legt das Modul zusätzliche Felder an:

ALTER TABLE `oxuser`  ADD `ECSBILLEMAIL`  varchar(255) NOT NULL;
ALTER TABLE `oxorder` ADD `ECSBILLEMAIL`  varchar(255) NOT NULL;
ALTER TABLE `oxuser`  ADD `ECSLEITWEGID`  varchar(255) NOT NULL;
ALTER TABLE `oxorder` ADD `ECSLEITWEGID`  varchar(255) NOT NULL;
ALTER TABLE `oxorder` ADD `ECSBILLPAYTO`  varchar(255) NOT NULL;
ALTER TABLE `oxorder` ADD `ECSBILLXNOTE`  varchar(255) NOT NULL;

Zusätzlich leert die Aktivierung das Compile-Verzeichnis und regeneriert die Datenbank-Views. Bei der Deaktivierung entfernt das Modul seine Template-Block-Einträge aus oxtplblocks und leert den Cache erneut:

DELETE FROM oxtplblocks WHERE OXMODULE = 'ecs_xrechnung';

Die Felder speichern pro Kunde beziehungsweise Bestellung die Rechnungseingangs-E-Mail, die Leitweg-ID, das Fälligkeitsdatum und eine freie Rechnungsnotiz.

Modul aktualisieren

OXID 7 aktualisieren

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

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

OXID 6 aktualisieren

Deaktivieren Sie das Modul und ersetzen Sie source/modules/ecs/xRechnung 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/xRechnung
vendor/bin/oe-console oe:module:activate ecs_xrechnung

Leeren Sie anschließend die temporären Shopdateien.

Nach jedem Update

Prüfen Sie die Moduleinstellungen; neue Paketvorgaben setzen vorhandene Betreiberwerte nicht automatisch zurück.
Erzeugen Sie eine Test-X-Rechnung (Ansehen und Herunterladen) und validieren Sie die XML-Datei.
Unter OXID 6: Prüfen Sie, dass der zugferd-Schwesterordner unverändert erreichbar ist.

Datenaufbewahrung bei Deaktivierung

Eine normale Deaktivierung entfernt den „X-Rechnung“-Block aus der Bestellübersicht. Die angelegten Datenbankfelder und ihre Inhalte (Leitweg-ID, Rechnungseingangs-E-Mail, Fälligkeit, Notiz) bleiben erhalten und werden bei einer erneuten Aktivierung weiterverwendet. Bereits vergebene Rechnungsnummern und gesendete E-Mails bleiben selbstverständlich bestehen. Es gibt keine automatische Bereinigung.