Linearización: salida para Fast Web View

En resumen

Un PDF linealizado —Fast Web View— está organizado para que un lector pueda mostrar la primera página antes de recibir el resto del archivo. Los objetos de la primera página, su subsección de referencias cruzadas y una tabla de pistas que localiza todas las demás páginas se ubican cerca del inicio del archivo. NextPDF emite esta disposición de forma determinista: el mismo documento produce los mismos bytes en cualquier host y el resultado pasa qpdf --check-linearization.

La linealización es una funcionalidad del núcleo. Se activa en el Document; el motor se encarga del diseño de tres pasadas, del diccionario de parámetros de linealización y de la tabla de pistas. En el lado de lectura, LinearizationView analiza el diccionario de linealización de un archivo finalizado para que un transporte pueda planificar la entrega sin reimplementar el formato.

Instalación

composer require nextpdf/core:^3

Descripción conceptual

Un PDF estándar sitúa la tabla de referencias cruzadas justo al final, por lo que un lector debe descargar el final del archivo antes de poder resolver cualquier objeto. Un PDF linealizado reordena el archivo en dos partes. La primera contiene el diccionario de parámetros de linealización, la primera página y la tabla de pistas con desplazamientos de página. La segunda contiene las páginas restantes. Un lector compatible con Fast Web View puede representar la primera página a partir de la primera parte y luego usar la tabla de pistas para saltar directamente a cualquier página posterior a medida que siguen llegando los bytes: ISO 32000-2 Annex F.

NextPDF incluye dos backends. El backend predeterminado v2 es un linealizador de tres pasadas que produce una salida ISO 32000-2 Annex F con una tabla de pistas con desplazamientos de página conforme y una longitud /L que equivale a la longitud exacta en bytes del archivo. Se conserva un backend heredado v1 por compatibilidad de bytes con documentos producidos antes de v2; emite parámetros Annex F no conformes y solo se usa de forma opcional. Para trabajo nuevo, debería usarse el predeterminado.

El determinismo es una garantía estricta. El identificador del archivo se deriva del resumen del contenido, no de una fuente aleatoria, de modo que enableLinearization() es una función pura del documento. Esto permite que las pruebas de bytes golden fijen la salida y hace posible una caché direccionada por contenido o un ETag estable más adelante.

Activar la linealización

examples/linearization/enable.php

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$document = Document::createStandalone();
$document->writeHtml('<h1>Quarterly report</h1>');
$document->enableLinearization();

// Deterministic: the same document always produces the same bytes.
$pdf = $document->output();

El backend predeterminado es v2. Para optar por el backend heredado v1, se llama primero a useLegacyLinearizer() (cualquier orden funciona):

$document->useLegacyLinearizer();
$document->enableLinearization();

Desde la configuración

También puede activarse de forma declarativa mediante Config. El ajuste se aplica al construir el documento, lo que conviene a las canalizaciones que fijan de antemano el formato de entrega en lugar de llamar a un método en cada documento:

use NextPDF\Core\Config;
use NextPDF\Core\Document;

$config   = (new Config())->withLinearization();
$document = Document::createStandalone($config);
$document->writeHtml('<h1>Quarterly report</h1>');

$pdf = $document->output(); // linearized output

withLinearization() está desactivado de forma predeterminada, como las demás opciones de Config. Pasar false permite hacer explícita esa decisión. Un documento construido de esta forma pasa por la misma ruta de enableLinearization(), así que las protecciones de conformidad descritas más abajo se aplican de forma idéntica.

Interacciones de conformidad

La linealización se combina con los perfiles de etiquetado y de archivo, pero es mutuamente excluyente con las funcionalidades que invalidarían la tabla de pistas inicial o una firma por rangos de bytes.

Funcionalidad	Interacción
PDF/A, PDF/UA	Pueden combinarse. v2 conserva la numeración de objetos, así que las referencias de estructura y etiquetas siguen siendo válidas.
Cifrado (AES-256, AES-GCM, clave pública)	Mutuamente excluyentes. El flujo de pistas se emitiría en texto plano, por lo que el motor rechaza la combinación.
Firmas PAdES	Mutuamente excluyentes. La relinealización reescribe los desplazamientos de bytes y rompería el /ByteRange de una firma.
Actualizaciones incrementales	Mutuamente excluyentes dentro de una misma construcción.

La protección es bidireccional e independiente del orden: solicitar cifrado (o una firma) en un documento ya marcado para linealización lanza una excepción, y marcar para linealización un documento ya cifrado (o ya firmado) lanza una excepción. En ambos casos se lanza InvalidConfigException.

use NextPDF\Exception\InvalidConfigException;

$document->setEncryption('user-pw', 'owner-pw'); // (userPassword, ownerPassword)

try {
    $document->enableLinearization(); // rejected — encryption is already configured
} catch (InvalidConfigException $e) {
    // Linearization and encryption cannot be combined on one document.
}

Leer un archivo linealizado

LinearizationView analiza el diccionario de parámetros de linealización situado al principio de un PDF finalizado. Es el único punto de enlace admitido para un transporte que quiera planificar la entrega; quien lo utiliza no reimplementa el análisis del diccionario.

examples/linearization/inspect.php

<?php

declare(strict_types=1);

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

use NextPDF\Writer\Linearization\LinearizationView;

$view = LinearizationView::fromPdf($pdf);

if ($view->isLinearized) {
    // Plan, e.g., a first-page byte range from the parsed dictionary fields:
    // file length, first-page object number, main cross-reference offset,
    // hint-table offset and length, first-page end offset, page count.
    $firstPageEnd = $view->firstPageEndOffset;
}

Superficie de la API

Tipo	Clase	Miembros clave	Estabilidad	Desde
Document	clase	enableLinearization(): static, useLegacyLinearizer(): static	estable	3.2.0
Config	clase	withLinearization(bool $linearize = true): self	estable	6.1.0
LinearizationView	clase	fromPdf(string): self, lengthMatches(int): bool, campos públicos de solo lectura del diccionario	estable	3.2.0

enableLinearization() lanza InvalidConfigException cuando ya se ha configurado cifrado o una firma PAdES. LinearizationView::fromPdf() devuelve una vista cuyo indicador isLinearized es false para un documento que no incluye ningún diccionario de linealización.

Limitaciones

• Un documento linealizado no puede además cifrarse ni firmarse con PAdES. Elegir una sola opción por construcción.
• El backend heredado v1 emite parámetros Annex F no conformes y existe solo por compatibilidad de bytes con salidas anteriores. La comprobación de conformidad se ejecuta sobre v2.
• Fast Web View es una optimización de la entrega, no una funcionalidad de seguridad ni de validación; no cambia el contenido representado de la página.