Contratos / Documento

De un vistazo

El dominio de documentos reúne los contratos sobre los que se construyen los PDF: PdfDocumentInterface para el contenido, DocumentFactoryInterface para la creación segura en workers, los contratos de los registros de fuentes e imágenes y los tres enums de entrega y disposición. Todos son stable desde 1.0.0 o 1.7.0.

Instalación

composer require nextpdf/core:^3

Visión general conceptual

PdfDocumentInterface es la superficie principal de la API. Define la gestión de páginas, la selección de fuentes, la disposición de texto en celdas y en modo multicelda, el renderizado de HTML, la incrustación de imágenes y la salida final. Cada método devuelve static, por lo que las llamadas pueden encadenarse. Document::createStandalone() devuelve una instancia concreta que satisface la interfaz. Declarar el tipo de la interfaz en los servicios propios mantiene intercambiables los detalles internos del motor.

La creación de documentos tiene dos rutas. En una solicitud clásica de PHP-FPM, createStandalone() construye un documento autocontenido con registros privados. Un worker de larga ejecución usa la otra ruta; esto incluye RoadRunner, Swoole y Laravel Octane. En ese caso, DocumentFactoryInterface::create() devuelve un Document nuevo y desechable. El documento lee de registros con vida útil del proceso, pero nunca los modifica. La fábrica conserva los singletons FontRegistryInterface e ImageRegistryInterface. Cada documento obtiene su propio contexto de renderizado y su propio writer. Esto proporciona contención de fallos: un documento no puede corromper el estado compartido del que depende otro documento.

Los contratos de los registros explican por qué un worker se mantiene rápido. FontRegistryInterface analiza un archivo de fuente una sola vez y almacena en caché los metadatos analizados durante toda la vida útil del proceso. Puede bloquearse después del calentamiento, de modo que el tráfico de producción no pueda modificarlo. ImageRegistryInterface almacena en caché los datos binarios de las imágenes decodificadas bajo una política acotada de uso menos reciente. Los metadatos de la imagen permanecen residentes incluso después de expulsar el binario. Ambos exponen memoryUsage() para la planificación de capacidad. ImageRegistryInterface extiende ResettableService. Ese contrato expulsa los datos en caché sin destruir los metadatos estructurales. Un worker puede descartar las cachés de imágenes bajo presión de memoria y seguir atendiendo solicitudes.

Tres enums completan el dominio. OutputDestination selecciona la visualización en línea, la descarga forzada, la escritura en el sistema de archivos o la devolución de la cadena sin procesar. Orientation selecciona vertical u horizontal. Alignment selecciona texto a la izquierda, centrado, a la derecha o justificado. Cada enum usa el código TCPDF heredado como valor de sus casos. Por eso el puente compat-tcpdf puede mapearse de forma limpia. La garantía de retrocompatibilidad para estos enums es aditiva. No se elimina ningún caso. Pueden añadirse nuevos casos en una versión menor.

Superficie de la API

Tipo	Clase	Miembros clave	Estabilidad	Desde
`PdfDocumentInterface`	interface	`addPage()`, `setMargins()`, `setFont()`, `cell()`, `multiCell()`, `writeHtml()`, `image()`, `output()`, `save()`	stable	1.0.0
`DocumentFactoryInterface`	interface	`create(?Config): Document`	stable	1.7.0
`ResettableService`	interface	`reset(): void`	stable	1.7.0
`FontRegistryInterface`	interface	`register()`, `get()`, `warmup()`, `lock()`, `isLocked()`, `registerFromBinary()`, `memoryUsage()`	stable	1.7.0
`ImageRegistryInterface`	interface	`load()`, `loadFromString()`, `getMetadata()`, `memoryUsage()` (extiende `ResettableService`)	stable	2.0.0
`OutputDestination`	enum (string)	`Inline`, `Download`, `File`, `String`	stable	1.0.0
`Orientation`	enum (string)	`Portrait`, `Landscape`	stable	1.0.0
`Alignment`	enum (string)	`Left`, `Center`, `Right`, `Justify`	stable	1.0.0

FontRegistryInterface e ImageRegistryInterface están documentadas íntegramente en la página de tipografía; la página del documento cubre su función en el ciclo de vida de creación.

Ejemplo de código — Inicio rápido

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Hello World');
$doc->addPage();
$doc->setFont('helvetica', '', 24);
$doc->cell(0, 15, 'Hello, NextPDF!', newLine: true);
$doc->setFont('helvetica', '', 12);
$doc->cell(0, 10, 'This is a minimal PDF generated with NextPDF.', newLine: true);
$doc->save(__DIR__ . '/output/01-hello-world.pdf');

Ejemplo de código — Producción

<?php

declare(strict_types=1);

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

use NextPDF\Core\PdfFactory;
use NextPDF\ValueObjects\{Margin, PageSize};

$factory = PdfFactory::new()
    ->withPageSize(PageSize::A4())
    ->withMargins(new Margin(15.0, 15.0, 15.0, 15.0))
    ->withCompress(true)
    ->withLang('en');

// The same configured factory creates independent documents.
$doc = $factory->create();
$doc->setTitle('PdfFactory Example');
$doc->setAuthor('NextPDF');
$doc->addPage();
$doc->setFont('helvetica', '', 16);
$doc->cell(0, 12, 'Created via PdfFactory', newLine: true);

$doc2 = $factory->create();
$doc2->addPage();
$doc2->setFont('helvetica', '', 12);
$doc2->cell(0, 10, 'Second document from the same factory.');

$doc->save(__DIR__ . '/output/02-pdf-factory.pdf');

PdfFactory es el builder inmutable; cada with*() devuelve una instancia nueva. Compone internamente un DocumentFactoryInterface, de modo que el modelo de registros para workers descrito en la visión general se aplica sin cableado adicional.

Casos límite y trampas

createStandalone() construye registros privados. En un bucle de worker, eso reanaliza cada fuente en cada solicitud. Usar DocumentFactoryInterface con registros compartidos en su lugar.
Un Document es desechable por diseño. Reutilizar una sola instancia entre documentos lógicos filtra estado. Llamar a create() por cada documento y dejar que la recolección de basura lo recupere.
FontRegistryInterface::lock() hace que register(), addFontDirectory() y warmup() lancen LogicException. Bloquear después del calentamiento, nunca durante el procesamiento de la solicitud.
OutputDestination::File escribe en el sistema de archivos del servidor y devuelve los bytes en bruto. save() es la ruta explícita para archivos. No mezclar ambas para el mismo documento.
cell() acepta bool|string para el argumento de borde por compatibilidad con TCPDF; una cadena vacía no es lo mismo que false. Pasar el valor tipado que realmente se quiere expresar.

Rendimiento

Los registros de fuentes e imágenes convierten el dominio de documentos en un sistema con memoria acotada, en lugar de un sistema por solicitud. El análisis de fuentes de la primera solicitud domina el costo. El performance_budget es de 1500 ms de tiempo total y 64 MB de pico en tres documentos del ejemplo de worker. Casi todo ese presupuesto corresponde al primer análisis de fuente. Después del calentamiento, el trabajo atribuible al contrato por documento es O(1): una búsqueda en el registro y una asignación de contexto. memoryUsage() en cualquiera de los registros devuelve un MemoryReport para la planificación de capacidad en tiempo de ejecución. ResettableService::reset() acota la memoria pico bajo carga sostenida.

Notas de seguridad

Los contratos de documentos no exponen superficie criptográfica, pero hay dos riesgos operativos aplicables. Primero, image() acepta una ruta o una URL. Cuando la entrada no es confiable, restringir la obtención remota mediante ExternalResourcePolicyInterface (consulta la página de política de seguridad) en lugar de pasar directamente URL controladas por el usuario. Segundo, writeHtml() es el punto de entrada del pipeline HTML. El marcado no confiable debe pasar por una HtmlSecurityPolicyInterface antes del renderizado. La propia capa de documentos no realiza saneamiento. Ese es el trabajo del dominio de política de seguridad, y el contrato permite suministrar una política más estricta sin hacer un fork.

Conformidad

Los contratos de documentos implementan la estructura de documento PDF 2.0 tal como se define en ISO 32000-2. El manejo de salida, páginas y fuentes produce objetos indirectos y un flujo de referencias cruzadas según ISO 32000-2 §7. El contenido se emite a través de la capa del writer según el contrato de la capa del motor (ADR-010). En esta página no se afirma ninguna declaración a nivel de cláusula más allá de la conformidad estructural. La conformidad con PDF/A y PDF/UA se documenta en las páginas de extracción y accesibilidad, que llevan las tablas normativas.

Véase también

Contratos: 41 interfaces públicas (SPI) — la visión general de la SPI y los niveles de estabilidad.
Contratos / Tipografía — FontRegistryInterface documentado por completo.
Contratos / Política de seguridad — las políticas que controlan writeHtml() e image().
Núcleo — las clases concretas Document y PdfFactory.
Documento — el módulo de construcción de documentos.
Writer — la capa que emite los objetos PDF para estos contratos.