Guía para desarrollar con Artisan

De un vistazo

El paquete Artisan tiene dos responsabilidades relacionadas: renderizar HTML mediante Chrome e importar el PDF resultante como página en un documento NextPDF. Al depurar, trata por separado los límites de Chrome, del parser y del importador.

Usa esta guía al escribir integraciones del renderer, workers de larga duración, diagnósticos del parser o pruebas en torno a nextpdf/artisan.

Límites de la arquitectura

Capa	Propiedad de	Responsabilidad	No pongas aquí
Aplicación	Aplicación	Autoriza la generación de HTML y elige la configuración del renderer.	Gestión del proceso del navegador.
Política de HTML	Aplicación y paquete	Rechaza el HTML inseguro o de tamaño excesivo antes de renderizar.	Autorización de inquilinos o decisiones de negocio.
Renderer de Chrome	`nextpdf/artisan`	Renderiza HTML a un PDF independiente producido por Chrome.	Reparación general de PDF o edición arbitraria de PDF.
Parser/importador	`nextpdf/artisan`	Analiza el PDF renderizado e importa una página como un XObject de formulario.	Validación completa de conformidad de PDF.
Motor central	`nextpdf/nextpdf`	Coloca los objetos de formulario importados y escribe el documento final.	Ciclo de vida de Chrome CDP.

Ciclo de vida en tiempo de ejecución

Etapa	Comportamiento	Acción del desarrollador
Creación de configuración	`ChromeRendererConfig` define el comportamiento del binario, el tiempo de espera, el CSS, el tamaño de entrada y el sandbox.	Usa una configuración específica del entorno en lugar de suposiciones fijas en tiempo de ejecución.
Creación del renderer	`ChromeHtmlRenderer` posee un `BrowserPool`.	Reutiliza el renderer dentro de un worker y ciérralo durante el apagado.
Validación de HTML	La política de seguridad comprueba el tamaño y envuelve el documento con el CSS predeterminado.	Valida la autorización del invocador antes de esta etapa.
Impresión de Chrome	CDP renderiza un PDF independiente.	Mantén bloqueados los recursos externos a menos que una política revisada los permita.
Análisis de PDF	`PdfReader::parse()` lee los datos de xref, las páginas, los objetos, los recursos y las revisiones.	Trata los fallos del parser como fallos de renderizado, salvo que el objetivo sea el diagnóstico.
Importación de página	`PageImporter::import()` extrae el contenido de la página, la media box, los recursos y los objetos incrustados.	Importa la página `0` salvo que el flujo de trabajo elija deliberadamente otra página.

Estructura recomendada de la aplicación

Ruta	Propósito
`app/Pdf/Renderers/*`	Envoltorio de la aplicación alrededor de `ChromeHtmlRenderer`.
`app/Pdf/Templates/*`	Renderizado de plantillas HTML y mapeo de DTO a la vista.
`app/Pdf/Policies/*`	Política de renderizado para el tamaño de HTML, los recursos y los inquilinos.
`tests/Pdf/Renderer/*`	Pruebas de humo del renderer con fixtures de HTML pequeños.
`tests/Pdf/Parser/*`	Fixtures del parser para la salida importada de Chrome.

Mantén el renderizado de plantillas separado del renderizado del navegador. El renderer debe recibir el HTML final y un ancho de página conocido.

<?php

use NextPDF\Artisan\ChromeHtmlRenderer;
use NextPDF\Artisan\ChromeRendererConfig;
use NextPDF\Artisan\PageImporter;
use NextPDF\Parser\PdfReader;

$renderer = new ChromeHtmlRenderer(new ChromeRendererConfig(
    renderTimeout: 30,
    maxHtmlSize: 1_000_000,
));

$result = $renderer->render($html, widthPt: 595.28);

$reader = new PdfReader($result->getPdfData());
$reader->parse();

$form = (new PageImporter())->import($reader);

Patrón del renderer

Crea un renderer por proceso de worker o por ámbito de solicitud. Reutilizar el renderer evita el coste repetido de iniciar Chrome. Cerrarlo de forma explícita evita fugas de procesos durante el apagado del worker.

<?php

final class InvoiceChromeRenderer
{
    public function __construct(
        private readonly ChromeHtmlRenderer $renderer,
    ) {}

    public function renderInvoice(string $html): string
    {
        return $this->renderer
            ->render($html, widthPt: 595.28)
            ->getPdfData();
    }

    public function close(): void
    {
        $this->renderer->close();
    }
}

Patrón de diagnóstico del parser

Las API del parser son útiles cuando la salida de Chrome no se importa correctamente. Mantén los diagnósticos en modo de solo lectura y evita mutar el estado del parser después de una importación correcta.

Pregunta de diagnóstico	API que se debe usar	Señal esperada
¿El archivo se analiza?	`PdfReader::parse()`	Lanza una excepción ante una estructura de PDF no válida.
¿Existe la página `0`?	`PdfReader::getPage(0)`	Devuelve un `PdfObject`.
¿Hay contenido?	`PdfReader::getPageContentStream($page)`	Stream de contenido con datos.
¿Existen recursos?	`PdfReader::getPageResources($page)`	Array del diccionario de recursos.
¿Hay revisiones incrementales?	`PdfReader::getRevisionCount()`	Recuento mayor que uno.
¿Qué objeto falló?	`PdfTokenizer::getOffset()` y el contexto de la excepción del parser.	Desplazamiento en bytes para reducir el fixture.

Puntos de extensión

Punto de extensión	Úsalo para	Restricción
`ChromeRendererConfig::fromArray()`	Mapeo de configuración del framework.	Los valores opcionales desconocidos o mal escritos usan los valores predeterminados.
`HtmlSecurityPolicyInterface`	Política de HTML en la capa del parser.	No sustituye los controles de transporte, de proceso ni de autorización.
`LoggerInterface`	Diagnósticos de renderizado y del navegador.	No registres el contenido HTML de forma predeterminada.
`BrowserPool`	Reutilización de un proceso de Chrome de larga duración.	Debe cerrarse al apagar el worker.
`PageImporter`	Incrustar una página externa ya analizada.	El reader debe analizarse primero.
Clases del parser	Diagnósticos y salida importada de Chrome.	No es un kit de herramientas general de reparación de PDF.

Flujo de trabajo de desarrollo

Reproduce el fragmento de HTML en una prueba de renderizado mínima.
Valida maxHtmlSize, el CSS predeterminado y la ruta del binario de Chrome.
Renderiza con un ancho fijo en puntos.
Analiza los bytes del PDF devuelto con PdfReader::parse().
Importa la página 0, salvo que el flujo de trabajo elija deliberadamente otra página.
Añade pruebas con fixtures para el HTML más pequeño que reproduzca cada fallo.
Cierra el renderer en los hooks de apagado del worker.

Gestión de fallos

Fallo	Dónde debería gestionarse	Respuesta recomendada
Falta el binario de Chrome	Comprobación del despliegue y ruta de construcción del renderer.	Haz fallar la comprobación de disponibilidad antes de aceptar tráfico de renderizado.
HTML de tamaño excesivo	Política de HTML.	Recházalo antes de iniciar Chrome.
Tiempo de espera del navegador agotado	Límite del renderer.	Haz fallar el renderizado y registra el nombre de la plantilla, el tamaño, el ancho y el tiempo de espera.
Fallo del parser	Límite de importación.	Almacena un fixture pequeño y saneado para depurar cuando la política lo permita.
Fuga de proceso del navegador	Ciclo de vida del worker.	Ciérralo al apagar y reinícialo tras un número controlado de renderizados.

Valores predeterminados seguros

Aspecto	Predeterminado	Cuándo anularlo
Tiempo de espera de renderizado	`30` segundos.	Auméntalo solo para documentos medidos y acotados.
Tamaño máximo de HTML	`5,000,000` bytes.	Redúcelo para endpoints públicos.
Sandbox	Habilitado.	Desactívalo solo cuando las restricciones del contenedor lo requieran y el host esté aislado.
Alto	Automático cuando `heightPt <= 0`.	Usa un alto fijo para contratos de diseño estrictos.
Recursos externos	Bloqueados por la política del renderer.	Permítelos solo a través de una política de recursos revisada.

Lista de verificación de pruebas

Las pruebas de renderizado cubren HTML y CSS representativos.
Las pruebas de seguridad cubren el HTML de tamaño excesivo y los intentos de recursos bloqueados.
Las pruebas de importación verifican que el objeto de formulario devuelto tenga contenido, media box y recursos.
Las pruebas del parser cubren la tabla xref, el stream xref, el stream de objetos y los casos de fixtures malformados.
Las pruebas del worker llaman a close() y verifican que no quede ningún proceso del navegador.
Las pruebas de rendimiento registran el tiempo de renderizado por plantilla y tamaño de contenido.