HTML a PDF, la vía sencilla

Hasta ahora, en esta ruta se han creado páginas una llamada cada vez. Muchos documentos resultan más rápidos de describir como marcado, el formato de texto basado en etiquetas que se usa en las páginas web. En este tutorial se le entrega a NextPDF algo de lenguaje de marcado de hipertexto (HTML) y el motor se encarga de dibujar la página.

Lo que se va a construir

Un informe de una página renderizado a partir de una sola cadena HTML. Tiene un encabezado de color, un párrafo breve y una tabla con una fila de totales. Se aplica el estilo con hojas de estilo en cascada (CSS), el lenguaje de reglas que controla la apariencia del marcado. En los tutoriales anteriores se usó la interfaz de programación de aplicaciones (API) fluida, las llamadas encadenadas a métodos. Aquí, en cambio, se describe el diseño mediante marcado y el mismo motor lo renderiza.

Paso 1: Renderizar un informe con estilo a partir de HTML

Crear un archivo llamado 01-html.php en la carpeta del proyecto, junto a vendor. Pegar en él este script completo:

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Monthly reading report');
$document->addPage();

$html = <<<'HTML'
<h1 style="color: #1E3A8A;">Monthly reading report</h1>

<p>This report was rendered from <strong>HTML</strong> with inline
<em>CSS</em>. The table below lists two books and their page counts.</p>

<table border="1" cellpadding="5" cellspacing="0" style="width: 100%;">
    <thead>
        <tr style="background-color: #1E3A8A; color: #FFFFFF;">
            <th style="width: 55%;">Title</th>
            <th style="width: 20%; text-align: center;">Format</th>
            <th style="width: 25%; text-align: right;">Pages</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>The Paper Trail</td>
            <td style="text-align: center;">Hardcover</td>
            <td style="text-align: right;">312</td>
        </tr>
        <tr style="background-color: #F8FAFC;">
            <td>Ink and Bytes</td>
            <td style="text-align: center;">Paperback</td>
            <td style="text-align: right;">248</td>
        </tr>
    </tbody>
    <tfoot>
        <tr style="font-weight: bold;">
            <td colspan="2" style="text-align: right;">Total pages:</td>
            <td style="text-align: right;">560</td>
        </tr>
    </tfoot>
</table>
HTML;

$document->writeHtml($html);

$document->save(__DIR__ . '/out/reading-report.pdf');

echo "Wrote out/reading-report.pdf\n";

Ejecutar el script desde la carpeta del proyecto:

php 01-html.php

Debería aparecer una sola línea de salida:

Wrote out/reading-report.pdf

Abrir out/reading-report.pdf en cualquier visor de formato de documento portátil (PDF). El encabezado es de color azul oscuro y la fila de cabecera de la tabla está rellena de ese mismo color.

Qué acaba de ocurrir

@mkdir(__DIR__ . '/out'); crea la carpeta de salida. El signo @ oculta la advertencia cuando la carpeta ya existe, de modo que las ejecuciones repetidas no generan ruido.
Document::createStandalone(), setTitle() y addPage() funcionan exactamente igual que en los tutoriales anteriores. Cambiar al marcado no altera nada de la configuración del documento.
writeHtml() lee la cadena una sola vez, de arriba abajo, y dibuja cada elemento en la posición actual. Los encabezados y los párrafos se convierten en texto con estilo. La tabla se convierte en filas medidas de celdas con borde.
Los atributos style en línea llevan el CSS. El motor entiende propiedades habituales como color, background-color, text-align y width.
No interviene ningún navegador ni software adicional. La canalización es PHP puro dentro del motor, de modo que el script se ejecuta allí donde funcione la instalación de Composer.

El motor admite un subconjunto práctico de HTML y CSS, no todo lo que acepta un navegador. Cualquier cosa fuera de ese subconjunto se omite en silencio en lugar de generar un error. La matriz de compatibilidad de CSS registra exactamente qué se cubre. Para un recorrido más detallado por esta canalización, consultar Renderizar HTML en una página PDF.

Cuándo usar HTML y cuándo usar la API fluida

Ambas rutas se ejecutan sobre el mismo motor, así que conviene elegir la que mejor se ajuste al documento.

Elegir writeHtml() cuando el documento se lee como una página web: encabezados, párrafos, listas y tablas. El marcado es más rápido de escribir y más fácil de editar para los compañeros de equipo.
Elegir la API fluida cuando se necesita una colocación exacta, como posiciones fijas o celdas medidas con precisión. El marcado aporta flujo; las llamadas fluidas aportan control.
Comprobar la matriz de compatibilidad de CSS antes de depender de una propiedad. Cuando un estilo no está cubierto, construir esa parte con llamadas fluidas en su lugar.

El límite de seguridad

El HTML real a menudo procede de fuera del código, por ejemplo de un formulario o de una base de datos. Conviene tratarlo como entrada no confiable y validarlo o depurarlo antes de renderizarlo. De forma predeterminada, la canalización integrada no ejecuta ningún script ni obtiene recursos remotos. Ese valor predeterminado mantiene conservador el renderizador aunque el marcado no lo sea. Si se necesitan opciones de renderizado de nivel de navegador, consultar Elegir tu ruta.

Si algo salió mal

Failed to open stream: No such file or directory suele significar que el script no encuentra vendor/autoload.php. Ejecutarlo desde la carpeta donde se ejecutó Composer.
Un estilo que falta suele ser una propiedad fuera del subconjunto compatible. El motor omite lo que no admite en lugar de fallar. Comparar el marcado con la matriz de compatibilidad de CSS.
Una excepción durante el renderizado nombra el problema exacto. Buscarlo en la referencia de errores de renderizado y de entrada/salida.

Para cualquier otra cosa, empezar por la guía de resolución de problemas.

Ahora ya se pueden construir documentos llamada por llamada y a partir de marcado. Terminar la ruta con Adónde ir a continuación. Esta página traza el recetario, la referencia y las guías que se usarán después de esta ruta.