data/epcqr

data 97cfcefe22 Neues Modul epcqr verbessert

2026-01-27 18:16:40 +01:00

10 KiB

Raw Blame History

Bilder in ODT-Dokumenten mit EPCQR-Modul

Übersicht

Das EPCQR-Modul bietet eine wiederverwendbare Lösung zum Einfügen von Bildern in ODT-Dokumentvorlagen. Die Implementierung ist generisch und kann für beliebige Bilder verwendet werden, nicht nur für QR-Codes.

Funktionsweise

1. QR-Code Keyword: `{qrcode}`

Das neue Keyword {qrcode} kann in jedem ODT-Dokumenttemplate verwendet werden und wird automatisch durch ein QR-Code-Bild ersetzt.

Beispiel in ODT-Template:

Rechnung: {ref}
Betrag: {total_ttc}

Bitte überweisen Sie den Betrag mit folgendem QR-Code:
{qrcode}

2. Generische Bildintegration

Das System unterstützt auch beliebige andere Bilder:

Erstellen Sie ein Extrafeld mit dem Suffix _imagepath
Speichern Sie den Dateipfad zum Bild im Extrafeld
Verwenden Sie das Keyword {FELDNAME} im ODT-Template

Beispiel:

Extrafeld: logo_imagepath (Typ: varchar)
Speichern: /pfad/zum/logo.png im Extrafeld
Im Template: {logo}

Installation und Konfiguration

Schritt 1: Modul aktualisieren

Das Modul muss deaktiviert und neu aktiviert werden, damit die neuen Funktionen verfügbar sind:

Home → Setup → Modules/Applications
EPCQR-Modul deaktivieren
EPCQR-Modul aktivieren

Schritt 2: Extrafeld erstellen (automatisch)

Das SQL-Update-Script erstellt automatisch das Extrafeld qrcodepath:

-- Wird automatisch bei Modulaktivierung ausgeführt
INSERT INTO llx_extrafields (name, label, type, elementtype, ...)
VALUES ('qrcodepath', 'QR-Code Bildpfad (lokal)', 'varchar', 'facture', ...);

Schritt 3: Konfiguration anpassen (optional)

Bankverbindung in admin/setup.php konfigurieren:

EPCQR_ACCOUNT_HOLDER: Kontoinhaber Name
EPCQR_IBAN: IBAN
EPCQR_BIC: BIC

Aktuell noch hardcoded im Trigger, wird in Version 1.6 konfigurierbar.

Verwendung in ODT-Templates

QR-Code in Rechnung einfügen

ODT-Template bearbeiten (z.B. invoice_template.odt)
Keyword einfügen: {qrcode} an gewünschter Stelle
Template speichern in Dolibarr
Rechnung validieren → QR-Code wird automatisch generiert
Dokument generieren (ODT) → QR-Code wird eingefügt

Eigene Bilder einfügen

Beispiel: Firmenlogo

Extrafeld erstellen:
- Name: company_logo_imagepath
- Typ: varchar(255)
- Element: facture

Bild speichern:

$invoice->array_options['options_company_logo_imagepath'] = '/pfad/zum/logo.png';
$invoice->insertExtraFields();

Template verwenden:
```
{company_logo}
```

Technische Details

Architektur

┌─────────────────────────────────────┐
│  1. BILL_VALIDATE Trigger           │
│     - Rechnung validiert             │
│     - QR-Code generieren             │
│     - Pfad in Extrafeld speichern    │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│  2. ODT-Generierung                  │
│     - Template laden                 │
│     - Felder ersetzen                │
│     - ODT-Datei erstellen            │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│  3. afterODTCreation Hook            │
│     - ODT entpacken (ZIP)            │
│     - Bild in Pictures/ kopieren     │
│     - manifest.xml aktualisieren     │
│     - {qrcode} durch <draw:frame>    │
│       XML ersetzen                   │
│     - ODT neu packen                 │
└─────────────────────────────────────┘

Wichtige Dateien

Datei	Funktion
lib/qrcode.class.php	QR-Code-Generator mit Caching
lib/epcqr.lib.php	Hilfsfunktionen für QR-Codes und Bilder
core/substitutions/functions_epcqr.lib.php	Substitutionsfunktionen für ODT
class/actions_epcqr.class.php	Hook-Klasse für ODT-Verarbeitung
core/triggers/interface_99_modEpcqr_EpcqrTriggers.class.php	Trigger für BILL_VALIDATE

Extrafelder

Feldname	Typ	Beschreibung
`qrcode`	HTML	QR-Code als `<img>`-Tag (Kompatibilität)
`qrcodepfad`	varchar	URL zum QR-Code über viewimage.php
`qrcodepath`	varchar	NEU: Lokaler Dateipfad für ODT-Integration

Bildverarbeitung

ODT ist ein ZIP-Archiv:

invoice.odt
├── mimetype (unkomprimiert!)
├── META-INF/
│   └── manifest.xml (Bild-Referenzen)
├── content.xml (Dokument-Inhalt)
├── styles.xml
└── Pictures/
    ├── qrcode.png
    └── logo.png

Ablauf:

ODT entpacken: ZipArchive::extractTo()
Bild kopieren: copy($source, $tmpDir.'/Pictures/img.png')

Manifest aktualisieren:

<manifest:file-entry
    manifest:media-type="image/png"
    manifest:full-path="Pictures/img.png"/>

Content.xml anpassen:

<draw:frame draw:name="QRCode"
            text:anchor-type="as-char"
            svg:width="2cm"
            svg:height="2cm">
  <draw:image xlink:href="Pictures/img.png"
              xlink:type="simple"
              xlink:show="embed"/>
</draw:frame>

ODT neu packen: ZipArchive::addFile() mit mimetype unkomprimiert

QR-Code-Generierung

Aktueller Stand (Version 1.5)

QR-Codes werden lokal generiert und gecached:

$qrGen = new QRCodeGenerator($db);
$qrCodePath = $qrGen->generateEPCQRCode(
    'Eduard Wisch',           // Kontoinhaber
    'DE70217625500013438147', // IBAN
    'GENODEF1HUM',           // BIC
    150.00,                  // Betrag
    'IN26-0001'              // Verwendungszweck
);
// Ergebnis: /srv/http/dolibarr/documents/epcqr/qrcodes/epc_abc123.png

Caching:

QR-Codes werden im Verzeichnis documents/epcqr/qrcodes/ gespeichert
Dateiname basiert auf MD5-Hash der Parameter
Wiederverwendung bei identischen Parametern

Migration von externem Service

Alt (bis Version 1.4):

$qrurl = "https://qr.data-it-solution.de/epc?...";
$invoice->array_options['options_qrcode'] = "<img src='".$qrurl."'>";

Neu (ab Version 1.5):

$qrCodePath = $qrGen->generateEPCQRCode(...);
$invoice->array_options['options_qrcodepath'] = $qrCodePath;
$invoice->array_options['options_qrcode'] = "<img src='".DOL_URL_ROOT."/viewimage.php?...'>";

Kompatibilität:

Bestehende Extrafelder bleiben erhalten
Alte Rechnungen mit extern gehosteten QR-Codes funktionieren weiter
Neue Rechnungen verwenden lokale QR-Codes

Erweiterte Verwendung

Eigene QR-Codes generieren

require_once DOL_DOCUMENT_ROOT.'/custom/epcqr/lib/qrcode.class.php';

$qrGen = new QRCodeGenerator($db);

// Generischer QR-Code
$qrPath = $qrGen->generateQRCode('https://example.com', 'url');

// EPC-QR-Code
$qrPath = $qrGen->generateEPCQRCode(
    'Firma GmbH',
    'DE89370400440532013000',
    'COBADEFFXXX',
    99.99,
    'Rechnung 2026-001'
);

Cache-Verwaltung

// Alte QR-Codes löschen (älter als 30 Tage)
$qrGen = new QRCodeGenerator($db);
$deleted = $qrGen->cleanCache(30);
echo "Gelöscht: ".$deleted." QR-Codes";

Bildgröße anpassen

Die Bildgröße wird automatisch berechnet und an die ODT-Vorgaben angepasst:

// In functions_epcqr.lib.php, Zeile ~180
$widthCm = round(($imageWidth / 96) * 2.54, 2);  // Pixel → cm (96 DPI)
$heightCm = round(($imageHeight / 96) * 2.54, 2);

// Maximale Größe begrenzen
$maxWidth = 6;  // cm
$maxHeight = 6; // cm

Anpassen: Bearbeiten Sie epcqr_insertImagesIntoODT() in core/substitutions/functions_epcqr.lib.php

Fehlerbehebung

Problem: QR-Code wird nicht angezeigt

Ursache 1: Extrafeld fehlt

# Prüfen ob Extrafeld existiert
mysql> SELECT name, label FROM llx_extrafields WHERE name = 'qrcodepath';

Lösung:

# SQL-Update manuell ausführen
mysql dolibarr < sql/update_1.5.0.sql

Ursache 2: Verzeichnis nicht beschreibbar

# Prüfen
ls -la /srv/http/dolibarr/documents/epcqr/

# Berechtigungen setzen
chmod 755 /srv/http/dolibarr/documents/epcqr/
chmod 755 /srv/http/dolibarr/documents/epcqr/qrcodes/

Ursache 3: Hook nicht aktiviert

# Prüfen
grep -r "hooks.*array" core/modules/modEpcqr.class.php

# Sollte enthalten:
'hooks' => array(
    'data' => array('pdfgeneration', 'odtgeneration', ...),

Problem: Bild wird im ODT nicht korrekt eingebettet

Diagnose:

ODT als ZIP öffnen
Prüfen ob Pictures/qrcode.png existiert
Prüfen ob META-INF/manifest.xml Eintrag enthält