Artisan-Schnellstart

Auf einen Blick

Weisen Sie einem NextPDF-Dokument eine ChromeRendererConfig zu, rufen Sie writeHtmlChrome() auf und speichern Sie es. Chrome rendert das HTML, die Brücke importiert das Ergebnis als Form-XObject, und der Text bleibt auswählbar.

Konzeptioneller Überblick

writeHtmlChrome() ist eine Methode des NextPDF-Core-Document, die der HasTextOutput-Concern bereitstellt. Die Methode validiert die Eingabe, löst den Artisan-Renderer auf, übergibt das HTML an Chrome, parst das zurückgegebene PDF und bettet Seite 0 als Form-XObject an der aktuellen Cursor-Position ein. Die öffentliche Signatur lautet writeHtmlChrome(string $html, ?float $width = null, ?float $height = null): static — verifiziert anhand von nextpdf/coresrc/Core/Concerns/HasTextOutput.php.

Codebeispiel — Schnellstart

quickstart.php

<?php

declare(strict_types=1);

use NextPDF\Core\Document;
use NextPDF\Artisan\ChromeRendererConfig;

require __DIR__ . '/vendor/autoload.php';

$config = new ChromeRendererConfig(
    chromeBinaryPath: '/usr/bin/chromium',
);

$doc = Document::createStandalone();
$doc->setChromeRendererConfig($config);
$doc->addPage();

$doc->writeHtmlChrome('
    <div style="display: flex; gap: 20px; font-family: sans-serif;">
        <div style="flex: 1; background: #f0f0f0; padding: 24px;">
            <h2>Revenue</h2><p style="font-size: 2em; color: #2563eb;">$124,500</p>
        </div>
        <div style="flex: 1; background: #f0f0f0; padding: 24px;">
            <h2>Orders</h2><p style="font-size: 2em; color: #16a34a;">1,847</p>
        </div>
    </div>
');

$doc->save('/tmp/report.pdf');

Dies ist der kanonische Ablauf aus der README.md des Pakets. Chrome übernimmt das flex-Layout. Die Zahlen bleiben in der Ausgabe als Text auswählbar, weil die Seite als Form-XObject und nicht als Rasterbild eingebettet wird.

Benutzerdefinierte Seitengröße

Übergeben Sie Breite und Höhe explizit in PDF-Punkten, um auf eine feste Seitengröße zu rendern (hier A4):

$doc->writeHtmlChrome($html, width: 595.28, height: 841.89);

Wenn Sie beide Werte angeben, druckt Chrome exakt auf diese Papiergröße. Wenn Sie die Höhe weglassen (oder null übergeben), passt die Brücke die Höhe automatisch an die gemessene Inhaltshöhe an und fügt einen kleinen Sicherheitspuffer für den Umbruch hinzu. Unter /integrations/artisan/production-usage/ erfahren Sie, warum dieser Puffer existiert und wann Sie ihn überschreiben sollten.

Was Sie erhalten

Eigenschaft	Verhalten
Text	Auswählbar und durchsuchbar (Vektortext, nicht gerastert)
CSS	Chrome-Layout — Flexbox, Grid, komplexe Selektoren, Webfonts über Data-URIs
Netzwerk	Keine Subresource-Abrufe; entfernte URLs werden nicht geladen (siehe /integrations/artisan/security-and-operations/)
Seiten	Seite 0 der Chrome-Ausgabe wird importiert

Sonderfälle & Fallstricke

• Leeres HTML ist ein No-op. writeHtmlChrome('') gibt das Dokument unverändert zurück (verifiziert in HasTextOutput::writeHtmlChrome).
• Noch keine Seite vorhanden. Wenn keine Seite existiert, fügt writeHtmlChrome() vor dem Rendern eine hinzu.
• Entfernte Assets werden nicht geladen. <img src="https://..."> rendert leer. Binden Sie Assets inline als data:-URIs ein. Das ist die vorgesehene Netzwerkisolation, kein Bug. Siehe /integrations/artisan/security-and-operations/.
• Brücke fehlt. Wenn nextpdf/artisan nicht installiert ist, wirft der Core eine Layout-Exception statt eines fatalen Fehlers.

Performance

Beim ersten Aufruf fallen der Chrome-Start und das Layout an. Weitere Aufrufe verwenden den laufenden Chrome-Prozess über den BrowserPool wieder. Für Batch-Verarbeitung oder langlaufende Worker lesen Sie die Hinweise zu Lifecycle und Ressourcen auf der Seite /integrations/artisan/production-usage/.

Sicherheitshinweise

Der Schnellstart verwendet vertrauenswürdiges, fest codiertes HTML. Bevor Sie writeHtmlChrome() HTML übergeben, das in irgendeiner Weise von Nutzern beeinflusst wird, lesen Sie /integrations/artisan/security-and-operations/. Die Brücke isoliert den Netzwerkzugriff, doch das Rendern von HTML bietet weiterhin eine Angriffsfläche.

Kommerzieller Kontext

Damit erzeugen Sie mit der Open-Source-Brücke ein PDF aus HTML. Um eine konforme E-Rechnungs-XML in dasselbe Dokument einzubetten, stellt die Premium-Pro-Stufe einen Embedder bereit. Der Open-Source-Pfad bleibt unberührt, wenn Premium nicht vorhanden ist.

Siehe auch

• /integrations/artisan/install/
• /integrations/artisan/configuration/
• /integrations/artisan/production-usage/
• /integrations/artisan/troubleshooting/
• /integrations/artisan/security-and-operations/