Pacchetto Artisan

Artisan · LGPL-3.0

Il pacchetto Artisan (yeeefang/tcpdf-next-artisan) fornisce conversione HTML-to-PDF pixel-perfect alimentata da Chrome DevTools Protocol (CDP). Renderizza HTML con supporto CSS3 completo -- inclusi Flexbox, Grid, web font, media query e animazioni congelate al momento del rendering.

Quando Usare Artisan

Scenario	Raccomandato
Generare PDF da template HTML/CSS	Artisan
Costruzione PDF programmatica (celle, disegno)	Core
Email HTML ad archivio PDF	Artisan
Fattura da dati strutturati	Core o Artisan
Layout CSS complessi (Grid, Flexbox)	Artisan
PDF firmati/criptati	Core

Come Funziona

Artisan avvia un'istanza Chrome headless tramite Chrome DevTools Protocol, carica il tuo contenuto HTML in una pagina browser e usa la funzionalità print-to-PDF integrata di Chrome. Questo significa che ogni funzionalità CSS supportata da Chrome è disponibile per i tuoi PDF -- non più lotta con parser CSS limitati.

HTML/CSS --> ChromeBridge --> Chrome CDP --> Binario PDF --> salva / stream

Installazione

bash

composer require yeeefang/tcpdf-next-artisan

Requisiti:

PHP 8.2+
chrome-php/chrome ^1.15 (installato automaticamente)
Browser Chrome o Chromium installato sull'host

bash

# Ubuntu/Debian
apt-get install -y chromium-browser

# macOS
brew install --cask chromium

# Windows (Chocolatey)
choco install googlechrome

# Imposta percorso personalizzato tramite variabile ambiente
export CHROME_PATH=/usr/bin/google-chrome

Avvio Rapido

php

use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;

$renderer = HtmlRenderer::create();

$renderer
    ->loadHtml('<h1>Ciao, Mondo!</h1><p>Renderizzato con Chrome CDP.</p>')
    ->save('/output/hello.pdf');

Da un URL

php

HtmlRenderer::create()
    ->loadUrl('https://example.com/report')
    ->save('/output/report.pdf');

Da un File

php

HtmlRenderer::create()
    ->loadFile('/templates/invoice.html')
    ->save('/output/invoice.pdf');

Contenuti Pacchetto

Classe	Scopo
`HtmlRenderer`	Entry point principale -- carica HTML, configura, renderizza
`ChromeBridge`	Comunicazione Chrome DevTools Protocol
`RenderOptions`	Configurazione rendering (margini, scala, header)
`PageSetup`	Dimensione pagina e orientamento per rendering
`PdfMerger`	Unisce pagine renderizzate multiple in un singolo PDF
`StyleInjector`	Inietta fogli stile CSS prima del rendering
`ScreenshotCapture`	Cattura screenshot pagina (PNG/JPEG)

Gerarchia Eccezioni

Eccezione	Quando
`RenderException`	Fallimento rendering generico
`ChromeNotFoundException`	Binario Chrome non trovato al percorso atteso
`TimeoutException`	Caricamento pagina o rendering ha superato timeout configurato

Tutte le eccezioni risiedono sotto il namespace Yeeefang\TcpdfNext\Artisan\Exceptions ed estendono una classe base comune ArtisanException.

Confronto con Core HTML Parser

Il pacchetto Core include un modulo HtmlParser per conversione HTML-to-PDF base. Usalo quando hai bisogno di una soluzione senza dipendenze. Usa Artisan quando hai bisogno di fedeltà rendering browser completa.

Funzionalità	Core HtmlParser	Artisan
Dipendenza esterna	Nessuna	Chrome/Chromium
CSS Flexbox / Grid	No	Sì
Web font (`@font-face`)	No	Sì
Media query	No	Sì
Esecuzione JavaScript	No	Sì
Regole CSS `@page`	No	Sì
Performance (doc semplici)	Più veloce	Più lento
Performance (CSS complesso)	N/A	Affidabile

Prossimi Passi

HTML Renderer -- Caricamento e rendering contenuto HTML.
Render Options -- Configurazione dimensione pagina, margini, header e footer.
Funzionalità Avanzate -- Unione PDF, iniezione CSS, screenshot.
Setup Docker -- Eseguire Artisan in container.

Pacchetto Artisan ​

Quando Usare Artisan ​

Come Funziona ​

Installazione ​

Avvio Rapido ​

Da un URL ​

Da un File ​

Contenuti Pacchetto ​

Gerarchia Eccezioni ​

Confronto con Core HTML Parser ​

Prossimi Passi ​