El modelo de canalización

Spec Spec: ISO 32000-2, §7.5 ISO 32000-2 §7.5 Evidence { } Code-backed Evidence: Code-backed

De un vistazo

Un documento de NextPDF no se produce en un solo paso opaco. Avanza a través de un pequeño número de etapas explícitas: una fachada que registra la intención, una capa de contenido que convierte esa intención en un modelo y un escritor que serializa ese modelo en un PDF conforme. Esta página explica esa forma y por qué adopta esta estructura.

Por qué esto importa

El propio formato de archivo PDF es una estructura por capas —una cabecera, un cuerpo de objetos, una tabla de referencias cruzadas y un tráiler— y un escritor tiene que ensamblarlo todo de forma coherente. Si el motor que lo construye es un procedimiento único y enmarañado, cada cambio pone en riesgo toda salida. Entonces, la única manera de ganar confianza es representar documentos enteros e inspeccionarlos visualmente, lo que resulta lento, tardío y poco convincente.

Una canalización explícita invierte esa situación. Cada etapa tiene una sola función y un límite tipado, de modo que se puede razonar sobre un cambio y probarlo en la etapa a la que afecta, no solo al final del archivo. La arquitectura es, ante todo, una decisión para facilitar las pruebas y la extensibilidad.

La versión breve

• El punto de entrada público es una fachada Document. Es un constructor fluido, de un solo uso y seguro para workers que registra qué se quiere, no cómo se serializa.
• La fachada delega en aproximadamente dos docenas de traits de responsabilidad específicos (salida de texto, dibujo, páginas, seguridad, navegación, etc.): una responsabilidad cada uno, no una sola clase gigante.
• El contenido llega por una de dos rutas: dibujo directo (primitivas gráficas) o el motor HTML/CSS. Ambas producen el mismo modelo de documento interno.
• Un escritor de PDF dedicado serializa ese modelo y elige una estrategia PDF 1.4 / 1.7 / 2.0. La producción de una estructura de archivo válida reside aquí y en ningún otro lugar.
• El estado de larga duración (los registros de fuentes e imágenes) tiene alcance de proceso y se comparte; el estado por solicitud (el documento) se crea de cero y nunca se reutiliza. El límite es explícito; eso es lo que hace que los entornos de ejecución de workers sean seguros.

Cómo lo aborda NextPDF

La forma más clara de ver el modelo es seguir un documento desde la llamada hasta los bytes finales.

1. Document facade Fluent, use-once builder; records intent via concern traits.
2. Content production Direct drawing or the HTML/CSS engine — both build one document model.
3. Document model Accumulated pages, content, and resources held as typed state.
4. PDF writer Serialises the model; selects a PDF 1.4 / 1.7 / 2.0 strategy.
5. Conforming PDF Header, object body, cross-reference table, trailer.

El recorrido de un documento a través de NextPDF: cada etapa tiene una responsabilidad y un límite tipado, de modo que se puede razonar sobre ella y probarla de forma aislada.

Dos decisiones de diseño hacen que esto sea algo más que un diagrama.

La fachada está compuesta, no es monolítica. Document no implementa cada característica por sí misma; delega cada área en un trait de responsabilidad dedicado: salida de texto, dibujo, páginas, seguridad, tipografía, navegación, transacciones, etc. Un nuevo método de documento pertenece al trait propietario de su área, no a la fachada en sí. La clase invocada se mantiene pequeña y las responsabilidades se mantienen separadas.

El escritor es propietario exclusivo de la estructura del archivo. La producción de contenido decide qué marcas y objetos existen; el escritor decide cómo se convierten en un archivo PDF válido, incluida la estrategia de versión que se aplica. Esa separación se impone como una regla arquitectónica: el código de diseño y de contenido no emite la estructura final del archivo, y el escritor no toma decisiones de diseño. La ventaja es que «¿es la salida un PDF válido?» tiene un único lugar donde probarse.

El límite de ciclo de vida es parte del modelo, no una idea añadida a posteriori. Los registros de fuentes e imágenes viven durante todo el ciclo de vida del proceso y se comparten entre solicitudes; el documento, su contexto de renderizado y el escritor se crean por solicitud y se desechan. En un entorno de ejecución de workers, esa distinción marca la diferencia entre la reutilización segura y la corrupción entre solicitudes. Por esa razón se explicita en la arquitectura, no se deja a la disciplina.

Qué dice la evidencia

Esta página cuenta con Evidence { } Code-backed Evidence: Code-backed . Las etapas se corresponden con una estructura real en el repositorio core:

• La fachada y su delegación son src/Core/Document.php junto con los traits de responsabilidad en src/Core/Concerns/ (salida de texto, salida, dibujo, páginas, seguridad, tipografía, navegación, transacciones y más, cada uno con una sola responsabilidad).
• Las dos rutas de contenido son el motor HTML/CSS (src/Html/) y el dibujo directo (src/Graphics/), y ambas alimentan el modelo interno.
• La serialización y la estrategia de versión de PDF residen en src/Writer/ (PdfWriter.php, con clases de estrategia PDF 1.4 / 1.7 / 2.0 explícitas).
• El límite entre el ciclo de vida del proceso y el de cada solicitud es el diseño seguro para workers registrado en la descripción general de la arquitectura y ejercitado por el ejemplo incluido de fábrica de workers, que comparte un FontRegistry y un ImageRegistry entre solicitudes mientras crea de cero cada Document.

El formato fija el destino. La salida del escritor debe ser una cabecera, un cuerpo de objetos, una tabla de referencias cruzadas y un tráiler según Spec Spec: ISO 32000-2, §7.5 ISO 32000-2 §7.5 . Concentrar esa obligación en una sola etapa es lo que permite que el resto del motor se mantenga centrado en el contenido, en lugar de centrarse en ensamblar la estructura del archivo.

Ejemplo práctico

La función de la fachada consiste en hacer que la intención se lea como intención. La ruta de contenido y el escritor quedan invisibles en el punto de llamada:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();   // facade
$doc->setTitle('Quarterly Report');    // metadata concern
$doc->addPage();                       // pages concern
$doc->setFont('helvetica', 'B', 16);   // typography concern
$doc->cell(0, 12, 'Summary', newLine: true); // text-output concern
$doc->writeHtml('<p>Generated in-process.</p>'); // HTML content path
$doc->save(__DIR__ . '/report.pdf');   // writer stage

Cada llamada llega a una responsabilidad diferente. Dos rutas de contenido diferentes alimentan el mismo modelo. Exactamente una etapa —save()— convierte el modelo en bytes del archivo. Nada en el punto de llamada necesita saber cómo se construye la tabla de referencias cruzadas.

Error común

Una interpretación errónea frecuente es que «canalización» implica una API de envío en flujo que se conecta etapa por etapa, como una tubería de Unix. No es así. La canalización aquí es una descomposición arquitectónica: etapas con una sola responsabilidad y límites tipados. Se sigue programando mediante una fachada fluida. Las etapas son la forma en que el motor se construye y se prueba, no un transporte que se ensambla a mano.

Otro error relacionado es suponer que la fachada es el motor. Es el punto de entrada. El trabajo real se distribuye entre los traits de responsabilidad, dos rutas de contenido y un escritor. Esa distribución es precisamente la razón por la que cambiar una característica no pone en riesgo cada salida.

Human-factors note: Human-factors note

La misma secuencia de cinco etapas se usa en el diagrama, en la versión breve, en la evidencia y en el ejemplo, de forma deliberada. Una estructura coherente que el lector encuentra una vez y luego reconoce en todas partes reduce el esfuerzo para seguir la página. Esto refleja por qué el propio motor mantiene los límites de las etapas fijos y reducidos en lugar de numerosos y cambiantes.

Límites y fronteras

Esta página describe la forma de la canalización, no la API interna de una etapa concreta. El inventario exacto de traits de responsabilidad, las reglas de selección de estrategia del escritor y los campos del modelo de contenido los definen el código y la referencia, no esta explicación. El número preciso de traits es un detalle de implementación que puede cambiar sin cambiar el modelo. Esta página no cubre las etapas internas del motor HTML (un tema aparte) ni el comportamiento de flujo y memoria del escritor (también aparte). Las afirmaciones estructurales son exactas a la fecha de revisión de esta página; la fuente autoritativa son los src/Core/, src/Html/, src/Graphics/ y src/Writer/ del repositorio core.

El modelo de canalización es idéntico en todas las ediciones; las ediciones añaden capacidades dentro de las etapas, no nuevas etapas:

Pipeline model — edition availability

Edition	Availability
Core	○ Core implementa la canalización completa fachada → contenido → escritor.
Pro	○ Pro añade capacidades dentro de las etapas existentes, no nuevas etapas.
Enterprise	○ Enterprise añade capacidades dentro de las etapas existentes, no nuevas etapas.

Documentos relacionados

• Memoria y flujo — cómo la etapa del escritor mantiene acotada la memoria.
• La canalización HTML — las etapas internas de la ruta de contenido HTML.
• Tipos estrictos, en todas partes — los límites tipados que permiten probar cada etapa de forma independiente.

Glosario

• Fachada — el punto de entrada público Document: un constructor fluido y de un solo uso que registra la intención y delega en traits de responsabilidad.
• Trait de responsabilidad — un trait de PHP específico que la fachada compone, cada uno propietario de una sola área funcional (salida de texto, dibujo, páginas, seguridad, etc.).
• Ruta de contenido — una de las dos formas en que el contenido entra en el modelo: el dibujo directo o el motor HTML/CSS.
• Modelo de documento — la acumulación interna y tipada de páginas, contenido y recursos que mantiene el motor antes de la serialización.
• Etapa del escritor — el componente que serializa el modelo en un PDF válido, seleccionando una estrategia PDF 1.4 / 1.7 / 2.0.
• Seguro para workers — diseñado de modo que el estado de tiempo de vida del proceso se comparte de forma segura mientras que el estado por solicitud se crea de cero y nunca se reutiliza.