Como Parar de Sofrer com Geração de PDF no Laravel

Gerar documentos PDF na web sempre foi um grande desafio. Pense em quantas vezes você tentou criar o layout perfeito para uma fatura ou relatório, apenas para descobrir que as fontes mudaram, as tabelas ficaram desalinhadas ou as imagens desapareceram completamente. Geralmente a escolha fica entre utilitários complexos de sistema como wkhtmltopdf, que exigem configuração do servidor, e serviços pagos em nuvem.

Se você está trabalhando com o stack Laravel, existe uma solução testada pelo tempo — o pacote laravel-dompdf de Barry van den Heuvel. É um wrapper em torno da biblioteca Dompdf que pega seu template Blade familiar e o converte em um arquivo PDF. Sem dependências extras de servidor, apenas PHP.

O que está por baixo do capô

O projeto essencialmente faz uma coisa: conecta o poder do Laravel com o motor Dompdf. A principal característica é que você não precisa aprender uma nova sintaxe para layout de documentos. Você cria uma View comum, passa dados para ela, e o pacote cuida da renderização.

Curiosamente, o pacote suporta não apenas o Laravel padrão, mas também o Lumen. Isso é útil se você estiver extraindo a geração de documentos para um microsserviço separado.

Como funciona na prática

A instalação é padrão via Composer:

composer require barryvdh/laravel-dompdf

Depois disso, você tem acesso à fachada Pdf. O exemplo mais simples de criar um arquivo fica assim:

use Barryvdh\DomPDF\Facade\Pdf;

$pdf = Pdf::loadView('emails.invoice', ['order' => $order]);
return $pdf->download('invoice.pdf');

O método loadView pega seu arquivo Blade, passa variáveis para ele e gera um objeto que você pode imediatamente enviar para o usuário para download ou apenas exibir no navegador via stream().

Configuração flexível de páginas

Muitas vezes você precisa mudar a orientação da página ou o formato do papel diretamente no código. Por exemplo, orientação paisagem funciona melhor para tabelas largas:

Pdf::loadHTML($html)
    ->setPaper('a4', 'landscape')
    ->setWarnings(false)
    ->save('report.pdf');

A propósito, se você precisar salvar o arquivo em disco em vez de servir ao usuário, o método save() fará isso em uma única ação.

Suporte a PDF/A-3b e faturas eletrônicas

As versões recentes (3.x) adicionaram suporte ao padrão PDF/A-3b. Isso é crítico para arquivamento de documentos a longo prazo. Mas há um detalhe: este padrão requer que todas as fontes sejam incorporadas no arquivo. Helvetica ou Times padrão não funcionam — você precisará usar algo como DejaVu Sans.

Para quem trabalha com automação contábil, o pacote agora suporta os formatos Zugferd e Factur-X. É quando um arquivo XML com dados da fatura é incorporado diretamente no PDF. Fica algo assim:

$pdf = Pdf::loadView('invoice', $data)->setPdfA();

// Добавляем метаданные для Factur-X
$pdf->setAdditionalXmpRdf($xmlMetadata);

// Прикрепляем сам XML
$pdf->addEmbeddedFile(
    storage_path('invoices/factur-x.xml'),
    'factur-x.xml',
    'Factur-X Invoice',
    'text/xml'
);

Algumas dicas de layout

Dompdf não é um motor de navegador completo. Ele lida bem com CSS 2.1 e algumas propriedades de CSS 3, mas não tente usar Flexbox ou Grid lá. Tabelas e floats bons e velhos são sua melhor aposta.

Duas coisas que vão te economizar muito tempo:

1. Sempre especifique o encoding no seu template: <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>. Sem isso, o Cirílico vai virar pontos de interrogação.
2. Para quebras de página, use a propriedade CSS page-break-after: always. Essa é a forma mais confiável de fazer a impressora começar uma nova folha onde você precisa.

Vale a pena usar

laravel-dompdf é um cavalo de batalha. É perfeito para gerar documentos de complexidade simples a média: faturas, relatórios de serviços, extratos simples.

A principal vantagem é a simplicidade. Você não precisa instalar Node.js, Puppeteer ou configurar binários do servidor. Tudo funciona de cara em hospedagem PHP padrão.

No entanto, se você precisa renderizar gráficos JavaScript complexos ou seu layout é pesado com truques modernos de CSS, o Dompdf pode ter dificuldades. Nesses casos, é melhor olhar para ferramentas baseadas em Chromium. Mas para 90% das tarefas de um desenvolvedor backend, este pacote é mais do que suficiente.

O projeto está vivo e é ativamente mantido (mais de 7.000 estrelas no GitHub) e é apoiado por um dos contribuidores mais conhecidos da comunidade Laravel. Se você ainda não experimentou — agora é a hora de marcá-lo.