Pacote Artisan

Artisan · LGPL-3.0

O pacote Artisan (yeeefang/tcpdf-next-artisan) fornece conversão pixel-perfect de HTML para PDF alimentada pelo Chrome DevTools Protocol (CDP). Ele renderiza HTML com suporte completo a CSS3 -- incluindo Flexbox, Grid, web fonts, media queries e animações congeladas no momento da renderização.

Quando Usar o Artisan

Cenário	Recomendado
Gerar PDF a partir de templates HTML/CSS	Artisan
Construção programática de PDF (cells, desenho)	Core
Emails HTML para arquivo PDF	Artisan
Fatura a partir de dados estruturados	Core ou Artisan
Layouts CSS complexos (Grid, Flexbox)	Artisan
PDFs assinados/criptografados	Core

Como Funciona

O Artisan inicia uma instância headless do Chrome via Chrome DevTools Protocol, carrega seu conteúdo HTML em uma página do navegador e usa a funcionalidade nativa de impressão para PDF do Chrome. Isso significa que todo recurso CSS que o Chrome suporta está disponível para seus PDFs -- sem mais lutas com parsers CSS limitados.

HTML/CSS --> ChromeBridge --> Chrome CDP --> PDF binary --> save / stream

Instalação

composer require yeeefang/tcpdf-next-artisan

Requisitos:

• PHP 8.2+
• chrome-php/chrome ^1.15 (instalado automaticamente)
• Navegador Chrome ou Chromium instalado no host

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

# macOS
brew install --cask chromium

# Windows (Chocolatey)
choco install googlechrome

# Set a custom path via environment variable
export CHROME_PATH=/usr/bin/google-chrome

Início Rápido

use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;

$renderer = HtmlRenderer::create();

$renderer
    ->loadHtml('<h1>Hello, World!</h1><p>Rendered with Chrome CDP.</p>')
    ->save('/output/hello.pdf');

A Partir de uma URL

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

A Partir de um Arquivo

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

Conteúdo do Pacote

Classe	Finalidade
HtmlRenderer	Ponto de entrada principal -- carregar HTML, configurar, renderizar
ChromeBridge	Comunicação via Chrome DevTools Protocol
RenderOptions	Configuração de renderização (margens, escala, cabeçalhos)
PageSetup	Tamanho de página e orientação para renderização
PdfMerger	Mesclar múltiplas páginas renderizadas em um único PDF
StyleInjector	Injetar folhas de estilo CSS antes da renderização
ScreenshotCapture	Capturar screenshots da página (PNG/JPEG)

Hierarquia de Exceções

Exceção	Quando
RenderException	Falha genérica de renderização
ChromeNotFoundException	Binário do Chrome não encontrado no caminho esperado
TimeoutException	Carregamento da página ou renderização excedeu o timeout configurado

Todas as exceções residem no namespace Yeeefang\TcpdfNext\Artisan\Exceptions e estendem uma classe base comum ArtisanException.

Comparação com o HTML Parser do Core

O pacote Core inclui um módulo HtmlParser para conversão básica de HTML para PDF. Use-o quando precisar de uma solução sem dependências. Use o Artisan quando precisar de fidelidade total de renderização do navegador.

Recurso	Core HtmlParser	Artisan
Dependência externa	Nenhuma	Chrome/Chromium
CSS Flexbox / Grid	Não	Sim
Web fonts (@font-face)	Não	Sim
Media queries	Não	Sim
Execução de JavaScript	Não	Sim
Regras CSS @page	Não	Sim
Performance (docs simples)	Mais rápido	Mais lento
Performance (CSS complexo)	N/A	Confiável

Próximos Passos

• HTML Renderer -- Carregando e renderizando conteúdo HTML.
• Render Options -- Configurando tamanho de página, margens, cabeçalhos e rodapés.
• Recursos Avançados -- Mesclagem de PDFs, injeção de CSS, screenshots.
• Configuração Docker -- Executando o Artisan em containers.