Ontwikkelaarsgids voor Artisan

In het kort

Het Artisan-pakket heeft twee nauw gekoppelde verantwoordelijkheden: Hypertext Markup Language (HTML) renderen via Chrome en de resulterende Portable Document Format (PDF)-pagina importeren in een NextPDF-document. Houd bij het opsporen van problemen de grenzen tussen Chrome, parser en importer duidelijk gescheiden.

Gebruik deze gids wanneer u renderer-integraties, langlopende workers, parserdiagnostiek of tests voor nextpdf/artisan schrijft.

Architectuurgrens

Laag	Eigenaar	Verantwoordelijkheid	Plaats hier niet
Applicatie	Applicatie	Autoriseer het genereren van HTML en kies de rendererconfiguratie.	Beheer van browserprocessen.
HTML-beleid	Applicatie en pakket	Weiger onveilige of te grote HTML voordat u rendert.	Tenant-autorisatie of zakelijke beslissingen.
Chrome-renderer	`nextpdf/artisan`	Render HTML naar een zelfstandig PDF-bestand dat Chrome heeft geproduceerd.	Algemene PDF-reparatie of willekeurige PDF-bewerking.
Parser/importer	`nextpdf/artisan`	Parseer het gerenderde PDF-bestand en importeer één pagina als form-XObject.	Volledige PDF-conformiteitsvalidatie.
Core-engine	`nextpdf/nextpdf`	Plaats geïmporteerde form-objecten en schrijf het uiteindelijke document.	Levenscyclus van het Chrome DevTools Protocol (CDP).

Levenscyclus tijdens uitvoering

Fase	Gedrag	Ontwikkelaarsactie
Configuratie aanmaken	`ChromeRendererConfig` definieert de binary, de time-out, de Cascading Style Sheets (CSS), de invoergrootte en het sandboxgedrag.	Gebruik omgevingsspecifieke configuratie in plaats van hardgecodeerde aannames over de uitvoeringsomgeving.
Renderer aanmaken	`ChromeHtmlRenderer` beheert een `BrowserPool`.	Hergebruik de renderer binnen een worker en sluit deze af wanneer de worker stopt.
HTML-validatie	Het beveiligingsbeleid controleert de grootte en voorziet het document van standaard-CSS.	Valideer de autorisatie van de aanroeper vóór deze fase.
Chrome print	CDP rendert een zelfstandig PDF-bestand.	Houd externe resources geblokkeerd, tenzij een beoordeeld beleid deze toestaat.
PDF-parse	`PdfReader::parse()` leest xref-gegevens, pagina’s, objecten, resources en revisies.	Behandel parserfouten als renderfouten, tenzij diagnostiek het doel is.
Pagina-import	`PageImporter::import()` extraheert de pagina-inhoud, media box, resources en ingebedde objecten.	Importeer pagina `0`, tenzij de workflow bewust een andere pagina kiest.

Aanbevolen applicatiestructuur

Pad	Doel
`app/Pdf/Renderers/*`	Applicatiewrapper rond `ChromeHtmlRenderer`.
`app/Pdf/Templates/*`	HTML-templaterendering en de mapping van data transfer object (DTO) naar view.
`app/Pdf/Policies/*`	Beleid voor HTML-grootte, resources en tenant-rendering.
`tests/Pdf/Renderer/*`	Smoke-tests voor de renderer met kleine HTML-fixtures.
`tests/Pdf/Parser/*`	Parserfixtures voor geïmporteerde Chrome-uitvoer.

Houd templaterendering gescheiden van browserrendering. Geef de renderer de definitieve HTML en een bekende paginabreedte mee.

<?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);

Rendererpatroon

Maak één renderer per workerproces of per request-scope aan. Hergebruik deze om herhaalde opstartkosten van Chrome te vermijden. Sluit de renderer expliciet af om proceslekken tijdens het afsluiten van de worker te voorkomen.

<?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();
    }
}

Parserdiagnostiekpatroon

Gebruik de application programming interfaces (API’s) van de parser wanneer Chrome-uitvoer niet kan worden geïmporteerd. Zorg dat diagnostiek alleen-lezen blijft en wijzig de parserstatus niet na een geslaagde import.

Diagnostische vraag	Te gebruiken API	Verwacht signaal
Laat het bestand zich parseren?	`PdfReader::parse()`	Werpt een uitzondering bij een ongeldige PDF-structuur.
Bestaat pagina `0`?	`PdfReader::getPage(0)`	Retourneert een `PdfObject`.
Is er inhoud?	`PdfReader::getPageContentStream($page)`	Niet-lege content-stream.
Zijn er resources aanwezig?	`PdfReader::getPageResources($page)`	Array met de resource-dictionary.
Zijn er incrementele revisies?	`PdfReader::getRevisionCount()`	Aantal groter dan één.
Welk object is mislukt?	`PdfTokenizer::getOffset()` en de contextinformatie van de parseruitzondering.	Byte-offset om fixtures te verkleinen.

Uitbreidingspunten

Uitbreidingspunt	Gebruik het voor	Beperking
`ChromeRendererConfig::fromArray()`	Mapping van de frameworkconfiguratie.	Onbekende of verkeerd getypeerde optionele waarden vallen terug op de standaardwaarden.
`HtmlSecurityPolicyInterface`	HTML-beleid op parseerniveau.	Vervangt geen transport-, proces- of autorisatiecontroles.
`LoggerInterface`	Render- en browserdiagnostiek.	Log HTML-inhoud standaard niet.
`BrowserPool`	Hergebruik van langlevende Chrome-processen.	Moet bij het afsluiten van de worker worden gesloten.
`PageImporter`	Het inbedden van een geparseerde externe pagina.	De reader moet eerst worden geparseerd.
Parserklassen	Diagnostiek en geïmporteerde Chrome-uitvoer.	Geen algemene PDF-reparatietoolkit.

Ontwikkelworkflow

Reproduceer het HTML-fragment in een minimale rendertest.
Valideer maxHtmlSize, de standaard-CSS en het pad naar de Chrome-binary.
Render met een vaste breedte in punten.
Parseer de geretourneerde PDF-bytes met PdfReader::parse().
Importeer pagina 0, tenzij de workflow bewust een andere pagina kiest.
Voeg fixturetests toe voor het kleinste HTML-fragment dat elke fout reproduceert.
Sluit de renderer af in de afsluit-hooks van de worker.

Foutafhandeling

Fout	Waar deze moet worden afgehandeld	Aanbevolen respons
Chrome-binary ontbreekt	De deploymentcontrole en het constructiepad van de renderer.	Laat de readiness-controle mislukken voordat u renderverkeer accepteert.
Te grote HTML	HTML-beleid.	Weiger voordat Chrome wordt gestart.
Browser-time-out	Renderergrens.	Laat de render mislukken en leg de templatenaam, grootte, breedte en time-out vast.
Parserfout	Importgrens.	Bewaar een kleine opgeschoonde fixture voor het opsporen van fouten wanneer het beleid dit toestaat.
Lek van browserprocessen	Levenscyclus van de worker.	Sluit de renderer af bij het afsluiten en herstart na een gecontroleerd aantal renders.

Veilige standaardwaarden

Aandachtspunt	Standaard	Wanneer te overschrijven
Render-time-out	`30` seconden.	Verhoog dit alleen voor gemeten, begrensde documenten.
Maximale HTML-grootte	`5,000,000` bytes.	Verlaag dit voor publieke endpoints.
Sandbox	Ingeschakeld.	Schakel dit alleen uit wanneer containerbeperkingen dit vereisen en de host geïsoleerd is.
Hoogte	Automatisch wanneer `heightPt <= 0`.	Gebruik een vaste hoogte voor strikte lay-outcontracten.
Externe resources	Geblokkeerd door het rendererbeleid.	Sta dit alleen toe via een beoordeeld resourcebeleid.

Testchecklist

Rendertests dekken representatieve HTML en CSS.
Beveiligingstests dekken te grote HTML en geblokkeerde pogingen om resources te laden.
Importtests bevestigen dat het geretourneerde form-object inhoud, een media box en resources heeft.
Parsertests dekken de cross-reference-tabel (xref), de xref-stream, de object-stream en gevallen met onjuist opgemaakte fixtures.
Workertests roepen close() aan en verifiëren dat er geen browserproces overblijft.
Performancetests leggen de rendertijd vast per template en inhoudsgrootte.