Cómo dejar de luchar con la generación de PDF en Laravel

Generar documentos PDF en la web siempre ha sido todo un desafío. Piensa en cuántas veces has intentado diseñar la factura o el informe perfecto, solo para descubrir que las fuentes se desplazaron, las tablas se desalinearon o las imágenes desaparecieron por completo. Por lo general, la elección se reduce a utilidades de sistema complejas como wkhtmltopdf, que requieren configuración del servidor, y servicios en la nube de pago.

Si estás trabajando con el stack de Laravel, existe una solución probada en el tiempo — el paquete laravel-dompdf de Barry van den Heuvel. Es un wrapper alrededor de la librería Dompdf que toma tu familiar plantilla Blade y la convierte en un archivo PDF. Sin dependencias adicionales en el servidor, solo PHP.

Qué hay bajo el capó

El proyecto esencialmente hace una cosa: conecta el poder de Laravel con el motor Dompdf. La característica principal es que no necesitas aprender una nueva sintaxis para el diseño de documentos. Creas una View regular, le pasas datos, y el paquete maneja la renderización.

Curiosamente, el paquete soporta no solo Laravel estándar sino también Lumen. Esto es útil si estás extrayendo la generación de documentos a un microservicio separado.

Cómo funciona en la práctica

La instalación es estándar a través de Composer:

composer require barryvdh/laravel-dompdf

Después de eso, obtienes acceso al facade Pdf. El ejemplo más simple de crear un archivo se ve así:

use Barryvdh\DomPDF\Facade\Pdf;

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

El método loadView toma tu archivo Blade, le pasa variables y genera un objeto que puedes inmediatamente enviar al usuario para descarga o simplemente mostrar en el navegador a través de stream().

Configuración flexible de páginas

A menudo necesitas cambiar la orientación de la página o el formato del papel directamente en el código. Por ejemplo, la orientación horizontal funciona mejor para tablas anchas:

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

Por cierto, si necesitas guardar el archivo en disco en lugar de servirlo al usuario, el método save() lo hará en una sola acción.

Soporte PDF/А-3b y facturas electrónicas

Las versiones recientes (3.x) añadieron soporte para el estándar PDF/А-3b. Esto es crítico para el archivo de documentos a largo plazo. Pero hay un detalle: este estándar requiere que todas las fuentes estén embebidas en el archivo. Helvetica o Times estándar no funcionarán — necesitarás usar algo como DejaVu Sans.

Para quienes trabajan en automatización contable, el paquete ahora soporta los formatos Zugferd y Factur-X. Esto es cuando un archivo XML con datos de factura se embebe directamente en el PDF. Se ve algo así:

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

Algunos consejos de maquetación

Dompdf no es un motor de navegador completo. Maneja bien CSS 2.1 y algunas propiedades de CSS 3, pero no intentes usar Flexbox o Grid ahí. Las buenas y viejas tablas y floats son tu mejor apuesta.

Dos cosas que te ahorrarán mucho tiempo:

1. Siempre especifica la codificación en tu plantilla: <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>. Sin esto, el cirílico se convertirá en signos de interrogación.
2. Para saltos de página, usa la propiedad CSS page-break-after: always. Esta es la forma más confiable de hacer que la impresora comience una nueva hoja donde la necesitas.

¿Vale la pena usarlo

laravel- dompdf es un trabajador incansable. Es perfecto para generar documentos de complejidad simple a media: facturas, informes de servicio, estados de cuenta simples.

La principal ventaja es la simplicidad. No necesitas instalar Node.js, Puppeteer, ni configurar binarios del servidor. Todo funciona out of the box en hosting PHP estándar.

Sin embargo, si necesitas renderizar gráficos complejos de JavaScript o tu diseño está cargado de trucos modernos de CSS, Dompdf puede tener dificultades. En tales casos, es mejor mirar herramientas basadas en Chromium. Pero para el 90% de las tareas de un desarrollador backend, este paquete es más que suficiente.

El proyecto está vivo y se mantiene activamente (más de 7,000 estrellas en GitHub) y es respaldado por uno de los contribuidores más conocidos de la comunidad Laravel. Si aún no lo has probado — ahora es el momento de guardarlo en tus marcadores.