Por qué tu motor de PDF pertenece a PHP, no a un sidecar

Spec: ISO/IEC 25010:2023, §3.7Spec: ISO 32000-2, §7

De un vistazo

Hay dos lugares donde se puede crear un PDF: dentro de tu proceso de PHP, o en algún otro sitio que tienes que operar. NextPDF lo crea dentro. Esta página es el argumento de esa decisión: por qué un motor en proceso suele ser la opción predeterminada correcta, y qué cuesta en realidad el patrón del «otro sitio» una vez que está en producción.

Este es el ángulo de la arquitectura, no el del framework. Cómo el mismo motor llega a Laravel, Symfony, CodeIgniter y al código independiente es otra historia, contada en un motor, todos los frameworks.

Por qué esto importa

Una función de PDF rara vez empieza como un sistema que operas. Empieza como una línea en un controlador: representa esta factura, devuelve aquel informe. El patrón sidecar convierte esa línea en infraestructura. Para dibujar el documento ahora ejecutas una segunda cosa —un binario externo, un navegador sin interfaz, un microservicio aparte— y todo lo que esa segunda cosa necesita pasa a ser tu problema también: su versión, su memoria, su contenedor, su red, sus modos de fallo, su aviso de guardia a las 2 de la madrugada.

El costo es invisible en la demostración e inevitable en producción. Un motor de documentos que vive en tu proceso no tiene nada de eso. La pregunta no es «¿puede un sidecar crear un PDF?»: por supuesto que puede. Es «¿a qué te comprometiste a operar para llegar ahí, y lo necesitabas?».

La versión breve

En proceso significa que no hay un segundo entorno de ejecución. NextPDF dibuja el PDF dentro del mismo trabajador de PHP que atendió la petición. No hay ningún subproceso que generar, ningún servicio que desplegar y nada extra que mantener vivo.
Un sidecar añade una superficie operativa que no tenías. Un navegador empaquetado o un binario externo trae su propia versión, su propia huella de seguridad y su propio contenedor, todo lo cual ahora parcheas y monitorizas.
Los límites de proceso son donde las cosas salen mal. Los arranques en frío, los tiempos de espera agotados, la fontanería frágil entre procesos y los datos que abandonan tu proceso son modos de fallo que una llamada en proceso simplemente no tiene.
En proceso es comprobable y determinista. El motor es PHP tipado que puedes probar con pruebas unitarias, simular y razonar, no un representador opaco que solo puedes sondear ejecutándolo y mirando la salida.
Un navegador real sigue teniendo usos reales. Para la representación fiel al píxel de páginas web modernas arbitrarias, un navegador sin interfaz es la herramienta honesta, y NextPDF puede delegar en uno deliberadamente. Es una costura, no la opción predeterminada.

Cómo lo aborda NextPDF

Pon las dos arquitecturas una al lado de la otra. La ruta en proceso es una llamada de función. La ruta sidecar es un sistema distribuido en miniatura, y cada flecha entre sus cajas es un lugar que falla con independencia de tu código.

In-process: call the enginewriteHtml() or the document API runs inside the current PHP worker — no subprocess, no socket.
In-process: receive PDF bytesThe engine returns native PDF content directly; nothing left the process.
Sidecar: serialize and shipMarkup or a request is marshalled out of your process to a binary, browser, or remote service.
Sidecar: cross the boundaryA process spawn or network hop — with a cold start, a timeout, and an IPC contract that can break.
Sidecar: run a second runtimeAn external renderer with its own version, memory profile, and security surface to operate and patch.
Sidecar: deserialize backMarshal the result back in and translate the renderer’s errors into yours.

La ruta en proceso frente a la ruta sidecar. En proceso, el PDF lo produce una llamada tipada dentro del mismo trabajador de PHP y se devuelve directamente. La ruta sidecar añade un paso de serialización, un límite de proceso o de red, un entorno de ejecución externo con su propia versión y huella, y un paso de deserialización de vuelta, cada uno un modo de fallo distinto que la llamada en proceso no tiene.

Ningún segundo entorno de ejecución que operar. El patrón sidecar son dos sistemas vestidos con el disfraz de una sola función. Un wkhtmltopdf empaquetado, un servicio de Chromium sin interfaz, un microservicio de representación aparte: cada uno es un entorno de ejecución con su propia cadencia de publicación y sus propios errores. Lo heredas todo. El motor en proceso se distribuye como una dependencia de Composer; se actualiza igual que cualquier otra biblioteca de tu composer.json, sin añadir ningún demonio, imagen ni socket a tu despliegue.

Desviación de versiones y una superficie de seguridad más amplia. Un navegador empaquetado es una base de código grande y de evolución rápida con un flujo constante de avisos de seguridad. Fíjalo y se pudre; síguelo y se agita. En cualquier caso, es toda la plataforma web de un representador metida en tu cadena de suministro para alimentar un solo documento. Un motor de PHP en proceso es una biblioteca de código enfocada que puedes leer; su superficie de seguridad es el PHP que ya ejecutas, no una segunda plataforma que ahora ejecutas también.

Los datos se quedan dentro del límite de tu proceso. Cuando delegas a un proceso externo, el contenido del documento —que a menudo es exactamente el dato sensible que un PDF existe para transportar— cruza un límite. Se escribe en una tubería, un argumento, un archivo temporal o un socket de red hacia un servicio. Cada uno de esos es un lugar donde filtrarse, registrarse por accidente o quedar abandonado. En proceso, los datos nunca abandonan al trabajador que los posee. El radio de impacto es un proceso, no una flota.

Fontanería frágil, arranques en frío y tiempos de espera. Las llamadas entre procesos y de red fallan de maneras que una llamada de función no puede: el subproceso que no arrancó, el socket que se colgó, el tiempo de espera que calculaste mal, el arranque en frío bajo un pico de tráfico. Cada uno necesita una política de reintentos, un cortacircuitos y un presupuesto. Una representación en proceso o devuelve bytes o lanza una excepción tipada que capturas en la línea siguiente. No hay un estado de red parcial que reconciliar.

La observabilidad y las pruebas se vuelven más difíciles al cruzar el límite. Un fallo en un sidecar llega como un código de salida, una línea de registro truncada o un 500 de un servicio que no controlas. Reproducirlo significa reproducir todo ese entorno. Un motor en proceso es observable con las herramientas que ya usas —una traza de pila, un depurador, un perfilador— y es comprobable igual que el resto de tu PHP. Esa comprobabilidad es una propiedad de calidad del software con nombre propio: ISO/IEC 25010 la sitúa bajo mantenibilidad (Spec: ISO/IEC 25010:2023, §3.7), y una biblioteca en proceso la satisface de forma mucho más directa que un representador que solo puedes ejercitar lanzándolo.

El PDF sobre el que se afirman esas pruebas es una estructura definida, no una caja negra. Un archivo PDF tiene una distribución de objetos y de archivo especificada (Spec: ISO 32000-2, §7), y un motor en proceso emite esa estructura a partir de código que puedes leer, de modo que una prueba de archivo de referencia (golden) o estructural verifica bytes que produjo una función conocida, en lugar de la salida de un programa externo que solo puedes observar.

Ejemplo práctico

Todo el quid cabe en un puñado de líneas. No hay cliente, ni URL base, ni comprobación de estado, ni política de reintentos, porque no hay un segundo sistema.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

// The engine runs inside this very process. No subprocess is spawned,
// no socket is opened, and the report data never leaves the worker.
$document = Document::createStandalone();
$document->setTitle('Quarterly Report');
$document->addPage();

$html = <<<'HTML'
<h1 style="color: #1E3A8A;">Quarterly Report</h1>
<p>Rendered <strong>in-process</strong> by PHP — no browser, no sidecar.</p>
HTML;

$document->writeHtml($html);

// PDF bytes are returned directly. There is no boundary to marshal across,
// so there is no timeout, cold start, or deserialization step to handle.
$bytes = $document->getPdfData();

Contrasta la forma de la versión sidecar —no su código, su forma operativa. Necesita que un binario o un servicio esté instalado y accesible, una petición serializada y enviada, un tiempo de espera elegido, una ruta de fallo para cuando el representador esté frío o caído, y el resultado devuelto y deserializado. Nada de eso está en el fragmento de arriba, porque nada de eso existe cuando el motor es una biblioteca.

Concepto erróneo habitual

La suposición frecuente es que la representación «de verdad» de PDF tiene que significar un navegador, así que en proceso debe de ser la versión de juguete. Eso tiene la disyuntiva al revés. Un navegador es la herramienta correcta cuando necesitas una representación exacta y fiel al píxel de contenido web moderno arbitrario. Es la opción predeterminada incorrecta para el trabajo con forma de documento que la mayoría de los equipos hace en realidad —facturas, informes, extractos, contratos— donde la maquetación es conocida, los datos son tuyos y la correctitud la comprueba un validador, no el ojo. Para ese trabajo, el peso operativo de un sidecar no te aporta nada que el motor en proceso no te dé ya, y te cuesta todo lo de las secciones anteriores.

El concepto erróneo espejo es el que esta página tiene cuidado de no cometer: afirmar que un motor en proceso representa «toda la web» como un navegador. No lo hace, y NextPDF no finge que lo haga. Su canalización de HTML en proceso es un subconjunto alineado con la especificación, centrado en la maquetación de documentos, con fronteras documentadas: el alcance honesto se expone en la canalización de HTML. Cuando genuinamente necesitas fidelidad completa de navegador, eso es una delegación deliberada y voluntaria, no una alternativa silenciosa.

Límites y fronteras

En proceso es la opción predeterminada correcta. No es una afirmación universal de que un subproceso nunca esté justificado. Donde un documento genuinamente requiere una representación exacta de CSS moderno arbitrario que el motor en proceso no cubre, delegar en un navegador sin interfaz es la decisión correcta, y NextPDF admite esa ruta deliberadamente, con su acceso a la red restringido, como una costura en lugar de la opción predeterminada. Los dos no son rivales; son herramientas distintas para trabajos distintos.

Esta página argumenta la arquitectura, no una matriz de compatibilidad de CSS. Exactamente qué HTML y CSS cubre la canalización en proceso lo definen el código del motor y sus pruebas de conformidad, y se documenta junto con esa canalización, no se promete aquí. «En proceso» describe la ruta de representación predeterminada; no es una afirmación de que toda ruta posible evite un subproceso.

La superficie de capacidades se mantiene simple: el motor en proceso es Core, y la ruta de delegación al navegador es una extensión opcional, independiente de la edición.

Where the PDF is rendered — edition availability
Edition	Availability
Core	Core representa el PDF en proceso en PHP, sin subproceso, binario ni sidecar de forma predeterminada.
Pro	La ruta de delegación al navegador sin interfaz es una extensión complementaria opcional, independiente del nivel de edición.
Enterprise	La ruta de delegación al navegador sin interfaz es una extensión complementaria opcional, independiente del nivel de edición.

Documentos relacionados

La canalización de HTML: el alcance honesto del motor en proceso, y exactamente cuándo delegar en un navegador es lo correcto.
Un motor, todos los frameworks: el eje complementario: cómo el mismo motor en proceso llega a todos los frameworks de PHP sin una biblioteca distinta por pila.
Operar NextPDF en producción: cómo es ejecutar un motor en proceso en el día a día, sin ningún entorno de ejecución extra que operar.
Memoria y streaming: cómo el motor mantiene acotada la generación en proceso bajo carga.

Glosario

Generación en proceso: producir el PDF dentro del mismo trabajador de PHP que atiende la petición, sin ningún subproceso, socket o servicio externo.
Sidecar: un entorno de ejecución aparte que se ejecuta junto a tu aplicación para hacer una sola tarea; aquí, un binario externo, un navegador sin interfaz o un microservicio que representa el PDF fuera de tu proceso.
Arranque en frío: la latencia y el pico de recursos que se incurren cuando un subproceso o servicio debe arrancar desde cero antes de poder atender la primera petición.
IPC: comunicación entre procesos: las tuberías, sockets, archivos temporales o llamadas de red que se usan para pasar datos hacia y desde un proceso aparte, y una fuente recurrente de fallos frágiles y difíciles de depurar.
Costura de delegación al navegador: la ruta opcional y voluntaria que entrega una representación a un navegador sin interfaz para una fidelidad exacta, con el acceso de red a subrecursos bloqueado; una decisión deliberada, no la opción predeterminada.