Wie Sie nicht mehr mit PDF-Generierung in Laravel kämpfen

PDF-Dokumente im Web zu generieren war schon immer eine ziemliche Herausforderung. Denken Sie nur daran, wie oft Sie versucht haben, die perfekte Rechnung oder den perfekten Bericht zu layouten, nur um festzustellen, dass sich Schriftarten verschoben haben, Tabellen nicht mehr ausgerichtet waren oder Bilder vollständig verschwunden sind. Normalerweise bleibt die Wahl zwischen komplexen System-Tools wie wkhtmltopdf, die Serverkonfiguration erfordern, und kostenpflichtigen Cloud-Diensten.

Wenn Sie mit dem Laravel-Stack arbeiten, gibt es eine erprobte Lösung – das laravel-dompdf-Paket von Barry van den Heuvel. Es ist ein Wrapper um die Dompdf-Bibliothek, der Ihr vertrautes Blade-Template in eine PDF-Datei konvertiert. Keine zusätzlichen Server-Abhängigkeiten, nur PHP.

Was steckt unter der Haube

Das Projekt macht im Wesentlichen eine Sache: Es verbindet die Leistungsfähigkeit von Laravel mit der Dompdf-Engine. Das Hauptmerkmal ist, dass Sie keine neue Syntax für das Dokumenten-Layout erlernen müssen. Sie erstellen eine normale View, übergeben Daten daran, und das Paket übernimmt das Rendering.

Interessanterweise unterstützt das Paket nicht nur standardmäßiges Laravel, sondern auch Lumen. Das ist nützlich, wenn Sie die Dokumentgenerierung in einen separaten Microservice auslagern.

Wie es in der Praxis funktioniert

Die Installation erfolgt standardmäßig über Composer:

composer require barryvdh/laravel-dompdf

Anschließend haben Sie Zugriff auf die Pdf-Fassade. Das einfachste Beispiel für das Erstellen einer Datei sieht so aus:

use Barryvdh\DomPDF\Facade\Pdf;

$pdf = Pdf::loadView('emails.invoice', ['order' => $order]);
return $pdf->download('invoice.pdf');

Die loadView-Methode nimmt Ihre Blade-Datei, übergibt Variablen daran und generiert ein Objekt, das Sie sofort zum Herunterladen an den Benutzer senden oder einfach im Browser über stream() anzeigen können.

Flexible Seiteneinrichtung

Oft müssen Sie die Seitenausrichtung oder das Papierformat direkt im Code ändern. Zum Beispiel funktioniert die Querformat-Ausrichtung besser für breite Tabellen:

Pdf::loadHTML($html)
    ->setPaper('a4', 'landscape')
    ->setWarnings(false)
    ->save('report.pdf');

Übrigens, wenn Sie die Datei auf der Festplatte speichern möchten, anstatt sie an den Benutzer zu senden, erledigt die save()-Methode dies mit einer einzigen Aktion.

PDF/A-3b-Unterstützung und elektronische Rechnungen

Neuere Versionen (3.x) haben Unterstützung für den PDF/A-3b-Standard hinzugefügt. Dies ist entscheidend für die langfristige Dokumentenarchivierung. Aber es gibt einen Haken: Dieser Standard erfordert, dass alle Schriftarten in der Datei eingebettet sind. Standard-Helvetica oder Times funktionieren nicht – Sie müssen etwas wie DejaVu Sans verwenden.

Für diejenigen, die an Buchhaltungsautomatisierung arbeiten, unterstützt das Paket jetzt die Formate Zugferd und Factur-X. Dabei wird eine XML-Datei mit Rechnungsdaten direkt in das PDF eingebettet. Es sieht ungefähr so aus:

$pdf = Pdf::loadView('invoice', $data)->setPdfA();

// Добавляем метаданные для Factur-X
$pdf->setAdditionalXmpRdf($xmlMetadata);

// Прикрепляем сам XML
$pdf->addEmbeddedFile(
    storage_path('invoices/factur-x.xml'),
    'factur-x.xml',
    'Factur-X Invoice',
    'text/xml'
);

Einige Layout-Tipps

Dompdf ist keine vollständige Browser-Engine. Es verarbeitet CSS 2.1 gut und einige CSS-3-Eigenschaften, aber versuchen Sie nicht, dort Flexbox oder Grid zu verwenden. Gute alte Tabellen und Floats sind Ihre beste Wahl.

Zwei Dinge, die Ihnen viel Zeit sparen werden:

1. Geben Sie immer die Kodierung in Ihrem Template an: <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>. Ohne dies werden kyrillische Zeichen zu Fragezeichen.
2. Verwenden Sie für Seitenumbrüche die CSS-Eigenschaft page-break-after: always. Dies ist der zuverlässigste Weg, um den Drucker dort ein neues Blatt beginnen zu lassen, wo Sie es benötigen.

Lohnt es sich zu verwenden

laravel-dompdf ist ein Arbeitstier. Es eignet sich perfekt für die Generierung einfacher bis mittelkomplexer Dokumente: Rechnungen, Servicereports, einfache Auszüge.

Der Hauptvorteil ist die Einfachheit. Sie müssen kein Node.js, Puppeteer installieren oder Server-Binaries konfigurieren. Alles funktioniert out-of-the-box auf standardmäßigem PHP-Hosting.

Wenn Sie jedoch komplexe JavaScript-Diagramme rendern müssen oder Ihr Layout stark auf moderne CSS-Tricks setzt, könnte Dompdf an seine Grenzen stoßen. In solchen Fällen ist es besser, sich nach Chromium-basierten Tools umzusehen. Aber für 90% der Backend-Entwickleraufgaben ist dieses Paket mehr als ausreichend.

Das Projekt ist lebendig und wird aktiv gepflegt (über 7.000 Sterne auf GitHub) und wird von einem der bekanntesten Mitwirkenden in der Laravel-Community unterstützt. Wenn Sie es noch nicht ausprobiert haben – jetzt ist es an der Zeit, es zu bookmarken.