Avvio rapido di Artisan

In breve

Associare un ChromeRendererConfig a un documento NextPDF, chiamare writeHtmlChrome() e salvare il documento. Chrome esegue il rendering dell’HTML, il bridge importa il risultato come Form XObject e il testo resta selezionabile.

Panoramica concettuale

writeHtmlChrome() è un metodo di Document, nel core di NextPDF, ed è fornito dal concern HasTextOutput. Il metodo convalida l’input, risolve il renderer Artisan, invia l’HTML a Chrome, analizza il PDF restituito e incorpora la pagina 0 come Form XObject nella posizione del cursore corrente. La firma pubblica è writeHtmlChrome(string $html, ?float $width = null, ?float $height = null): static — verificata rispetto a nextpdf/coresrc/Core/Concerns/HasTextOutput.php.

Esempio di codice — Avvio rapido

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

È il flusso canonico mostrato nel README.md del pacchetto. Chrome gestisce il layout flex. Nel PDF prodotto i numeri restano testo selezionabile, perché la pagina viene incorporata come Form XObject e non come immagine raster.

Dimensioni di pagina personalizzate

Passare larghezza e altezza esplicite, in punti PDF, per usare una pagina fissa (qui A4):

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

Quando si forniscono entrambi i valori, Chrome stampa esattamente con quel formato di carta. Quando si omette l’altezza (o si passa null), il bridge si adatta automaticamente all’altezza misurata del contenuto e aggiunge un piccolo margine di sicurezza per il reflow. Vedere /integrations/artisan/production-usage/ per capire perché esiste questo margine e quando sovrascriverlo.

Che cosa si ottiene

Proprietà	Comportamento
Testo	Selezionabile e ricercabile (testo vettoriale, non rasterizzato)
CSS	Layout di Chrome — flexbox, grid, selettori complessi, web font tramite URI data
Rete	Nessun recupero di sottorisorse; gli URL remoti non vengono caricati (vedere /integrations/artisan/security-and-operations/)
Pagine	Importa la pagina 0 dell’output di Chrome

Casi limite e insidie

• L’HTML vuoto non comporta alcuna operazione. writeHtmlChrome('') restituisce il documento invariato (verificato in HasTextOutput::writeHtmlChrome).
• Nessuna pagina presente. Se non è presente alcuna pagina, writeHtmlChrome() ne aggiunge una prima del rendering.
• Le risorse remote non vengono caricate. <img src="https://..."> risulta vuoto. Incorporare le risorse come URI data:. Si tratta dell’impostazione di isolamento di rete, non di un bug. Vedere /integrations/artisan/security-and-operations/.
• Bridge mancante. Se nextpdf/artisan non è installato, il core solleva un’eccezione di layout anziché un errore fatale.

Prestazioni

La prima chiamata include il costo dell’avvio di Chrome, oltre a quello del layout. Le chiamate successive riutilizzano il processo Chrome attivo tramite BrowserPool. Per worker batch o processi a esecuzione prolungata, consultare le indicazioni sul ciclo di vita e sulle risorse nella pagina /integrations/artisan/production-usage/.

Note sulla sicurezza

L’avvio rapido utilizza HTML attendibile e definito direttamente nel codice. Prima di passare a writeHtmlChrome() qualsiasi HTML influenzato dall’utente, leggere /integrations/artisan/security-and-operations/. Il bridge isola l’accesso alla rete, ma il rendering dell’HTML presenta comunque una superficie di attacco.

Contesto commerciale

Questo flusso produce un PDF a partire dall’HTML utilizzando il bridge open source. Per incorporare nello stesso documento un XML di fattura elettronica conforme, il piano Premium Pro fornisce un embedder. Il percorso open source non è influenzato dall’assenza di Premium.

Vedere anche

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