Warum Ihre PDF-Rechnungen in Dolibarr nicht korrekt angezeigt werden: Diagnose und Lösungen

Inhaltsverzeichnis

1. Einführung

2. So funktioniert die PDF-Rechnung in Dolibarr

3. Wichtige PDF-Generierungs-Engines: TCPDF vs. DOMPDF

4. Häufige Symptome von PDF-Anzeigefehlern

5. Ursachen für Probleme mit der PDF-Rechnung

6. Schritt-für-Schritt-Diagnoseablauf

7. Lösung Nr. 1: Reparieren von PDF-Vorlagenfehlern

8. Fix Nr. 2: Verwalten der Schriftartkompatibilität

9. Fix Nr. 3: Anpassen der PHP-Konfiguration für die PDF-Generierung

10. Lösung Nr. 4: Lösen von Problemen mit Dateiberechtigungen und -zugriff

11. Lösung Nr. 5: Verwenden der richtigen Ausgabemethode (Browser, Download, Speicher)

12. Benutzerdefinierte Vorlagen: Best Practices zur Vermeidung von Fehlern

13. Tipps für mehrsprachige und RTL-PDF-Ausgabe (Arabisch, Hebräisch)

14. Fazit

1. Einleitung

Dolibarr ERP & CRM ist eine weit verbreitete Open-Source-Geschäftsplattform, die Abläufe von der Rechnungsstellung und Zahlung bis hin zur Lagerverwaltung, CRM, Buchhaltung und Projektverfolgung optimiert. Eines der wichtigsten Merkmale – insbesondere für kommerzielle Abläufe – ist die Möglichkeit, PDF-Rechnungen und andere Dokumente automatisch.

Viele Benutzer stoßen jedoch auf ein frustrierendes Problem: Ihre Rechnungen werden nicht richtig angezeigt, überhaupt nicht generiert oder führen zu beschädigten oder unlesbaren PDFs. Unabhängig davon, ob Sie selbst gehostet sind oder eine Cloud-basierte Dolibarr-Instanz verwenden, können diese Probleme die Abrechnungsabläufe stören und dem professionellen Image Ihres Unternehmens schaden.

Dieser Leitfaden gliedert sich warum PDF-Rechnungen in Dolibarr nicht korrekt dargestellt werden, wie die zugrunde liegende PDF-Generierung funktioniert und wie Sie diese Probleme schnell und dauerhaft diagnostizieren und beheben können.

2. So funktioniert die PDF-Rechnung in Dolibarr

Wenn Sie in Dolibarr auf „PDF generieren“ klicken (für eine Rechnung, einen Vorschlag, eine Bestellung usw.), führt das System Folgendes aus:

1. Verwendet a PHP-basierte Vorlage (bekannt als „PDF-Modell“)

2. Füllt dynamische Variablen aus (Kundenname, Artikeldetails, Gesamtbetrag usw.)

3. Sendet diesen Inhalt an einen PDF-Engine (TCPDF oder DOMPDF)

4. Gibt das Ergebnis entweder aus für:

   • Sofortiger Download

   • Browseranzeige

   • Dateiablage in /documents/

Die PDF-Generierung erfolgt vollständig serverseitig, was bedeutet, dass die Umgebung (PHP-Version, Speichereinstellungen, Schriftartenunterstützung) eine entscheidende Rolle für Erfolg oder Misserfolg spielt.

3. Wichtige PDF-Generierungs-Engines: TCPDF vs. DOMPDF

Dolibarr unterstützt zwei primäre PDF-Rendering-Engines:

TCPDF (Standard-Engine in älteren Versionen)

• Weit verbreitet in älteren Dolibarr-Versionen

• Schnell und leicht

• Unterstützt UTF-8 und grundlegendes Bild-Rendering

• Schlechte Unterstützung für CSS oder erweiterte Layouts

DOMPDF (in späteren Versionen eingeführt)

• Moderner und flexibler

• Unterstützt HTML5/CSS3-Layout

• Benötigt mehr Speicher und mehr Systemressourcen

• Besser für benutzerdefinierte Designs und komplexe Dokumente

Wenn Ihre Rechnungen leer, beschädigt oder falsch ausgerichtet sind, kann das Problem damit zusammenhängen, Engine-Einschränkungen, Fehlkonfigurationen oder Ressourcenbeschränkungen.

4. Häufige Symptome von PDF-Anzeigefehlern

Benutzer berichten typischerweise von folgenden Problemen beim Erstellen von Rechnungen:

• Leeres PDF ohne Inhalt

• Unvollständige Darstellung (fehlende Tabellen, Preise, Kundeninformationen)

• Falsch ausgerichteter Text oder Layoutverschiebungen

• PDF wird heruntergeladen, lässt sich aber nicht öffnen

• Fehlermeldungen wie:

  • TCPDF ERROR: Some data has already been output

  • DOMPDF Fatal error: Uncaught exception

• PDF sieht korrekt aus, zeigt aber die falsche Sprache oder fehlerhafte Zeichen an

Diese Symptome deuten darauf hin verschiedene Ursachen, von Problemen bei der Servereinrichtung bis hin zu fehlerhaftem Vorlagencode oder fehlenden Schriftarten.

5. Ursachen für Probleme mit der PDF-Rechnung

Dies sind die häufigsten Ursachen für Fehler beim Erstellen von PDF-Rechnungen in Dolibarr:

Für jedes dieser Probleme ist zur Lösung ein anderer Ansatz erforderlich.

6. Schrittweiser Diagnoseablauf

Führen Sie vor dem Anwenden von Fixes diese strukturierte Diagnoseroutine durch:

Schritt 1: Entwicklermodus aktivieren

In conf.php, aktivieren Sie den Entwicklermodus:

Hier wird die Debug-Ausgabe zur PDF-Generierung angezeigt.

Schritt 2: Reproduzieren Sie das Problem

• Probieren Sie verschiedene Rechnungsmodelle aus (z. B. crabe, azur, rouget)

• PDFs für kleine und große Rechnungen generieren

• Versuchen Sie sowohl Download- als auch Vorschauaktionen

Schritt 3: Protokolle prüfen

• PHP-Protokolle (/var/log/php/error.log)

• Apache/Nginx-Protokolle (/var/log/apache2/error.log)

• Dolibarrs interne Protokolldatei (falls konfiguriert)

Schritt 4: Überprüfen Sie den Quellcode der Vorlage

• Gehe zu /dolibarr/core/modules/facture/doc/

• Überprüfen Sie den PHP-Code auf Syntaxprobleme, nicht geschlossene Tags oder veraltete Funktionen

7. Lösung Nr. 1: PDF-Vorlagenfehler reparieren

PDF-Modelle (z. B. pdf_crabe.modules.php) sind in PHP geschrieben. Ein einziges falsch platziertes Zeichen kann die Ausgabe beschädigen.

Checkliste:

• Gewährleisten <?php Auf Tags folgen keine Leerzeichen

• Keine HTML- oder Textausgabe bevor Header sind gesetzt

• Kein Zufall echo or print Aufrufe in Logikabschnitten

• Variablen wie $this->emetteur muss richtig initialisiert werden

Tipp: Testen Sie zuerst mit Standardvorlagen

Wechseln Sie zu Dolibarrs Standard crabe Modell. Wenn dies funktioniert, liegt das Problem an Ihrer benutzerdefinierten Vorlage.

8. Fix Nr. 2: Verwalten der Schriftartkompatibilität

PDF-Engines benötigen die entsprechende Schriftart, um Zeichen korrekt anzuzeigen.

Symptome von Schriftartproblemen:

• Arabischer, chinesischer oder kyrillischer Text wird nicht wiedergegeben

• Leere Felder, in denen Namen oder Adressen stehen sollen

• PDF zeigt „????“ anstelle von Buchstaben an

Solutions:

• Wechseln Sie zu UTF-8-fähige Schriftarten wie DejaVu Sans oder FreeSerif

• Für DOMPDF laden Sie Schriftarten manuell mit load_font.php Nutzen

• Vermeiden Sie nicht in die PDF-Ausgabe eingebettete Systemschriftarten

In Dolibarr können Sie die Schrifteinstellungen pro Vorlage anpassen.

9. Fix Nr. 3: Anpassen der PHP-Konfiguration für die PDF-Generierung

Insbesondere DOMPDF erfordert entsprechende Serverressourcen.

Aktualisierung php.ini:

Starten Sie Apache/Nginx oder PHP-FPM nach Änderungen neu.

Erweiterungen überprüfen

Stellen Sie sicher, dass die folgenden PHP-Erweiterungen aktiv sind:

• mbstring

• gd

• dom

• fileinfo

• intl (für Sprach-/Gebietsschemaunterstützung)

Anwendung:

10. Fix Nr. 4: Lösen von Dateiberechtigungs- und Zugriffsproblemen

Wenn Dolibarr nicht kann schreibe an die /documents/ Flyer, die PDF-Generierung schlägt stillschweigend fehl.

Befehle zum Korrigieren von Berechtigungen:

Ersetzen www-data mit Ihrem Webserver-Benutzer.

Stellen Sie sicher, dass Unterverzeichnisse für Rechnungen (/documents/facture/) vorhanden sind.

11. Lösung Nr. 5: Verwenden der richtigen Ausgabemethode (Browser, Download, Speicher)

Dolibarr ermöglicht beim Erstellen von PDF-Rechnungen unterschiedliche Ausgabeverhalten:

• Anzeige im Browser (im Einklang)

• Aufforderung zum Download

• Direkt speichern in /documents/ Verzeichnis

Wenn Rechnungen in einer Methode nicht korrekt dargestellt werden, in einer anderen jedoch funktionieren, kann das Problem folgende Ursachen haben: HTTP-Header oder Browserkompatibilität.

Empfehlungen:

• Testen Sie alle Ausgabemethoden der Rechnungsseite

• Vermeiden Sie das Senden von HTML-Ausgaben (wie Debug-Informationen) vor Headern

• Auf Konflikte prüfen Content-Type or Content-Disposition Überschriften

• Deaktivieren Sie Browsererweiterungen, die die PDF-Wiedergabe blockieren könnten

In einigen Fällen löst das Umschalten von der Inline-Anzeige zum Download das Problem des „leeren Bildschirms“.

12. Benutzerdefinierte Vorlagen: Best Practices zur Vermeidung von Fehlern

Das Erstellen eines benutzerdefinierten PDF-Modells für Rechnungen ist in Dolibarr üblich, birgt jedoch potenzielle Kompatibilitätsrisiken mit:

• PHP-Versions-Upgrades

• Änderungen an der PDF-Engine

• Dolibarr-Kernaktualisierungen

So vermeiden Sie zukünftige Probleme:

12.1 Verwenden Sie das offizielle Vorlagengerüst

Verwenden Sie eine vorhandene Vorlage (wie crabe) als Ausgangspunkt. Halten Sie sich an die interne Struktur von Dolibarr:

• Definierung $object richtig (normalerweise ein Facture Klasseninstanz)

• Verwenden Sie interne Hilfsmethoden zur Tabellengenerierung

• Vermeiden Sie fest codierte Layoutpositionen – verwenden Sie die relative Positionierung

12.2 Gesamte Ausgabe bereinigen

Escape-Zeichenfolgen, die Sonderzeichen enthalten oder die Kodierung unterbrechen können:

12.3 Validieren mit Entwicklertools

Wenn Sie eine benutzerdefinierte Logik verwenden (z. B. Summen, Rabatte), validieren Sie die Ergebnisse anhand der integrierten PDF- und Bildschirmanzeige von Dolibarr.

12.4 Vorlagen versionieren

Speichern Sie benutzerdefinierte Vorlagen in Git. Dies ermöglicht Ihnen:

• Rollback defekter Versionen

• Kompatibilitätsänderungen im Laufe der Zeit verfolgen

• Einfaches Zusammenführen von Änderungen über Dolibarr-Upgrades hinweg

13. Tipps für mehrsprachige und RTL-PDF-Ausgabe (Arabisch, Hebräisch)

Das Erstellen mehrsprachiger oder von rechts nach links verlaufender PDF-Dateien erfordert besondere Sorgfalt.

13.1 Einstellen der richtigen Locale

Stellen Sie sicher, dass Dolibarr vor der PDF-Generierung auf die Sprache des Benutzers/Clients eingestellt ist:

In einigen Fällen müssen Sie möglicherweise den Zeichensatz erzwingen:

13.2 RTL-kompatible Schriftarten verwenden

Schriftarten wie Amiri, Noto Naskh Arabisch oder DejaVu Sans unterstützt RTL-Skripte.

13.3 RTL in DOMPDF aktivieren

DOMPDF unterstützt RTL nur, wenn es explizit konfiguriert ist:

Die Unterstützung kann jedoch variieren. TCPDF ist im Allgemeinen für RTL-Skripte zuverlässiger, im Design jedoch weniger flexibel.

13.4 Vermeiden Sie das Mischen von LTR/RTL ohne Ausrichtungseinstellungen

Legen Sie in Tabellen die Ausrichtungseigenschaften immer explizit fest. Beispiel:

14. Letzte Gedanken

Das Erstellen professioneller PDF-Rechnungen in Dolibarr sollte ein nahtloses Erlebnis sein – es kann jedoch leicht zu Frustration führen, wenn Vorlagen beschädigt werden, Konflikte bei den Servereinstellungen auftreten oder Inhalte nicht gerendert werden können.

Hier ist eine abschließende Checkliste, um eine robuste PDF-Ausgabe sicherzustellen:

✅ Verwendung offizielle Vorlagen als Grundlage für kundenspezifische Arbeiten
✅ Halten Sie Ihre PHP- und Dolibarr-Versionen auf dem gleichen Stand mit Modulkompatibilität
✅ Stellen Sie sicher Schriftabdeckung für jede Sprache, die Sie verwenden
✅ Richtig einstellen Berechtigungen auf die /documents/ Verzeichnis
✅ Validieren Vorlagensyntax, vermeiden Sie vorzeitige Ausgabe
✅ Regelmäßig Testen Sie benutzerdefinierte Vorlagen nach Dolibarr-Upgrades
✅ Wenn mehrsprachig oder RTL: Überprüfen Sie das Schriftart- und Layoutverhalten anhand realer Daten
✅ Verwendung Protokolle und Entwicklermodus um stille Fehler aufzuspüren

Ein kleines Konfigurationsversehen oder eine veraltete Vorlage können Ihren gesamten Rechnungsworkflow stören. Mit dem in diesem Handbuch beschriebenen Diagnose-Framework und den Fehlerbehebungen haben Sie alles, was Sie zur Behebung und Vermeidung von PDF-Problemen in Dolibarr benötigen.

Durch die Umsetzung dieser Best Practices stellen Sie sicher, dass Ihre Rechnungs-PDFs klar, zuverlässig, professionell und voll funktionsfähig– unabhängig davon, welche Version von Dolibarr oder PHP Sie verwenden.