PDF-Rechnungen mit Tailwind CSS: Dompdf und wkhtmltopdf im Vergleich

1. Warum PHP-Anwendungen oft ohne Node.js auskommen müssen

Viele PHP-Anwendungen, insbesondere Symfony-Projekte oder Magento-Shops, laufen in Server-Umgebungen, in denen bewusst keine Node.js-Laufzeit installiert werden soll, sei es aus Sicherheitsrichtlinien, aus Gründen der Deployment-Komplexität oder weil das Betriebsteam eine reine PHP-Umgebung bevorzugt. In solchen Fällen scheidet eine Puppeteer-basierte PDF-Generierung mit echtem Headless Chrome aus, weil sie zwingend eine Node.js-Laufzeit und einen vollständigen Chromium-Browser voraussetzt. Für PDF-Rechnungen in reinen PHP-Umgebungen bleiben deshalb PHP-native Bibliotheken wie Dompdf oder externe Binärwerkzeuge wie wkhtmltopdf die praktikablen Optionen.

Beide Ansätze verfolgen dieselbe Grundidee wie Puppeteer: eine mit Tailwind CSS gestylte HTML-Vorlage wird als Eingabe verwendet und in ein PDF-Dokument umgewandelt. Der entscheidende Unterschied liegt im Funktionsumfang der jeweiligen CSS-Engine. Weder Dompdf noch wkhtmltopdf unterstützen den vollen modernen CSS-Funktionsumfang, den Chrome bietet, weshalb eine Tailwind-Rechnungsvorlage bewusst auf die von beiden Bibliotheken unterstützten CSS-Eigenschaften beschränkt werden muss.

2. Dompdf: reines PHP ohne externe Abhängigkeit

Dompdf ist eine vollständig in PHP geschriebene Bibliothek, die HTML und CSS direkt im PHP-Prozess parst und in ein PDF-Dokument rendert, ganz ohne externe Programme oder Systemabhängigkeiten. Das macht Dompdf besonders attraktiv für Shared-Hosting-Umgebungen oder restriktive Server-Konfigurationen, in denen keine zusätzlichen Binärdateien installiert werden dürfen. Der Composer-Befehl composer require dompdf/dompdf reicht für die Installation, ohne dass Systemadministrator-Rechte oder ein separater Prozess-Aufruf nötig sind.

Der Nachteil dieser reinen PHP-Implementierung: Dompdfs CSS-Engine unterstützt weder Flexbox noch CSS Grid, und auch moderne CSS-Selektoren wie :has() oder :nth-child() in komplexeren Kombinationen werden nur teilweise korrekt interpretiert. Eine Tailwind-Rechnungsvorlage, die mit flex oder grid arbeitet, muss für Dompdf komplett auf tabellenbasiertes Layout umgestellt werden, ähnlich wie bei der E-Mail-Client-Kompatibilität für Outlook.

# Install Dompdf via Composer, no external binary required
composer require dompdf/dompdf

3. wkhtmltopdf: alte WebKit-Basis mit besserer CSS-Unterstützung

wkhtmltopdf ist kein reines PHP-Paket, sondern ein eigenständiges Kommandozeilenwerkzeug, das auf einer eingebetteten, älteren WebKit-Rendering-Engine basiert. PHP-Anwendungen rufen dieses Binary über einen Prozessaufruf auf, meist über einen Wrapper wie knplabs/knp-snappy, der die Kommandozeilenoptionen komfortabel als PHP-API bereitstellt. Weil WebKit eine echte Browser-Engine ist, unterstützt wkhtmltopdf deutlich mehr modernes CSS als Dompdf, inklusive teilweiser Flexbox-Unterstützung in neueren Versionen.

Der Nachteil: Die in wkhtmltopdf eingebettete WebKit-Version ist seit Jahren nicht mehr aktualisiert worden, das offizielle Projekt gilt inzwischen als eingestellt. CSS-Features, die nach dem letzten WebKit-Stand hinzukamen, etwa CSS Grid oder Container Queries, funktionieren deshalb nicht zuverlässig. Zudem erfordert wkhtmltopdf die Installation eines Systembinaries, was in stark eingeschränkten Hosting-Umgebungen ohne Root-Zugriff zum Problem werden kann.

4. Tailwind-Rechnungslayout ohne Flexbox und Grid

Damit dieselbe Tailwind-Rechnungsvorlage sowohl mit Dompdf als auch mit wkhtmltopdf funktioniert, empfiehlt sich von vornherein ein tabellenbasiertes Layout für alle strukturellen Elemente: Kopfzeile mit Firmenlogo und Rechnungsadresse, Positionstabelle mit Menge, Beschreibung, Einzelpreis und Gesamtpreis, sowie eine Fußzeile mit Steuersätzen und Zahlungsbedingungen. Tailwind-Klassen für Zellenpolsterung, Textausrichtung und Rahmenfarben lassen sich auf <table>-, <tr>- und <td>-Elemente anwenden, ohne auf moderne Layout-Mechanismen angewiesen zu sein.

Für die Gesamtsumme am Ende der Rechnung, die üblicherweise rechtsbündig unterhalb der Positionstabelle steht, funktioniert eine einfache Tabellenzeile mit text-right zuverlässig in beiden Bibliotheken, während ein mit Flexbox realisiertes justify-end-Layout in Dompdf komplett ignoriert würde. Die Faustregel für maximale Kompatibilität: Jede strukturelle Anordnung wird über Tabellen gelöst, während Tailwind-Klassen ausschließlich für Farben, Abstände, Schriftgrößen und Rahmen zum Einsatz kommen.

<!-- invoice.html — table-based layout compatible with both Dompdf and wkhtmltopdf -->
<table class="w-full border-collapse" cellpadding="0" cellspacing="0">
  <thead>
    <tr class="bg-slate-900 text-white">
      <th class="p-3 text-left">Beschreibung</th>
      <th class="p-3 text-right">Menge</th>
      <th class="p-3 text-right">Einzelpreis</th>
      <th class="p-3 text-right">Gesamt</th>
    </tr>
  </thead>
  <tbody>
    <tr class="border-b border-slate-200">
      <td class="p-3">Webentwicklung, Sprint 12</td>
      <td class="p-3 text-right">40</td>
      <td class="p-3 text-right">95,00 EUR</td>
      <td class="p-3 text-right font-semibold">3.800,00 EUR</td>
    </tr>
  </tbody>
</table>

5. Praxisbeispiel: Rechnung mit Dompdf rendern

Der Aufruf von Dompdf aus PHP heraus ist unkompliziert: eine Instanz wird erzeugt, HTML wird über loadHtml() übergeben, das Papierformat über setPaper() festgelegt, und render() erzeugt das Dokument im Speicher. Bevor die Rechnungsvorlage in Dompdf geladen wird, muss das kompilierte Tailwind-CSS entweder inline im <head> stehen oder als String eingebettet werden, da Dompdf keine externen Stylesheet-Referenzen über HTTP zuverlässig aus dem Dateisystem auflöst.

Ein wichtiges Detail: Dompdf benötigt für Umlaute und Sonderzeichen in deutschen Rechnungen eine explizite UTF-8-Konfiguration sowie eine Schriftart, die diese Zeichen abdeckt. Die Standard-Schriftarten von Dompdf unterstützen europäische Sonderzeichen zuverlässig, bei benutzerdefinierten Web-Fonts aus dem Tailwind-Theme muss die Schriftdatei zusätzlich über Dompdf\Options::setFontDir() eingebunden werden, da Dompdf Web-Fonts nicht automatisch aus dem CSS nachlädt wie ein Browser.

<?php

declare(strict_types=1);

use Dompdf\Dompdf;
use Dompdf\Options;

// Configure Dompdf for UTF-8 invoices with Tailwind-compiled CSS
$options = new Options();
$options->set('isRemoteEnabled', false);
$options->set('defaultFont', 'DejaVu Sans');

$dompdf = new Dompdf($options);
$html = file_get_contents(__DIR__ . '/dist/invoice.html');
$dompdf->loadHtml($html, 'UTF-8');
$dompdf->setPaper('A4', 'portrait');
$dompdf->render();

file_put_contents(__DIR__ . '/output/invoice-2026-0142.pdf', $dompdf->output());

6. Praxisbeispiel: dieselbe Vorlage mit wkhtmltopdf

Für wkhtmltopdf übernimmt der Wrapper knp-snappy die Kommunikation mit dem Kommandozeilenprogramm und stellt eine PHP-Klasse bereit, die Optionen wie Seitenränder, Papierformat und Kopf- und Fußzeilen komfortabel entgegennimmt. Weil wkhtmltopdf intern eine vollständige WebKit-Instanz startet, unterstützt es zusätzlich @page-Regeln für Seitenränder direkt im CSS, was bei Dompdf nur eingeschränkt funktioniert. Für Rechnungen mit fortlaufenden Seitenzahlen über mehrere Positionen hinweg ist das ein spürbarer Vorteil.

Ein Unterschied in der Praxis: wkhtmltopdf lädt lokale Bilddateien über relative Pfade zuverlässiger als Dompdf, solange der Arbeitsordner korrekt gesetzt ist, weil die WebKit-Engine dieselbe Pfadauflösung wie ein normaler Browser verwendet. Für Firmenlogos, die im selben Verzeichnis wie die HTML-Vorlage liegen, bedeutet das weniger Konfigurationsaufwand als bei Dompdf, wo Bildpfade häufig als absolute Dateisystempfade angegeben werden müssen.

<?php

declare(strict_types=1);

use Knp\Snappy\Pdf;

// wkhtmltopdf via the Snappy wrapper — supports @page CSS rules
$snappy = new Pdf('/usr/local/bin/wkhtmltopdf');
$snappy->setOption('page-size', 'A4');
$snappy->setOption('margin-top', '15mm');
$snappy->setOption('margin-bottom', '15mm');
$snappy->setOption('encoding', 'UTF-8');

$snappy->generateFromHtml(
    file_get_contents(__DIR__ . '/dist/invoice.html'),
    __DIR__ . '/output/invoice-2026-0142.pdf'
);

7. Schriftarten und Zahlenformatierung in beiden Bibliotheken

Rechnungen enthalten häufig Zahlenwerte, die im deutschen Format mit Komma als Dezimaltrennzeichen und Punkt als Tausendertrennzeichen dargestellt werden müssen. Diese Formatierung erfolgt idealerweise bereits in PHP vor dem Einsetzen in die Tailwind-Vorlage, etwa über number_format($betrag, 2, ',', '.'), statt sich auf clientseitige Formatierung zu verlassen, die in beiden PDF-Bibliotheken ohnehin nicht zur Verfügung steht, da kein JavaScript ausgeführt wird.

Bei Schriftarten zeigt sich ein weiterer Unterschied: Dompdf bringt eine begrenzte Auswahl an eingebetteten Schriftarten mit, während wkhtmltopdf über die System-Schriftarten des Servers rendert und deshalb theoretisch mehr Auswahl bietet, praktisch aber von der Konsistenz der Server-Konfiguration abhängt. Für maximale Kontrolle über das Erscheinungsbild empfiehlt sich in beiden Fällen, eine spezifische Schriftdatei mitzuliefern und explizit im CSS über @font-face mit lokalem Dateipfad einzubinden, statt sich auf Systemschriften zu verlassen.

<?php

declare(strict_types=1);

// Format amounts in German locale before inserting them into the Tailwind template
$formatted = number_format($lineItem->getTotal(), 2, ',', '.') . ' EUR';

/* Embed a local font file explicitly, do not rely on system fonts */
@font-face {
  font-family: "Inter";
  src: url("fonts/inter-regular.ttf") format("truetype");
}
body { font-family: "Inter", "DejaVu Sans", sans-serif; }

8. Integration in Symfony und Rechnungsarchivierung

In Symfony-Projekten lässt sich sowohl Dompdf als auch wkhtmltopdf als Service registrieren, der von einem Controller oder einer Konsolen-Kommandozeile aufgerufen wird, um Rechnungen aus Bestelldaten zu generieren. Twig übernimmt dabei das Rendering der HTML-Vorlage mit eingesetzten Bestelldaten, bevor das resultierende HTML an Dompdf oder wkhtmltopdf zur PDF-Konvertierung übergeben wird. Diese Trennung hält die Rechnungslogik in Twig-Templates und die PDF-Konvertierung als austauschbaren Infrastruktur-Baustein.

Für die gesetzlich vorgeschriebene Rechnungsarchivierung ist es wichtig, das erzeugte PDF unveränderlich zu speichern, meist in einem dedizierten Speicherordner mit fortlaufender Rechnungsnummer im Dateinamen, und zusätzlich einen Prüfsummen-Hash der Datei in der Datenbank zu hinterlegen. Das ermöglicht später den Nachweis, dass eine archivierte Rechnung nach der Erstellung nicht mehr verändert wurde, unabhängig davon, ob Dompdf oder wkhtmltopdf für die ursprüngliche Generierung verwendet wurde.

<?php

declare(strict_types=1);

// Store the PDF immutably and record a checksum for audit purposes
$pdfContent = $dompdf->output();
$path = sprintf('/var/invoices/%s.pdf', $invoiceNumber);
file_put_contents($path, $pdfContent);

$invoice->setChecksum(hash('sha256', $pdfContent));
$invoice->setArchivedAt(new \DateTimeImmutable());
$entityManager->flush();

9. Dompdf und wkhtmltopdf im direkten Vergleich

Die folgende Übersicht fasst die praktischen Unterschiede zusammen, die bei der Wahl zwischen beiden Bibliotheken für Tailwind-basierte PDF-Rechnungen entscheidend sind.

Für neue Projekte ohne Bestandslast ist Dompdf wegen der einfacheren Installation und der aktiven Weiterentwicklung meist die pragmatischere Wahl, sofern die Rechnungsvorlage konsequent auf Tabellen-Layout statt Flexbox setzt. wkhtmltopdf bleibt relevant für Bestandsprojekte, die bereits darauf aufbauen, oder wenn @page-CSS-Regeln für komplexere Kopf- und Fußzeilen über mehrere Seiten benötigt werden.

10. Zusammenfassung

Dompdf und wkhtmltopdf sind die naheliegenden Optionen für PDF-Rechnungen in reinen PHP-Umgebungen ohne Node.js-Abhängigkeit. Beide unterstützen nur eine Teilmenge des modernen CSS, das Tailwind normalerweise erzeugt, weshalb Rechnungsvorlagen konsequent auf tabellenbasiertes Layout statt Flexbox oder Grid ausgelegt werden müssen. Dompdf punktet mit einfacher Composer-Installation und aktiver Weiterentwicklung, während wkhtmltopdf dank seiner WebKit-Basis etwas mehr modernes CSS versteht, dafür aber ein zusätzliches Systembinary erfordert und offiziell nicht mehr weiterentwickelt wird.

Für neue Projekte ist Dompdf meist die pragmatischere Wahl. Unabhängig von der gewählten Bibliothek gilt: korrekte UTF-8-Konfiguration, explizit eingebundene Schriftarten und serverseitig vorformatierte Zahlenwerte sind Pflicht, damit eine Tailwind-Rechnungsvorlage in beiden PDF-Bibliotheken zuverlässig und professionell aussieht.

Für Teams mit ohnehin vorhandener Node.js-Infrastruktur bleibt Puppeteer die treuere Alternative mit vollem modernem CSS-Funktionsumfang, während Dompdf und wkhtmltopdf dort ihre Stärken ausspielen, wo eine reine PHP-Umgebung Pflicht ist.

11. FAQ: PDF-Rechnungen mit Tailwind CSS, Dompdf und wkhtmltopdf