Signatur
Beschreibung
Die Klasse wkhtmltox\PDF\Converter ist Teil der PHP-Erweiterung wkhtmltox und stellt die zentrale Schnittstelle zur wkhtmltopdf-Bibliothek dar. Sie ermöglicht es, HTML-Seiten – aus Dateien, URLs oder rohen HTML-Strings – serverseitig in PDF-Dokumente umzuwandeln, ohne einen externen Prozess starten zu müssen.
Der typische Arbeitsablauf besteht darin, zunächst ein wkhtmltox\PDF\Converter-Objekt zu instanziieren (optionale globale Einstellungen können über ein assoziatives Array übergeben werden), anschließend eine oder mehrere wkhtmltox\PDF\Object-Instanzen via add() hinzuzufügen und schließlich convert() aufzurufen. Das fertige PDF kann danach mit output() als String abgerufen werden.
Globale Einstellungen betreffen das gesamte Dokument (z. B. Seitengröße, Ränder, DPI, Header/Footer auf Dokumentebene), während objektspezifische Einstellungen auf jeder einzelnen Seite individuell gesetzt werden können. Dies erlaubt sehr flexible Konfigurationen für mehrteilige Dokumente.
Da wkhtmltox intern einen Webkit-basierten Renderer verwendet, können JavaScript-lastige Seiten problematisch sein. Die Erweiterung ist nicht thread-safe und sollte nicht parallel im selben Prozess verwendet werden.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $settings | array | [] | Assoziatives Array mit globalen Konverter-Einstellungen. Mögliche Schlüssel sind z. B. out (Ausgabedatei), size.paperSize (z. B. A4), margin.top, margin.bottom, margin.left, margin.right, dpi, imageDPI, imageQuality und orientation (Landscape oder Portrait). |
Beispiele
Einfache HTML-URL in PDF konvertieren und ausgeben
<?php
use wkhtmltox\PDF\Converter;
use wkhtmltox\PDF\Object;
// Globale Einstellungen für das gesamte PDF-Dokument
$converter = new Converter([
'size.paperSize' => 'A4',
'orientation' => 'Portrait',
'margin.top' => '10mm',
'margin.bottom' => '10mm',
'margin.left' => '10mm',
'margin.right' => '10mm',
]);
// Seite aus einer URL hinzufügen
$page = new Object('https://example.com', [
'load.jsDelay' => '1000', // Warte 1 Sekunde auf JS-Ausführung
]);
$converter->add($page);
// Konvertierung durchführen
$converter->convert();
// PDF-Daten als String holen und an den Browser senden
$pdfData = $converter->output();
header('Content-Type: application/pdf');
header('Content-Disposition: inline; filename="ausgabe.pdf"');
header('Content-Length: ' . strlen($pdfData));
echo $pdfData;Mehrseitiges PDF aus rohem HTML und URL zusammenstellen
<?php
use wkhtmltox\PDF\Converter;
use wkhtmltox\PDF\Object;
$converter = new Converter([
'size.paperSize' => 'A4',
'out' => '/tmp/ausgabe.pdf', // Direkt in Datei speichern
'dpi' => '150',
]);
// Erste Seite: rohes HTML als Deckblatt
$deckblatt = new Object(
'<html><body><h1>Mein Bericht</h1><p>Erstellt am ' . date('d.m.Y') . '</p></body></html>',
['page.isHtml' => true] // Rohen HTML-String übergeben
);
$converter->add($deckblatt);
// Zweite Seite: externe URL
$inhalt = new Object('https://example.com/bericht', [
'load.blockLocalFileAccess' => false,
]);
$converter->add($inhalt);
try {
$converter->convert();
echo 'PDF wurde erfolgreich unter /tmp/ausgabe.pdf gespeichert.';
} catch (\Exception $e) {
echo 'Fehler bei der PDF-Erzeugung: ' . htmlspecialchars($e->getMessage());
}// Wichtig · Fallstricke
Sicherheit: Übergeben Sie niemals ungeprüfte Benutzereingaben als HTML-Inhalt oder URL an wkhtmltox\PDF\Object. wkhtmltopdf kann lokale Dateien lesen (file://-Protokoll), was bei SSRF-Angriffen ausgenutzt werden kann. Setzen Sie load.blockLocalFileAccess auf true und validieren Sie URLs sorgfältig.
Thread-Safety: Die wkhtmltox-Bibliothek ist nicht thread-safe. Verwenden Sie den Converter nicht in parallelen Threads oder Forks desselben Prozesses. In PHP-FPM-Umgebungen mit mehreren Worker-Prozessen ist dies in der Regel kein Problem, solange jeder Worker nur einen Converter gleichzeitig verwendet.
JavaScript-Unterstützung: Ob JavaScript ausgeführt wird, hängt davon ab, ob wkhtmltopdf mit der patched-Qt-Variante kompiliert wurde. Über die Einstellung load.jsDelay kann eine Wartezeit in Millisekunden angegeben werden, um asynchrone Skripte abzuwarten.
Abhängigkeit: Die PHP-Erweiterung wkhtmltox muss kompiliert und in der php.ini aktiviert sein. Die zugehörige native Bibliothek libwkhtmltox muss auf dem System installiert sein.