Panoramica di NextPDF Artisan

In breve

NextPDF Artisan è il bridge Chrome per NextPDF. Invia un frammento HTML a un processo Chrome headless tramite il Chrome DevTools Protocol, acquisisce l’output di printToPDF e incorpora il risultato nel documento di destinazione come Form XObject. Il testo incorporato resta selezionabile e ricercabile.

Panoramica concettuale

Il pacchetto Artisan (nextpdf/artisan) estende il motore open source NextPDF con un renderer che delega a Chrome l’impaginazione. La pipeline HTML nativa di NextPDF copre già un ampio sottoinsieme di CSS. Il bridge Artisan è pensato per i documenti che richiedono un’impaginazione di livello Chrome — flexbox e grid CSS, web font personalizzati caricati da data URI e selettori complessi — continuando però a produrre testo vettoriale anziché uno screenshot rasterizzato.

Il bridge è una pipeline di componenti piccoli, ciascuno con una responsabilità specifica. ChromeHtmlRenderer orchestra un rendering. ChromeSecurityPolicy convalida l’input e lo racchiude in un documento HTML blindato. BrowserPool gestisce il ciclo di vita del processo Chrome. ViewportCalculator mappa i punti PDF sui pixel CSS. Il reader NextPDF\Parser analizza l’output di Chrome e PageImporter lo converte in un Form XObject. Ogni componente è final, usa l’iniezione tramite costruttore ed è tipizzato al livello 10 di PHPStan.

Il bridge è vincolato a dipendenze esterne. Richiede la libreria chrome-php/chrome (^1.15) e un binario Chrome o Chromium raggiungibile dal processo PHP. Nessuno dei due è incluso. Quando la libreria è assente, il bridge solleva ChromeNotAvailableException invece di degradare silenziosamente — vedere /integrations/artisan/failure-modes/ nella pagina /integrations/artisan/troubleshooting/.

Un rendering non raggiunge mai Chrome finché l’input non supera ChromeSecurityPolicy::validate(); il documento ricevuto da Chrome è sempre racchiuso con una Content-Security-Policy rigorosa e con un blocco di rete CDP per difesa in profondità. Poiché il bridge elabora HTML potenzialmente non attendibile, la configurazione di trasporto e isolamento è documentata in modo esplicito nella pagina /integrations/artisan/security-and-operations/ anziché essere riassunta qui.

Questo è il comportamento osservato del pacchetto così come distribuito, verificato rispetto a src/Artisan/ e alla suite tests/Unit/Artisan/. Non costituisce un’affermazione di parità pixel per pixel con un browser Chrome interattivo: le animazioni vengono acquisite nel loro fotogramma finale, l’impaginazione non dipende da JavaScript e viene importata solo la prima pagina di Chrome.

Architettura

Diagram

Responsabilità dei componenti

Componente	Responsabilità	Origine
ChromeHtmlRenderer	Orchestra un singolo rendering; restituisce ChromeRenderResult	src/Artisan/ChromeHtmlRenderer.php
ChromeRendererConfig	Value object di configurazione immutabile	src/Artisan/ChromeRendererConfig.php
ChromeSecurityPolicy	Convalida dell’input + envelope HTML sicuro	src/Artisan/ChromeSecurityPolicy.php
BrowserPool	Ciclo di vita del processo Chrome e criterio di riavvio	src/Artisan/BrowserPool.php
ViewportCalculator	Conversione 72 pt/inch ↔ 96 px/inch	src/Artisan/ViewportCalculator.php
ChromeRenderResult	Output di rendering tipizzato (ChromeRenderResultInterface)	src/Artisan/ChromeRenderResult.php
PageImporter	Pagina Chrome analizzata → ImportedFormXObject	src/Artisan/PageImporter.php
EInvoiceServiceFactory	Factory senza container per i contratti di fatturazione elettronica Premium	src/Artisan/EInvoiceServiceFactory.php

Casi limite e insidie

• Provenienza delle versioni. L’artifact Composer pubblicato è contrassegnato con il tag v0.1.0. I docblock del sorgente riportano @since 1.7.0 (bridge Chrome) e @since 1.1.0 (factory di fatturazione elettronica), entrambi ereditati dalla linea di versione nextpdf/core precedente alla ridenominazione; il pacchetto è stato rinominato in nextpdf/artisan in corrispondenza della voce del CHANGELOG 2.0.0. Considerare il tag Composer come la versione di installazione autorevole e i marcatori @since come origine della versione del motore.
• Solo la prima pagina. PageImporter::import() utilizza per impostazione predefinita l’indice di pagina 0. Il contenuto che eccede e prosegue in una seconda pagina di Chrome viene ritagliato, a meno che non venga fornita un’altezza esplicita — argomento trattato nella pagina /integrations/artisan/production-usage/.
• Nessun container DI. Artisan è privo di container. EInvoiceServiceFactory offre agli ambienti senza service container una superficie di istanziazione coerente; vedere /integrations/artisan/boot-and-discovery/.

Prestazioni

Ogni rendering comporta il costo del caricamento della pagina di Chrome e di printToPDF, una volta per chiamata. BrowserPool mantiene attivo il processo Chrome tra un rendering e l’altro e lo riavvia ogni 100 rendering per limitare la crescita della memoria. La complessità Big-O è dominata dall’impaginazione dell’input da parte di Chrome, non dal bridge in sé. Per il budget misurato del flusso di riferimento di questa pagina, vedere performance_budget nel front matter e la pagina /integrations/artisan/production-usage/.

Note sulla sicurezza

Il bridge esegue il rendering di HTML potenzialmente non attendibile all’interno di Chrome. L’input viene convalidato per dimensione e contenuto prima di essere passato a Chrome. Il documento racchiuso include default-src 'none'. Un blocco a livello di CDP blocca ogni richiesta di sottorisorse. Il modello completo di trasporto e isolamento — inclusi i limiti espliciti del flag sandbox di Chrome — è descritto nella pagina /integrations/artisan/security-and-operations/. Non considerare questa sezione come la configurazione di sicurezza completa.

Contesto commerciale

Il bridge open source esegue il rendering dell’HTML in PDF. I livelli Premium aggiungono l’incorporamento conforme di fatture elettroniche (Pro) e la convalida (Enterprise) sul documento renderizzato. Quando tali livelli non sono installati, EInvoiceServiceFactory restituisce null, così il percorso open source rimane pienamente funzionante anche in loro assenza.

Vedere anche

• /integrations/artisan/install/
• /integrations/artisan/configuration/
• /integrations/artisan/quickstart/
• /integrations/artisan/chrome-renderer-setup/
• /integrations/artisan/security-and-operations/
• /integrations/artisan/production-usage/