Linearisierung: Fast Web View-Ausgabe

Auf einen Blick

Ein linearisiertes PDF — Fast Web View — ist so aufgebaut, dass ein Reader die erste Seite anzeigen kann, bevor der Rest der Datei eingetroffen ist. Die Objekte der ersten Seite, ihre Cross-Reference-Untersektion und eine Hint-Tabelle, die jede weitere Seite lokalisiert, liegen alle nahe am Dateianfang. NextPDF erzeugt dieses Layout deterministisch: Dasselbe Dokument erzeugt auf jedem Host dieselben Bytes, und das Ergebnis besteht qpdf --check-linearization.

Die Linearisierung ist ein Core-Feature. Sie aktivieren sie am Document; die Engine erstellt das Drei-Pass-Layout, das Linearisierungs-Parameter-Dictionary und die Hint-Tabelle. Die leseseitige LinearizationView parst das Linearisierungs-Dictionary einer fertigen Datei, sodass ein Transport die Auslieferung planen kann, ohne das Format neu zu implementieren.

Installation

composer require nextpdf/core:^3

Konzeptioneller Überblick

Ein herkömmliches PDF platziert seine Cross-Reference-Tabelle ganz am Ende, sodass ein Reader das Dateiende laden muss, bevor er ein Objekt auflösen kann. Ein linearisiertes PDF ordnet die Datei in zwei Teile um. Der erste Teil enthält das Linearisierungs-Parameter-Dictionary, die erste Seite und die Seitenoffset-Hint-Tabelle. Der zweite Teil enthält die übrigen Seiten. Ein Reader, der Fast Web View unterstützt, kann Seite eins aus dem ersten Teil rendern und anschließend über die Hint-Tabelle direkt zu jeder späteren Seite springen, während weitere Bytes eintreffen — ISO 32000-2 Annex F.

NextPDF enthält zwei Backends. Das standardmäßige v2-Backend ist ein Drei-Pass-Linearisierer, der eine Ausgabe nach ISO 32000-2 Annex F mit einer konformen Seitenoffset-Hint-Tabelle und einer /L-Länge erzeugt, die der exakten Byte-Länge der Datei entspricht. Ein Legacy-v1-Backend bleibt für die Byte-Kompatibilität mit Dokumenten erhalten, die vor v2 erzeugt wurden; es gibt nicht-konforme Annex F-Parameter aus und ist nur per Opt-in nutzbar. Neue Implementierungen sollten das Standard-Backend verwenden.

Determinismus wird strikt garantiert. Der Datei-Identifier wird aus dem Inhalts-Digest statt aus einer Zufallsquelle abgeleitet, sodass enableLinearization() eine reine Funktion des Dokuments ist. Genau das erlaubt es den Golden-Byte-Tests, die Ausgabe exakt festzuschreiben, und ermöglicht nachgelagert einen inhaltsadressierten Cache oder ein stabiles ETag.

Linearisierung aktivieren

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

Das Standard-Backend ist v2. Um das Legacy-v1-Backend zu aktivieren, rufen Sie zuerst useLegacyLinearizer() auf (beide Reihenfolgen funktionieren):

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

Aus der Konfiguration

Sie können die Linearisierung auch deklarativ über Config aktivieren. Die Einstellung wird beim Erstellen des Dokuments angewendet. Das passt zu Pipelines, die das Auslieferungsformat vorab festlegen, statt für jedes Dokument eine Methode aufzurufen:

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() ist standardmäßig deaktiviert, wie andere Config-Optionen auch. Übergeben Sie false, um diese Wahl explizit zu machen. Ein so erstelltes Dokument läuft über denselben enableLinearization()-Pfad, sodass die unten beschriebenen Konformitäts-Guards identisch gelten.

Konformitäts-Interaktionen

Die Linearisierung lässt sich mit getaggten und archivtauglichen Profilen kombinieren, ist jedoch mit Features unvereinbar, die die vorgelagerte Hint-Tabelle oder eine Byte-Range-Signatur ungültig machen würden.

Feature	Interaktion
PDF/A, PDF/UA	Kombinierbar. v2 behält die Objektnummerierung bei, sodass Struktur- und Tag-Referenzen gültig bleiben.
Verschlüsselung (AES-256, AES-GCM, Public-Key)	Gegenseitig ausschließend. Der Hint-Stream würde im Klartext ausgegeben, daher lehnt die Engine die Kombination ab.
PAdES-Signaturen	Gegenseitig ausschließend. Eine erneute Linearisierung schreibt Byte-Offsets neu und würde die /ByteRange einer Signatur zerstören.
Inkrementelle Updates	Innerhalb eines einzelnen Builds gegenseitig ausschließend.

Der Guard ist bidirektional und reihenfolgeunabhängig: Wenn für ein bereits zur Linearisierung markiertes Dokument Verschlüsselung (oder eine Signatur) angefordert wird, wirft das eine Exception; ebenso, wenn ein bereits verschlüsseltes (oder bereits signiertes) Dokument zur Linearisierung markiert wird. In beiden Fällen wird InvalidConfigException geworfen.

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

Eine linearisierte Datei lesen

LinearizationView parst das Linearisierungs-Parameter-Dictionary am Anfang eines fertigen PDF und ist der einzige unterstützte Anbindungspunkt für einen Transport, der die Auslieferung planen soll. Aufrufer implementieren den Dictionary-Parse niemals neu.

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

API-Oberfläche

Typ	Art	Wichtige Mitglieder	Stabilität	Seit
Document	class	enableLinearization(): static, useLegacyLinearizer(): static	stable	3.2.0
Config	class	withLinearization(bool $linearize = true): self	stable	6.1.0
LinearizationView	class	fromPdf(string): self, lengthMatches(int): bool, öffentliche Read-only-Dictionary-Felder	stable	3.2.0

enableLinearization() wirft InvalidConfigException, wenn Verschlüsselung oder eine PAdES-Signatur bereits konfiguriert ist. LinearizationView::fromPdf() gibt eine Sicht zurück, deren isLinearized-Flag bei einem Dokument ohne Linearisierungs-Dictionary false ist.

Einschränkungen

• Ein linearisiertes Dokument kann nicht zugleich verschlüsselt oder mit PAdES signiert sein. Wählen Sie eines pro Build.
• Das Legacy-v1-Backend gibt nicht-konforme Annex F-Parameter aus und existiert nur für die Byte-Kompatibilität mit älterer Ausgabe. Das Konformitäts-Gate läuft gegen v2.
• Fast Web View ist eine Auslieferungsoptimierung, kein Sicherheits- oder Validierungs-Feature; es ändert nicht den gerenderten Seiteninhalt.