Guida per sviluppatori Artisan

In sintesi

Il pacchetto Artisan ha due responsabilità correlate: eseguire il rendering dell’HTML tramite Chrome e importare la pagina PDF risultante in un documento NextPDF. Durante il debug, considerare separatamente i confini tra Chrome, parser e importatore.

Usare questa guida quando si scrivono integrazioni con il renderer, worker a lunga durata, diagnostica del parser o test relativi a nextpdf/artisan.

Confine architetturale

Livello	Proprietario	Responsabilità	Da non inserire qui
Applicazione	Applicazione	Autorizzare la generazione dell’HTML e scegliere la configurazione del renderer.	Gestione del processo del browser.
Criterio HTML	Applicazione e pacchetto	Rifiutare l’HTML non sicuro o sovradimensionato prima del rendering.	Autorizzazioni del tenant o decisioni di business.
Renderer Chrome	`nextpdf/artisan`	Eseguire il rendering dell’HTML in un PDF autonomo prodotto da Chrome.	Riparazione generica o modifica arbitraria del PDF.
Parser/importatore	`nextpdf/artisan`	Analizzare il PDF renderizzato e importare una pagina come form XObject.	Convalida completa della conformità PDF.
Motore principale	`nextpdf/nextpdf`	Posizionare gli oggetti form importati e scrivere il documento finale.	Ciclo di vita CDP di Chrome.

Ciclo di vita a runtime

Fase	Comportamento	Azione dello sviluppatore
Creazione della configurazione	`ChromeRendererConfig` definisce il binario, il timeout, il CSS, la dimensione dell’input e il comportamento della sandbox.	Usare una configurazione specifica per l’ambiente invece di assunzioni di runtime codificate in modo rigido.
Creazione del renderer	`ChromeHtmlRenderer` mantiene un `BrowserPool`.	Riutilizzare il renderer all’interno di un worker, quindi chiuderlo all’arresto.
Convalida dell’HTML	Il criterio di sicurezza verifica la dimensione e avvolge il documento con il CSS predefinito.	Convalidare l’autorizzazione del chiamante prima di questa fase.
Stampa di Chrome	CDP esegue il rendering di un PDF autonomo.	Mantenere le risorse esterne bloccate, a meno che un criterio sottoposto a revisione non le consenta.
Analisi del PDF	`PdfReader::parse()` legge i dati xref, le pagine, gli oggetti, le risorse e le revisioni.	Trattare gli errori del parser come errori di rendering, a meno che l’obiettivo non sia la diagnostica.
Importazione della pagina	`PageImporter::import()` estrae il contenuto della pagina, il media box, le risorse e gli oggetti incorporati.	Importare la pagina `0`, a meno che il flusso di lavoro non scelga deliberatamente un’altra pagina.

Struttura consigliata dell’applicazione

Percorso	Scopo
`app/Pdf/Renderers/*`	Wrapper applicativo attorno a `ChromeHtmlRenderer`.
`app/Pdf/Templates/*`	Rendering dei template HTML e mappatura dai DTO alla vista.
`app/Pdf/Policies/*`	Criterio di rendering per dimensione HTML, risorse e tenant.
`tests/Pdf/Renderer/*`	Smoke test del renderer con piccole fixture HTML.
`tests/Pdf/Parser/*`	Fixture del parser per l’output importato da Chrome.

Tenere separato il rendering dei template da quello del browser. Il renderer deve ricevere l’HTML finale e una larghezza di pagina nota.

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

Pattern del renderer

Creare un renderer per ciascun processo worker o ambito di richiesta. Riutilizzare il renderer evita il costo ripetuto di avvio di Chrome. Chiuderlo esplicitamente evita perdite di processi durante l’arresto del worker.

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

Pattern di diagnostica del parser

Le API del parser sono utili quando l’output di Chrome non può essere importato. Mantenere la diagnostica in sola lettura ed evitare di modificare lo stato del parser dopo un’importazione riuscita.

Domanda diagnostica	API da usare	Segnale previsto
Il file viene analizzato correttamente?	`PdfReader::parse()`	Solleva un’eccezione in caso di struttura PDF non valida.
La pagina `0` esiste?	`PdfReader::getPage(0)`	Restituisce un `PdfObject`.
È presente contenuto?	`PdfReader::getPageContentStream($page)`	Flusso di contenuti non vuoto.
Sono presenti risorse?	`PdfReader::getPageResources($page)`	Array del dizionario delle risorse.
Sono presenti revisioni incrementali?	`PdfReader::getRevisionCount()`	Conteggio superiore a uno.
Quale oggetto ha causato l’errore?	`PdfTokenizer::getOffset()` e contesto dell’eccezione del parser.	Offset in byte per ridurre la fixture.

Punti di estensione

Punto di estensione	Da usare per	Vincolo
`ChromeRendererConfig::fromArray()`	Mappatura della configurazione del framework.	I valori opzionali sconosciuti o di tipo errato ricadono sui valori predefiniti.
`HtmlSecurityPolicyInterface`	Criterio HTML in fase di analisi.	Non sostituisce i controlli di trasporto, di processo o di autorizzazione.
`LoggerInterface`	Diagnostica del rendering e del browser.	Non registrare il contenuto HTML per impostazione predefinita.
`BrowserPool`	Riutilizzo di processi Chrome a lunga durata.	Deve essere chiuso all’arresto del worker.
`PageImporter`	Incorporamento di una pagina esterna analizzata.	Il reader deve essere già stato analizzato.
Classi del parser	Diagnostica e output di Chrome da importare.	Non è un toolkit generico per la riparazione del PDF.

Flusso di lavoro di sviluppo

Riprodurre il frammento HTML in un test minimale di rendering.
Convalidare maxHtmlSize, il CSS predefinito e il percorso del binario di Chrome.
Eseguire il rendering con una larghezza fissa in punti.
Analizzare i byte del PDF restituito con PdfReader::parse().
Importare la pagina 0, a meno che il flusso di lavoro non scelga deliberatamente un’altra pagina.
Aggiungere test con fixture per l’HTML minimo che riproduce ogni errore.
Chiudere il renderer negli hook di arresto del worker.

Gestione degli errori

Errore	Dove deve essere gestito	Risposta consigliata
Binario di Chrome mancante	Controllo di distribuzione e percorso di creazione del renderer.	Far fallire il controllo di idoneità prima di accettare traffico di rendering.
HTML sovradimensionato	Criterio HTML.	Rifiutare prima di avviare Chrome.
Timeout del browser	Confine del renderer.	Far fallire il rendering e registrare il nome del template, dimensione, larghezza e timeout.
Errore del parser	Confine dell’importazione.	Archiviare una piccola fixture sanificata per il debug quando il criterio lo consente.
Perdita di processi del browser	Ciclo di vita del worker.	Chiudere all’arresto e riavviare dopo un numero controllato di rendering.

Impostazioni predefinite sicure

Aspetto	Predefinito	Quando eseguire l’override
Timeout di rendering	`30` secondi.	Aumentarlo solo per documenti misurati e con limiti definiti.
Dimensione massima dell’HTML	`5,000,000` byte.	Ridurla per gli endpoint pubblici.
Sandbox	Abilitata.	Disabilitarla solo quando i vincoli del container lo richiedono e l’host è isolato.
Altezza	Automatica quando `heightPt <= 0`.	Usare un’altezza fissa per requisiti di layout rigidi.
Risorse esterne	Bloccate dal criterio del renderer.	Consentirle solo tramite un criterio sulle risorse sottoposto a revisione.

Elenco di controllo per i test

I test di rendering coprono HTML e CSS rappresentativi.
I test di sicurezza coprono l’HTML sovradimensionato e i tentativi di accesso a risorse bloccate.
I test di importazione verificano che l’oggetto form restituito abbia contenuto, media box e risorse.
I test del parser coprono i casi di tabella xref, flusso xref, flusso di oggetti e fixture non valida.
I test del worker chiamano close() e verificano che non rimanga alcun processo del browser.
I test delle prestazioni registrano il tempo di rendering per template e dimensione del contenuto.