Signatur
Beschreibung
Die Klasse wkhtmltox\Image\Converter ist Teil der PHP-Erweiterung wkhtmltox und nutzt intern die Bibliothek wkhtmltoimage, die auf der WebKit-Rendering-Engine basiert. Damit lassen sich Webseiten oder beliebige HTML-Inhalte pixel-getreu als Rastergrafik oder Vektorgrafik rendern.
Der Konverter wird in der Regel mit einem wkhtmltox\Image\Settings-Objekt konfiguriert, das Angaben zu Eingabequelle, Ausgabeformat, Seitengröße, Qualität und weiteren Render-Optionen enthält. Anschließend kann über die convert()-Methode der eigentliche Render-Vorgang angestoßen und das Ergebnis-Bild als Binär-String abgerufen werden.
Typische Anwendungsfälle sind das Erstellen von Website-Screenshots, das Generieren von Vorschaubildern aus dynamischen HTML-Templates oder das Exportieren von Berichten und Dashboards als Bilddateien. Die Klasse eignet sich besonders dann, wenn eine pixelgenaue Darstellung von HTML/CSS erforderlich ist, die mit GD oder Imagick nicht erreichbar wäre.
Hinweis: Die Erweiterung setzt eine korrekt installierte wkhtmltoimage-Bibliothek (Version ≥ 0.12) auf dem Server voraus. Da der Renderer einen vollständigen Browser-Stack aufbaut, ist der Speicher- und CPU-Bedarf im Vergleich zu anderen Konvertierungsmethoden deutlich höher.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $settings Pflicht | wkhtmltox\Image\Settings | Ein konfiguriertes wkhtmltox\Image\Settings-Objekt, das mindestens die Eingabequelle (in) und das gewünschte Ausgabeformat (fmt, z. B. png, jpg, bmp, svg) enthält. |
Rückgabewert
Beispiele
URL als PNG-Bild rendern und speichern
<?php
// Settings-Objekt erstellen und konfigurieren
$settings = new wkhtmltox\Image\Settings();
$settings->in = 'https://example.com'; // Eingabe: URL
$settings->fmt = 'png'; // Ausgabeformat
$settings->out = ''; // Leer = Ausgabe in den Puffer
// Konverter erstellen und rendern
$converter = new wkhtmltox\Image\Converter($settings);
$converter->convert();
// Binäres Bild abrufen und in Datei speichern
$imageData = $converter->output();
file_put_contents('/tmp/screenshot.png', $imageData);
echo 'Bild gespeichert: ' . strlen($imageData) . ' Bytes';
Rohen HTML-String als JPEG direkt an den Browser senden
<?php
$html = '<html><body style="background:#4a90d9;font-family:sans-serif;">
<h1 style="color:#fff;padding:40px;">Hallo Welt</h1>
</body></html>';
// Temporäre HTML-Datei schreiben
$tmpFile = tempnam(sys_get_temp_dir(), 'wk_') . '.html';
file_put_contents($tmpFile, $html);
$settings = new wkhtmltox\Image\Settings();
$settings->in = $tmpFile;
$settings->fmt = 'jpg';
$settings->quality = 90;
$settings->out = '';
$converter = new wkhtmltox\Image\Converter($settings);
$converter->convert();
// Bild direkt ausgeben
header('Content-Type: image/jpeg');
echo $converter->output();
unlink($tmpFile);
// Wichtig · Fallstricke
Ressourcenverbrauch: Jeder Aufruf von convert() startet intern eine vollständige WebKit-Rendering-Pipeline. In Umgebungen mit hohem Durchsatz sollte das Konvertieren in einen separaten Prozess oder eine Queue ausgelagert werden, um PHP-FPM-Worker nicht zu blockieren.
Sicherheit: Wenn die Eingabe-URL oder der HTML-Inhalt aus Benutzereingaben stammt, besteht die Gefahr von Server-Side Request Forgery (SSRF). Validieren und whitelisten Sie erlaubte URLs konsequent, bevor Sie sie an den Konverter übergeben.
Fehlerbehandlung: Schlägt convert() fehl (z. B. wegen einer nicht erreichbaren URL), wirft die Methode eine Exception. Kapseln Sie den Aufruf daher stets in einem try/catch-Block.