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/documents

OXID eShop 6 ab 6.1

Smarty

source/modules/ecs/Documents

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. Auf dem Server abgelegte Rechnungs-PDFs und die Modulfelder in oxorder enthalten Kundendaten und müssen in das Datenschutz- und Sicherungskonzept einbezogen werden.

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.

  • Documents benötigt die PDF-Bibliothek dompdf. OXID 7: dompdf/dompdf:^3.1, OXID 6: dompdf/dompdf:^2.0. Ist dompdf bereits durch eine andere Erweiterung installiert, entfällt dieser Schritt.

  • Optional: Für den EPC-QR-Code auf Belegen wird zusätzlich das Paket endroid/qr-code benötigt (OXID 6: ^4.0). Ohne dieses Paket bleibt die QR-Code-Funktion wirkungslos.

  • Der Webserver-PHP-Prozess benötigt Schreibrechte auf das Compile- sowie auf das konfigurierte PDF-Ablageverzeichnis.

  • Ein vollständiges Datenbankbackup und ein Wiederherstellungsweg wurden geprüft.

Achtung

Rechnungs-PDFs können personenbezogene Daten enthalten. Klären Sie vor dem Live-Betrieb Speicherort, Zugriffsschutz (das Modul legt eine .htaccess im Ablageordner an), Aufbewahrung und Löschprozess. Die steuerliche Bewertung der Belege trifft das Modul nicht.

OXID 7 installieren

1. Moduldateien kopieren

Kopieren Sie das vollständige Twig-Paket nach:

vendor/ecs/documents

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

Vollständiges Beispiel mit einem vorhandenen Namespace:

{
    "autoload": {
        "psr-4": {
            "Vorhandener\\Namespace\\": "vendor/vorhandener/anbieter/modul/src/",
            "Ecs\\Documents\\": "vendor/ecs/documents/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. dompdf installieren

Installieren Sie im Shop-Hauptverzeichnis die PDF-Bibliothek, sofern sie nicht bereits vorhanden ist:

composer require dompdf/dompdf:^3.1

Optional für den EPC-QR-Code auf Belegen:

composer require endroid/qr-code

4. Autoloader und Modul installieren

Führen Sie im Shop-Hauptverzeichnis aus:

composer dump-autoload
vendor/bin/oe-console oe:module:install vendor/ecs/documents
vendor/bin/oe-console oe:module:activate ecs_easydocuments
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 sind vorhanden.

  • In der Bestellverwaltung erscheint der Tab PDF-Dokumente; die Übersicht einer Bestellung zeigt die Beleg-Box.

  • Die Felder ECSBILLPAYTO, ECSBILLSENT, ECSBILLEMAIL und ECSBILLTEXT sind in oxorder vorhanden und die OXID-Views wurden aktualisiert.

  • Eine Testbestellung erzeugt eine HTML-Vorschau und ein PDF ohne Twig- oder Dompdf-Fehler; eine Test-E-Mail wird zugestellt.

  • Der Shopcache wurde geleert.

OXID 6 installieren

1. Moduldateien kopieren

Kopieren Sie das vollständige Smarty-Paket nach:

source/modules/ecs/Documents

Beachten Sie die Groß- und Kleinschreibung von Documents. Prüfen Sie mindestens metadata.php, composer.json, Controller, Core, Model, templates, templates_child, translations und views.

2. Namespace in der Projekt-composer.json registrieren

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

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

Vollständiges Beispiel:

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

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

3. dompdf installieren

Installieren Sie im Shop-Hauptverzeichnis die PDF-Bibliothek:

composer require dompdf/dompdf:^2.0

Optional für den EPC-QR-Code (ab PHP 7.3):

composer require endroid/qr-code:^4.0

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/Documents
vendor/bin/oe-console oe:module:activate ecs_easydocuments

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.

  • Die vier oxorder-Felder wurden angelegt und die OXID-Views aktualisiert.

  • Tab PDF-Dokumente und Übersichts-Box sind vorhanden; eine Testbestellung erzeugt Vorschau, PDF und E-Mail ohne Smarty-Fehler.

  • Die temporären Shopdateien wurden geleert.

Datenbankänderung und Aktivierungsereignisse

Bei der Aktivierung legt das Modul folgende Felder an:

ALTER TABLE oxorder ADD ECSBILLPAYTO DATE NOT NULL DEFAULT '0000-00-00' AFTER OXISNETTOMODE;
ALTER TABLE oxorder ADD ECSBILLSENT DATETIME NOT NULL DEFAULT '0000-00-00 00:00:00' AFTER OXISNETTOMODE;
ALTER TABLE oxorder ADD ECSBILLEMAIL varchar(255) NOT NULL AFTER OXISNETTOMODE;
ALTER TABLE oxorder ADD ECSBILLTEXT TEXT NOT NULL AFTER OXISNETTOMODE;

Danach leert es das Compile-Verzeichnis und regeneriert die Datenbank-Views. Bereits vorhandene Felder bleiben erhalten; ein Fehler des ALTER TABLE-Befehls wird vom Modul nicht im Admin ausgegeben. Kontrollieren Sie die Struktur deshalb ausdrücklich:

SHOW COLUMNS FROM oxorder LIKE 'ECS%';

Bei der Deaktivierung entfernt das Modul seine Einträge aus oxtplblocks, leert erneut das Compile-Verzeichnis und regeneriert die Views. Die vier oxorder-Felder und ihre Inhalte bleiben erhalten.

Gespeicherte Bestelldaten

  • ECSBILLPAYTO: Zahlungsziel-Datum der Rechnung (aus Rechnungsdatum plus konfiguriertem Zahlungsziel).

  • ECSBILLSENT: Zeitpunkt des ersten Rechnungsversands per E-Mail.

  • ECSBILLEMAIL: abweichende Rechnungs-E-Mail-Adresse der Bestellung; sie wird für Rechnung und Proforma vorrangig verwendet.

  • ECSBILLTEXT: individueller Zusatztext der Bestellung; die Zeichenfolge ~~~ trennt Text über und unter der Positionstabelle.

  • Jede versandte Modul-E-Mail wird zusätzlich als Klartext-Bemerkung (oxremark, Typ r) beim Bestellkunden abgelegt.

Modul aktualisieren

OXID 7 aktualisieren

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

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

OXID 6 aktualisieren

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

Leeren Sie anschließend die temporären Shopdateien.

Nach jedem Update

  • Kontrollieren Sie die vier oxorder-Felder und die OXID-Views.

  • Prüfen Sie die Moduleinstellungen; neue Paketvorgaben setzen vorhandene Betreiberwerte nicht automatisch zurück.

  • Testen Sie PDF-Ansicht, Download, E-Mail-Versand und – falls eingerichtet – die Serverablage mit einer Testbestellung.

  • Individuelle Template-Anpassungen gehören in die Child-Template-Ordner; prüfen Sie, dass sie nach dem Update weiter greifen (siehe folgenden Abschnitt).

Beleg-Templates updatefest anpassen

Layout und Inhalte der PDF-Belege werden über Templatedateien im Modul gesteuert. Ändern Sie diese Dateien niemals direkt im Originalordner: Bei einem Modulupdate werden die Original-Templates überschrieben und die Anpassungen gehen verloren. Kopieren Sie stattdessen nur die tatsächlich anzupassende Datei in den Child-Ordner. Dateien im Child-Ordner werden bei der Belegerzeugung bevorzugt und bleiben beim Update erhalten.

Template-Ordner

Shop

Original-Templates

Child-Ordner für Anpassungen

OXID 7 (Twig)

vendor/ecs/documents/pdf_templates/

vendor/ecs/documents/pdf_childtemplates/

OXID 6 (Smarty)

source/modules/ecs/Documents/templates/

source/modules/ecs/Documents/templates_child/

Vorgehen

  1. Legen Sie im Child-Ordner bei Bedarf dieselbe Unterverzeichnisstruktur an wie im Originalordner; die gemeinsam genutzten Untervorlagen liegen jeweils im Unterordner inc/.

  2. Kopieren Sie die zu ändernde Datei unter identischem Dateinamen in den Child-Ordner, unter OXID 7 zum Beispiel pdf_templates/inc/easydocuments_header.html.twig nach pdf_childtemplates/inc/easydocuments_header.html.twig.

  3. Nehmen Sie alle Anpassungen ausschließlich in der Kopie im Child-Ordner vor.

  4. Leeren Sie anschließend den Compile-Ordner des Shops. OXID 7 cached die Beleg-Templates unter tmp/twig_pdf; ohne Leerung werden ältere Stände weiter verwendet.

Das Modul prüft jede Belegdatei zuerst im Child-Ordner und verwendet eine dort vorhandene Version bevorzugt – das gilt für die Dokument-Templates ebenso wie für die Untervorlagen in inc/. Kopieren Sie nur die Dateien, die Sie wirklich ändern; alles andere bleibt automatisch auf dem Originalstand.

Zuordnung der Templatedateien

Die Dateinamen folgen dem Schema easydocuments_<typ>.html.twig beziehungsweise unter OXID 6 easydocuments_<typ>.tpl:

Datei

Inhalt

easydocuments_invoice.*

Rechnung

easydocuments_offer.*

Angebot

easydocuments_confirmation.*

Auftragsbestätigung

easydocuments_reminder.*

Zahlungserinnerung

easydocuments_creditnote.*

Gutschrift

easydocuments_delnote.*

Lieferschein

easydocuments_proforma.*

Proformarechnung

easydocuments_letter.*

Brief

easydocuments_beispiel.*

Beispieldokument zur Layout-Prüfung

Untervorlagen im Unterordner inc/:

Datei

Inhalt

easydocuments_header.*

Briefkopf mit Logo und Absender

easydocuments_adress.*

Adressfeld des Empfängers

easydocuments_infobox.*

Infobox mit Beleg- und Bestelldaten

easydocuments_invoicetable.*

Positionstabelle der Warenbelege

easydocuments_delnote_table.*

Positionstabelle des Lieferscheins

easydocuments_bankinfo.*

Bankdaten- und Zahlungsziel-Block

easydocuments_paypalbtn.*

PayPal-Zahlbutton

easydocuments_footer.*

Fußzeile

easydocuments_styles.*

CSS-Grundgerüst der Belege

Datenaufbewahrung bei Deaktivierung

Eine normale Deaktivierung bewahrt die vier oxorder-Felder, sämtliche Beleg-Zeitstempel, Zusatztexte und die als Kundenbemerkung abgelegten Mail-Texte auf. Bereits auf dem Server gespeicherte PDF-Dateien bleiben ebenfalls erhalten. Bei erneuter Aktivierung stehen alle Daten weiter zur Verfügung. Es gibt keine automatische Bereinigung; eine endgültige Entfernung der Felder und Dateien erfolgt nur manuell nach Backup und fachlicher Freigabe.