Linéarisation : sortie Fast Web View

En un coup d’œil

Un PDF linéarisé — Fast Web View — est organisé de sorte qu’un lecteur puisse afficher la première page avant que le reste du fichier ne soit arrivé. Les objets de la première page, la sous-section de sa table de références croisées et une table d’indices qui localise toutes les autres pages sont regroupés près du début du fichier. NextPDF produit cette disposition de manière déterministe : le même document génère les mêmes octets sur chaque machine, et le résultat passe qpdf --check-linearization.

La linéarisation fait partie du Core. Tu actives l’option sur le Document ; le moteur gère la disposition en trois passes, le dictionnaire de paramètres de linéarisation et la table d’indices. Côté lecture, LinearizationView analyse le dictionnaire de linéarisation d’un fichier finalisé afin qu’un transport puisse planifier la livraison sans réimplémenter le format.

Installation

composer require nextpdf/core:^3

Vue d’ensemble conceptuelle

Un PDF standard place sa table de références croisées tout à la fin, de sorte qu’un lecteur doit récupérer la fin du fichier avant de pouvoir résoudre le moindre objet. Un PDF linéarisé réorganise le fichier en deux parties. La première partie contient le dictionnaire de paramètres de linéarisation, la première page et la table d’indices de décalage de page. La seconde partie contient les pages restantes. Un lecteur qui prend en charge Fast Web View peut afficher la première page à partir de la première partie, puis utiliser la table d’indices pour se positionner directement sur n’importe quelle page ultérieure au fur et à mesure que les octets continuent d’arriver — ISO 32000-2 Annex F.

NextPDF fournit deux backends. Le backend v2 par défaut est un linéariseur en trois passes qui produit une sortie ISO 32000-2 Annex F avec une table d’indices de décalage de page conforme et une longueur /L égale à la longueur exacte du fichier en octets. Un backend hérité v1 est conservé pour la compatibilité octet pour octet avec les documents produits avant la v2 ; il émet des paramètres Annex F non conformes et ne s’active que sur option explicite. Pour tout nouveau développement, utilise le backend par défaut.

Le déterminisme est une garantie stricte. L’identifiant de fichier est dérivé de l’empreinte du contenu plutôt que d’une source aléatoire, de sorte que enableLinearization() est une fonction pure du document. C’est ce qui permet aux tests comparant des octets de référence de figer la sortie et rend possible, en aval, un cache adressé par contenu ou un ETag stable.

Activer la linéarisation

<?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();

Le backend par défaut est le v2. Pour passer au backend hérité v1, appelle d’abord useLegacyLinearizer() (l’ordre n’a pas d’importance) :

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

Depuis la configuration

Tu peux aussi activer l’option de manière déclarative via Config. Le réglage est appliqué au moment de la construction du document, ce qui convient aux pipelines qui fixent le format de livraison en amont au lieu d’appeler une méthode sur chaque document :

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 désactivé par défaut, comme les autres options de Config. Passe false pour rendre ce choix explicite. Un document construit ainsi suit le même chemin que enableLinearization(), si bien que les garde-fous de conformité ci-dessous s’appliquent de manière identique.

Interactions avec la conformité

La linéarisation se combine avec les profils de balisage et d’archivage, mais elle est mutuellement exclusive avec les fonctionnalités qui invalideraient la table d’indices calculée en amont ou une signature par plages d’octets.

Fonctionnalité	Interaction
PDF/A, PDF/UA	Compatible. La v2 préserve la numérotation des objets, donc les références de structure et de balises restent valides.
Chiffrement (AES-256, AES-GCM, à clé publique)	Mutuellement exclusifs. Le flux d’indices serait émis en clair, donc le moteur rejette cette combinaison.
Signatures PAdES	Mutuellement exclusives. La re-linéarisation réécrit les décalages d’octets, ce qui casserait le `/ByteRange` d’une signature.
Mises à jour incrémentales	Mutuellement exclusives au sein d’une même construction.

Le garde-fou est bidirectionnel et indépendant de l’ordre : demander un chiffrement (ou une signature) sur un document déjà marqué pour la linéarisation lève une exception, et marquer un document déjà chiffré (ou déjà signé) pour la linéarisation lève une exception. Dans les deux cas, InvalidConfigException est levée.

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.
}

Lire un fichier linéarisé

LinearizationView analyse le dictionnaire de paramètres de linéarisation situé au début d’un PDF finalisé. C’est le seul point d’accroche pris en charge pour un transport qui veut planifier la livraison ; les appelants ne réimplémentent jamais l’analyse du dictionnaire.

<?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;
}

Surface de l’API

Type	Genre	Membres clés	Stabilité	Depuis
`Document`	classe	`enableLinearization(): static`, `useLegacyLinearizer(): static`	stable	3.2.0
`Config`	classe	`withLinearization(bool $linearize = true): self`	stable	6.1.0
`LinearizationView`	classe	`fromPdf(string): self`, `lengthMatches(int): bool`, champs publics de dictionnaire en lecture seule	stable	3.2.0

enableLinearization() lève InvalidConfigException lorsqu’un chiffrement ou une signature PAdES est déjà configuré. LinearizationView::fromPdf() renvoie une vue dont l’indicateur isLinearized vaut false pour un document qui ne contient aucun dictionnaire de linéarisation.

Limitations

Un document linéarisé ne peut pas être en même temps chiffré ou signé avec PAdES. Choisis-en un seul par construction.
Le backend hérité v1 émet des paramètres Annex F non conformes et n’existe que pour la compatibilité octet pour octet avec d’anciennes sorties. Le contrôle de conformité s’exécute sur la v2.
Fast Web View est une optimisation de livraison, pas une fonctionnalité de sécurité ou de validation ; cela ne change pas le contenu rendu de la page.

Linéarisation : sortie Fast Web View