Artisan-Entwicklerhandbuch

Auf einen Blick

Das Artisan-Paket erfüllt zwei miteinander verknüpfte Aufgaben: Es rendert HTML über Chrome und importiert die entstandene PDF-Seite in ein NextPDF-Dokument. Betrachten Sie die Grenzen von Chrome, Parser und Importer beim Debugging getrennt.

Verwenden Sie dieses Handbuch, wenn Sie Renderer-Integrationen, langlebige Worker, Parser-Diagnosen oder Tests rund um nextpdf/artisan schreiben.

Architekturgrenze

Schicht	Verantwortlich	Aufgabe	Gehört nicht hierher
Anwendung	Anwendung	Die HTML-Erzeugung autorisieren und die Renderer-Konfiguration auswählen.	Verwaltung des Browser-Prozesses.
HTML-Richtlinie	Anwendung und Paket	Unsicheres oder zu großes HTML vor dem Rendern ablehnen.	Mandantenautorisierung oder Geschäftsentscheidungen.
Chrome-Renderer	`nextpdf/artisan`	HTML in ein eigenständiges, von Chrome erzeugtes PDF rendern.	Allgemeine PDF-Reparatur oder beliebige PDF-Bearbeitung.
Parser/Importer	`nextpdf/artisan`	Das gerenderte PDF parsen und eine Seite als Form-XObject importieren.	Vollständige PDF-Konformitätsprüfung.
Kern-Engine	`nextpdf/nextpdf`	Importierte Form-Objekte platzieren und das fertige Dokument schreiben.	Chrome-CDP-Lebenszyklus.

Laufzeit-Lebenszyklus

Phase	Verhalten	Entwickler-Aktion
Konfiguration erstellen	`ChromeRendererConfig` legt Binary, Timeout, CSS, Eingabegröße und Sandbox-Verhalten fest.	Verwenden Sie umgebungsspezifische Konfiguration statt fest verdrahteter Laufzeitannahmen.
Renderer erstellen	`ChromeHtmlRenderer` besitzt einen `BrowserPool`.	Verwenden Sie den Renderer innerhalb eines Workers wieder und schließen Sie ihn beim Herunterfahren.
HTML-Validierung	Die Sicherheitsrichtlinie prüft die Größe und umschließt das Dokument mit Standard-CSS.	Validieren Sie die Aufruferautorisierung vor dieser Phase.
Chrome-Druck	CDP rendert ein eigenständiges PDF.	Halten Sie externe Ressourcen blockiert, sofern keine geprüfte Richtlinie sie zulässt.
PDF-Parsing	`PdfReader::parse()` liest Xref-Daten, Seiten, Objekte, Ressourcen und Revisionen.	Behandeln Sie Parser-Fehler als Render-Fehler, sofern die Diagnose nicht das Ziel ist.
Seitenimport	`PageImporter::import()` extrahiert Seiteninhalt, Media-Box, Ressourcen und eingebettete Objekte.	Importieren Sie Seite `0`, sofern der Workflow nicht bewusst eine andere Seite wählt.

Empfohlene Anwendungsstruktur

Pfad	Zweck
`app/Pdf/Renderers/*`	Anwendungs-Wrapper für `ChromeHtmlRenderer`.
`app/Pdf/Templates/*`	HTML-Template-Rendering und DTO-zu-View-Mapping.
`app/Pdf/Policies/*`	Richtlinien für HTML-Größe, Ressourcen und Mandanten-Rendering.
`tests/Pdf/Renderer/*`	Renderer-Smoke-Tests mit kleinen HTML-Fixtures.
`tests/Pdf/Parser/*`	Parser-Fixtures für importierte Chrome-Ausgaben.

Halten Sie Template-Rendering und Browser-Rendering getrennt. Der Renderer sollte fertiges HTML und eine bekannte Seitenbreite erhalten.

<?php

use NextPDF\Artisan\ChromeHtmlRenderer;
use NextPDF\Artisan\ChromeRendererConfig;
use NextPDF\Artisan\PageImporter;
use NextPDF\Parser\PdfReader;

$renderer = new ChromeHtmlRenderer(new ChromeRendererConfig(
    renderTimeout: 30,
    maxHtmlSize: 1_000_000,
));

$result = $renderer->render($html, widthPt: 595.28);

$reader = new PdfReader($result->getPdfData());
$reader->parse();

$form = (new PageImporter())->import($reader);

Renderer-Muster

Erstellen Sie einen Renderer pro Worker-Prozess oder pro Request-Scope. Die Wiederverwendung des Renderers vermeidet wiederholte Chrome-Startkosten. Das explizite Schließen verhindert Prozess-Leaks beim Herunterfahren des Workers.

<?php

final class InvoiceChromeRenderer
{
    public function __construct(
        private readonly ChromeHtmlRenderer $renderer,
    ) {}

    public function renderInvoice(string $html): string
    {
        return $this->renderer
            ->render($html, widthPt: 595.28)
            ->getPdfData();
    }

    public function close(): void
    {
        $this->renderer->close();
    }
}

Muster für Parser-Diagnose

Die Parser-APIs sind nützlich, wenn der Import der Chrome-Ausgabe fehlschlägt. Halten Sie die Diagnose schreibgeschützt und ändern Sie den Parser-Zustand nach einem erfolgreichen Import nicht.

Diagnose-Frage	Zu verwendende API	Erwartetes Signal
Lässt sich die Datei parsen?	`PdfReader::parse()`	Löst bei ungültiger PDF-Struktur eine Ausnahme aus.
Existiert Seite `0`?	`PdfReader::getPage(0)`	Liefert ein `PdfObject`.
Ist Inhalt vorhanden?	`PdfReader::getPageContentStream($page)`	Ein nicht leerer Content-Stream.
Sind Ressourcen vorhanden?	`PdfReader::getPageResources($page)`	Ein Array des Ressourcen-Dictionarys.
Gibt es inkrementelle Revisionen?	`PdfReader::getRevisionCount()`	Eine Anzahl größer als eins.
Welches Objekt ist fehlgeschlagen?	`PdfTokenizer::getOffset()` und Kontext der Parser-Ausnahme.	Byte-Offset, um die Fixture zu verkleinern.

Erweiterungspunkte

Erweiterungspunkt	Verwende ihn für	Einschränkung
`ChromeRendererConfig::fromArray()`	Mapping der Framework-Konfiguration.	Unbekannte oder falsch typisierte optionale Werte fallen auf die Standardwerte zurück.
`HtmlSecurityPolicyInterface`	HTML-Richtlinie auf Parser-Ebene.	Ersetzt keine Transport-, Prozess- oder Autorisierungskontrollen.
`LoggerInterface`	Render- und Browser-Diagnose.	Protokollieren Sie HTML-Inhalte standardmäßig nicht.
`BrowserPool`	Wiederverwendung eines langlebigen Chrome-Prozesses.	Muss beim Herunterfahren des Workers geschlossen werden.
`PageImporter`	Einbetten einer geparsten externen Seite.	Der Reader muss zuerst geparst werden.
Parser-Klassen	Diagnose und importierte Chrome-Ausgaben.	Kein allgemeines PDF-Reparatur-Toolkit.

Entwicklungs-Workflow

Reproduzieren Sie das HTML-Fragment in einem minimalen Render-Test.
Validieren Sie maxHtmlSize, das Standard-CSS und den Pfad zur Chrome-Binary.
Rendern Sie mit einer festen Breite in Punkt.
Parsen Sie die zurückgegebenen PDF-Bytes mit PdfReader::parse().
Importieren Sie Seite 0, sofern der Workflow nicht bewusst eine andere Seite wählt.
Fügen Sie Fixture-Tests für das kleinste HTML hinzu, das jeden Fehler reproduziert.
Schließen Sie den Renderer in den Shutdown-Hooks des Workers.

Fehlerbehandlung

Fehler	Wo er behandelt werden sollte	Empfohlene Reaktion
Chrome-Binary fehlt	Deployment-Prüfung und Konstruktionspfad des Renderers.	Lassen Sie die Bereitschaftsprüfung fehlschlagen, bevor Sie Render-Traffic annehmen.
Zu großes HTML	HTML-Richtlinie.	Vor dem Start von Chrome ablehnen.
Browser-Timeout	Renderer-Grenze.	Lassen Sie das Rendern fehlschlagen und erfassen Sie Template-Name, Größe, Breite und Timeout.
Parser-Fehler	Import-Grenze.	Speichern Sie eine kleine bereinigte Fixture zum Debuggen, wenn die Richtlinie es erlaubt.
Browser-Prozess-Leak	Worker-Lebenszyklus.	Schließen Sie ihn beim Herunterfahren und starten Sie ihn nach kontrollierten Render-Zählwerten neu.

Sichere Standardwerte

Anliegen	Standard	Wann überschreiben
Render-Timeout	`30` Sekunden.	Erhöhen Sie ihn nur für gemessene, begrenzte Dokumente.
Maximale HTML-Größe	`5,000,000` Bytes.	Für öffentliche Endpunkte niedriger festlegen.
Sandbox	Aktiviert.	Nur deaktivieren, wenn Container-Einschränkungen es erfordern und der Host isoliert ist.
Höhe	Automatisch, wenn `heightPt <= 0`.	Verwenden Sie eine feste Höhe für strikte Layout-Verträge.
Externe Ressourcen	Durch die Renderer-Richtlinie blockiert.	Nur über eine geprüfte Ressourcen-Richtlinie zulassen.

Test-Checkliste

Render-Tests decken repräsentatives HTML und CSS ab.
Sicherheitstests decken zu großes HTML und Versuche mit blockierten Ressourcen ab.
Import-Tests prüfen, dass das zurückgegebene Form-Objekt Inhalt, Media-Box und Ressourcen enthält.
Parser-Tests decken Xref-Tabelle, Xref-Stream, Objekt-Stream und fehlerhafte Fixture-Fälle ab.
Worker-Tests rufen close() auf und prüfen, dass kein Browser-Prozess zurückbleibt.
Performance-Tests erfassen die Render-Zeit nach Template und Inhaltsgröße.