Inicio rápido con Artisan

De un vistazo

Asocia un ChromeRendererConfig a un documento de NextPDF, llama a writeHtmlChrome() y guarda el resultado. Chrome renderiza el HTML, el puente importa el resultado como un Form XObject y el texto permanece seleccionable.

Descripción conceptual

writeHtmlChrome() es un método del Document del núcleo de NextPDF proporcionado por el concern HasTextOutput. El método valida la entrada, resuelve el renderer de Artisan, envía el HTML a Chrome, analiza el PDF devuelto e incrusta la página 0 como un Form XObject en la posición actual del cursor. La firma pública es writeHtmlChrome(string $html, ?float $width = null, ?float $height = null): static, verificada contra nextpdf/coresrc/Core/Concerns/HasTextOutput.php.

Ejemplo de código — Inicio rápido

quickstart.php

<?php

declare(strict_types=1);

use NextPDF\Core\Document;
use NextPDF\Artisan\ChromeRendererConfig;

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

$config = new ChromeRendererConfig(
    chromeBinaryPath: '/usr/bin/chromium',
);

$doc = Document::createStandalone();
$doc->setChromeRendererConfig($config);
$doc->addPage();

$doc->writeHtmlChrome('
    <div style="display: flex; gap: 20px; font-family: sans-serif;">
        <div style="flex: 1; background: #f0f0f0; padding: 24px;">
            <h2>Revenue</h2><p style="font-size: 2em; color: #2563eb;">$124,500</p>
        </div>
        <div style="flex: 1; background: #f0f0f0; padding: 24px;">
            <h2>Orders</h2><p style="font-size: 2em; color: #16a34a;">1,847</p>
        </div>
    </div>
');

$doc->save('/tmp/report.pdf');

Este es el flujo canónico que muestra el README.md del paquete. Chrome se encarga del layout flex. Los números permanecen como texto seleccionable en la salida, porque la página se incrusta como un Form XObject y no como una imagen rasterizada.

Tamaño de página personalizado

Pasa un ancho y un alto explícitos en puntos PDF para ajustarse a una página fija (se muestra A4):

$doc->writeHtmlChrome($html, width: 595.28, height: 841.89);

Cuando se proporcionan ambos valores, Chrome imprime exactamente con ese tamaño de papel. Cuando se omite el alto (o se pasa null), el puente se ajusta automáticamente al alto medido del contenido y añade un pequeño margen de seguridad para el reflujo. Consulta /integrations/artisan/production-usage/ para saber por qué existe ese margen y cuándo conviene anularlo.

Lo que obtienes

Propiedad	Comportamiento
Texto	Seleccionable y apto para búsqueda (texto vectorial, no rasterizado)
CSS	Layout de Chrome — flexbox, grid, selectores complejos, fuentes web mediante URI de datos
Red	Sin descargas de subrecursos; las URL remotas no se cargan (consulta /integrations/artisan/security-and-operations/)
Páginas	Se importa la página 0 de la salida de Chrome

Casos límite y trampas

• El HTML vacío no hace nada. writeHtmlChrome('') devuelve el documento sin cambios (verificado en HasTextOutput::writeHtmlChrome).
• Todavía no hay ninguna página. Si no existe ninguna página, writeHtmlChrome() añade una antes de renderizar.
• Los recursos remotos no se cargan. <img src="https://..."> se renderiza vacío. Incluye los recursos en línea como URI data:. Esta es la postura de aislamiento de red, no un fallo. Consulta /integrations/artisan/security-and-operations/.
• Falta el puente. Si nextpdf/artisan no está instalado, el núcleo lanza una excepción de layout en lugar de un error fatal.

Rendimiento

La primera llamada asume el coste de iniciar Chrome y del layout. Las llamadas posteriores reutilizan el proceso de Chrome activo mediante BrowserPool. Para procesos por lotes o workers de larga ejecución, lee la guía de ciclo de vida y recursos en la página /integrations/artisan/production-usage/.

Notas de seguridad

El inicio rápido usa HTML de confianza y definido de forma fija. Antes de pasar cualquier HTML influido por el usuario a writeHtmlChrome(), lee /integrations/artisan/security-and-operations/. El puente aísla el acceso a la red, pero el renderizado de HTML sigue teniendo superficie de amenaza.

Contexto comercial

Esto produce un PDF a partir de HTML mediante el puente de código abierto. Para incrustar un XML de factura electrónica conforme en el mismo documento, el nivel Premium Pro proporciona un incrustador. La ruta de código abierto no se ve afectada cuando Premium está ausente.

Consulta también

• /integrations/artisan/install/
• /integrations/artisan/configuration/
• /integrations/artisan/production-usage/
• /integrations/artisan/troubleshooting/
• /integrations/artisan/security-and-operations/