Linearizzazione: output Fast Web View

In breve

Un PDF linearizzato — Fast Web View — è organizzato in modo che un lettore possa visualizzare la prima pagina prima che arrivi il resto del file. Gli oggetti della prima pagina, la relativa sottosezione dei riferimenti incrociati e una tabella di hint che individua ogni altra pagina si trovano tutti vicino all’inizio del file. NextPDF genera questo layout in modo deterministico: lo stesso documento produce gli stessi byte su qualunque host e il risultato supera qpdf --check-linearization.

La linearizzazione è una funzionalità di Core. Si attiva sul Document; il motore gestisce il layout a tre passaggi, il dizionario dei parametri di linearizzazione e la tabella di hint. La LinearizationView lato lettura analizza il dizionario di linearizzazione di un file completato, così che un livello di trasporto possa pianificare la consegna senza reimplementare il formato.

Installazione

composer require nextpdf/core:^3

Panoramica concettuale

Un PDF standard colloca la tabella di riferimenti incrociati alla fine, quindi un lettore deve recuperare la coda del file prima di poter risolvere qualsiasi oggetto. Un PDF linearizzato riordina il file in due parti. La prima parte contiene il dizionario dei parametri di linearizzazione, la prima pagina e la tabella di hint degli offset di pagina. La seconda parte contiene le pagine rimanenti. Un lettore che supporta Fast Web View può eseguire il rendering della prima pagina a partire dalla prima parte, quindi usare la tabella di hint per posizionarsi direttamente su qualunque pagina successiva man mano che i byte continuano ad arrivare — ISO 32000-2 Annex F.

NextPDF include due backend. Il backend v2 predefinito è un linearizzatore a tre passaggi che produce output conforme a ISO 32000-2 Annex F, con una tabella di hint degli offset di pagina conforme e una lunghezza /L pari all’esatta lunghezza in byte del file. Un backend legacy v1 è mantenuto per la compatibilità byte a byte con i documenti prodotti prima di v2; genera parametri Annex F non conformi ed è disponibile solo su richiesta esplicita. Per i nuovi lavori usare il backend predefinito.

Il determinismo è una garanzia rigorosa. L’identificatore del file deriva dal digest del contenuto, non da una sorgente casuale; enableLinearization() è quindi una funzione pura del documento. Questo consente ai golden byte test di fissare l’output e rende possibile, a valle, una cache indirizzata al contenuto o un ETag stabile.

Abilitare la linearizzazione

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

Il backend predefinito è v2. Per attivare il backend legacy v1, chiamare anche useLegacyLinearizer() (entrambi gli ordini sono validi):

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

Dalla configurazione

È possibile attivarla anche in modo dichiarativo tramite Config. L’impostazione viene applicata quando il documento viene compilato, ed è quindi adatta alle pipeline che fissano il formato di consegna in anticipo anziché chiamare un metodo su ciascun 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() è disattivata per impostazione predefinita, come le altre opzioni di Config. Passare false per rendere esplicita questa scelta. Un documento creato in questo modo passa attraverso lo stesso percorso enableLinearization(), quindi le protezioni di conformità descritte di seguito si applicano allo stesso modo.

Interazioni di conformità

La linearizzazione può essere combinata con i profili tagged e di archiviazione, ma è mutuamente esclusiva rispetto alle funzionalità che invaliderebbero la tabella di hint iniziale o una firma per intervalli di byte.

Funzionalità	Interazione
PDF/A, PDF/UA	Si combinano. v2 mantiene la numerazione degli oggetti, quindi i riferimenti di struttura e tag rimangono validi.
Cifratura (AES-256, AES-GCM, chiave pubblica)	Mutuamente esclusive. Il flusso di hint verrebbe emesso in chiaro; il motore quindi rifiuta la combinazione.
Firme PAdES	Mutuamente esclusive. La rilinearizzazione riscrive gli offset di byte e comprometterebbe il /ByteRange di una firma.
Aggiornamenti incrementali	Mutuamente esclusivi in una singola compilazione.

La protezione è bidirezionale e indipendente dall’ordine: richiedere la cifratura (o una firma) su un documento già contrassegnato per la linearizzazione genera un’eccezione; lo stesso vale se si contrassegna per la linearizzazione un documento già cifrato (o già firmato). In entrambi i casi viene generata 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.
}

Lettura di un file linearizzato

LinearizationView analizza il dizionario dei parametri di linearizzazione all’inizio di un PDF completato. È l’unico punto di integrazione supportato per un livello di trasporto che vuole pianificare la consegna; i chiamanti non devono mai reimplementare l’analisi del dizionario.

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 dell’API

Tipo	Genere	Membri principali	Stabilità	Da
Document	classe	enableLinearization(): static, useLegacyLinearizer(): static	stabile	3.2.0
Config	classe	withLinearization(bool $linearize = true): self	stabile	6.1.0
LinearizationView	classe	fromPdf(string): self, lengthMatches(int): bool, campi del dizionario pubblici in sola lettura	stabile	3.2.0

enableLinearization() genera InvalidConfigException quando la cifratura o una firma PAdES è già configurata. LinearizationView::fromPdf() restituisce una vista con flag isLinearized impostato a false per un documento che non contiene alcun dizionario di linearizzazione.

Limitazioni

• Un documento linearizzato non può essere anche cifrato o firmato con PAdES. Scegliere una sola opzione per ogni compilazione.
• Il backend legacy v1 genera parametri Annex F non conformi ed esiste solo per la compatibilità byte a byte con l’output meno recente. Il controllo di conformità viene eseguito su v2.
• Fast Web View è un’ottimizzazione della consegna, non una funzionalità di sicurezza o di convalida; non modifica il contenuto della pagina sottoposto a rendering.