Recursos Avançados

Além da renderização básica de HTML para PDF, o pacote Artisan fornece utilitários para mesclar documentos, injetar estilos globais, capturar screenshots e ajustar o comportamento do Chrome.

Mesclagem de PDFs

A classe PdfMerger combina múltiplas fontes HTML em um único documento PDF. Cada fonte é renderizada como uma seção separada, e os resultados são concatenados em ordem.

use Yeeefang\TcpdfNext\Artisan\PdfMerger;
use Yeeefang\TcpdfNext\Artisan\RenderOptions;

$merger = PdfMerger::create();

$merger
    ->addHtml('<h1>Cover Page</h1><p>Annual Report 2026</p>')
    ->addFile('/templates/chapter-1.html')
    ->addFile('/templates/chapter-2.html')
    ->addUrl('https://charts.example.com/annual-summary')
    ->addHtml('<h1>Appendix</h1><p>Supporting data tables.</p>');

$merger->save('/reports/annual-2026.pdf');

Options por Seção

Cada seção pode ter suas próprias RenderOptions. Por exemplo, uma capa em paisagem e capítulos em retrato.

$coverOptions = RenderOptions::create()
    ->setPageSize('A4')
    ->setLandscape(true)
    ->setPrintBackground(true);

$chapterOptions = RenderOptions::create()
    ->setPageSize('A4')
    ->setLandscape(false)
    ->setDisplayHeaderFooter(true)
    ->setFooterTemplate('
        <div style="font-size: 8px; text-align: center; width: 100%; color: #888;">
            Page <span class="pageNumber"></span>
        </div>
    ');

PdfMerger::create()
    ->addHtml('<h1>Cover</h1>', options: $coverOptions)
    ->addFile('/templates/chapter-1.html', options: $chapterOptions)
    ->addFile('/templates/chapter-2.html', options: $chapterOptions)
    ->save('/reports/merged.pdf');

Injeção de CSS

A classe StyleInjector prepende regras CSS à página renderizada. Isso é útil para aplicar uma folha de estilo global da marca a templates que você não controla.

use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;
use Yeeefang\TcpdfNext\Artisan\StyleInjector;

$injector = StyleInjector::create()
    ->addCss('
        body {
            font-family: "Inter", "Noto Sans TC", sans-serif;
            font-size: 11pt;
            line-height: 1.6;
            color: #333;
        }
        h1 { color: #1a237e; }
    ')
    ->addCssFile('/styles/brand.css');

HtmlRenderer::create()
    ->loadFile('/templates/report.html')
    ->withStyleInjector($injector)
    ->save('/output/branded-report.pdf');

Múltiplas Camadas de Estilo

Estilos são injetados na ordem em que são adicionados. Regras posteriores substituem as anteriores, seguindo a especificidade CSS padrão.

$injector = StyleInjector::create()
    ->addCssFile('/styles/reset.css')
    ->addCssFile('/styles/brand.css')
    ->addCss('table { page-break-inside: avoid; }');  // overrides

Screenshots

A classe ScreenshotCapture renderiza HTML para formatos de imagem em vez de PDF. Útil para gerar thumbnails, previews de redes sociais ou testes de regressão visual.

use Yeeefang\TcpdfNext\Artisan\ScreenshotCapture;

// Full page screenshot as PNG
ScreenshotCapture::create()
    ->loadHtml('<h1>Preview</h1><p>This will be a PNG image.</p>')
    ->fullPage(true)
    ->format('png')
    ->save('/output/preview.png');

JPEG com Qualidade

ScreenshotCapture::create()
    ->loadUrl('https://example.com/dashboard')
    ->format('jpeg')
    ->quality(85)
    ->save('/output/dashboard.jpg');

Configuração de Viewport

ScreenshotCapture::create()
    ->loadFile('/templates/email.html')
    ->viewport(width: 1200, height: 800)
    ->deviceScaleFactor(2)  // retina
    ->fullPage(false)
    ->save('/output/email-preview.png');

Configuração do Chrome

Caminho do Binário Personalizado

O Artisan detecta automaticamente o Chrome em caminhos comuns do SO. Substitua com chromePath.

use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;

$renderer = HtmlRenderer::create(
    chromePath: '/opt/google/chrome/chrome',
);

Ou defina a variável de ambiente CHROME_PATH globalmente.

Flags do Modo Headless

O Artisan passa --headless=new por padrão (Chrome 112+). Você pode adicionar flags extras para ambientes específicos.

$renderer = HtmlRenderer::create(
    chromeFlags: [
        '--no-sandbox',            // required in Docker
        '--disable-gpu',           // recommended in Docker
        '--disable-dev-shm-usage', // avoid /dev/shm issues
        '--font-render-hinting=none',
    ],
);

Connection Pooling

Para cenários de alta vazão, reutilize uma única instância do Chrome em múltiplas renderizações. Isso elimina o custo de inicialização (aproximadamente 300--500 ms) para cada renderização subsequente.

use Yeeefang\TcpdfNext\Artisan\ChromeBridge;
use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;

// Create a persistent bridge
$bridge = ChromeBridge::create(chromePath: '/usr/bin/chromium');

// Reuse across multiple renders
foreach ($reports as $report) {
    HtmlRenderer::createWithBridge($bridge)
        ->loadHtml($report->html)
        ->save("/output/{$report->id}.pdf");
}

// Explicitly close when done
$bridge->close();

Tratamento de Erros

Todas as exceções do Artisan estendem Yeeefang\TcpdfNext\Artisan\Exceptions\ArtisanException.

use Yeeefang\TcpdfNext\Artisan\Exceptions\RenderException;
use Yeeefang\TcpdfNext\Artisan\Exceptions\ChromeNotFoundException;
use Yeeefang\TcpdfNext\Artisan\Exceptions\TimeoutException;

try {
    HtmlRenderer::create()->loadUrl($url)->save($path);
} catch (ChromeNotFoundException $e) {
    // Install Chrome or set CHROME_PATH
} catch (TimeoutException $e) {
    // Increase timeout or check network
} catch (RenderException $e) {
    // Inspect $e->getMessage() for details
}

Exceção	Causa Comum
ChromeNotFoundException	Chrome não instalado, CHROME_PATH incorreto
TimeoutException	Página lenta, promises JS não resolvidas, problemas de rede
RenderException	HTML inválido, crash do Chrome, falha de gravação no disco

Dicas de Performance

1. Reutilize instâncias do Chrome -- Use ChromeBridge para operações em lote.
2. Minimize JavaScript -- Quanto menos JS o Chrome precisar executar, mais rápida a renderização.
3. Inline CSS crítico -- Evite buscar folhas de estilo externas quando possível.
4. Defina um timeout rigoroso -- Falhe rápido em páginas quebradas em vez de bloquear a fila.
5. Use setPrintBackground(false) -- Pule a renderização de fundo quando não precisar.

Próximos Passos

• Render Options -- Tamanho de página, margens e templates de cabeçalho/rodapé.
• Configuração Docker -- Executando o Artisan em ambientes containerizados.
• Visão Geral -- Resumo do pacote e instalação.