Linearization: Fast Web View output

At a glance

A linearized Portable Document Format (PDF) file, also called Fast Web View, is arranged so a reader can display the first page before the full file arrives. The first page’s objects, its cross-reference subsection, and the hint table for every other page sit near the front of the file. NextPDF emits this layout deterministically: the same document produces the same bytes on every host, and the result passes qpdf --check-linearization.

Linearization is a Core feature. To use it, opt in on the Document; the engine handles the three-pass layout, the linearization parameter dictionary, and the hint table. The read-side LinearizationView parses the linearization dictionary in a finished file, so a transport can plan delivery without re-implementing the format.

Install

composer require nextpdf/core:^3

Conceptual overview

A standard PDF places its cross-reference table at the end, so a reader must fetch the tail of the file before it can resolve any object. A linearized PDF organizes the file into two parts. The first part holds the linearization parameter dictionary, the first page, and the page-offset hint table. The second part holds the remaining pages. A reader that supports Fast Web View can render page one from the first part, then use the hint table to seek directly to any later page as bytes continue to arrive, as defined by ISO 32000-2 Annex F.

NextPDF provides two backends. The default v2 backend is a three-pass linearizer that produces ISO 32000-2 Annex F output with a conformant page-offset hint table and a /L length that equals the exact byte length of the file. A legacy v1 backend remains for byte-compatibility with documents produced before v2; it emits non-conformant Annex F parameters and is opt-in only. For new work, use the default.

Determinism is guaranteed. The file identifier comes from the content digest, not a random source, so enableLinearization() is a pure function of the document. This lets golden byte tests pin the output and lets downstream systems use a content-addressed cache or a stable ETag.

Enabling linearization

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

The default backend is v2. To use the legacy v1 backend, call useLegacyLinearizer() first (either order works):

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

From configuration

You can also opt in through Config. NextPDF applies the setting when it builds the document, which fits pipelines that choose the delivery format up front instead of calling a method on each 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

Like other Config options, withLinearization() is off by default. Pass false to make that choice explicit. A document built this way uses the same enableLinearization() path, so the conformance guards below apply identically.

Conformance interactions

Linearization works with the tagged and archival profiles, but it is mutually exclusive with features that would invalidate the up-front hint table or a PDF Advanced Electronic Signatures (PAdES) byte-range signature.

Feature	Interaction
PDF/A, PDF/UA	Compose. v2 preserves object numbering, so structure and tag references stay valid.
Encryption (AES-256, AES-GCM, public-key)	Mutually exclusive. The hint stream would be emitted in plaintext, so the engine rejects the pair.
PAdES signatures	Mutually exclusive. Re-linearization rewrites byte offsets and would break a signature’s /ByteRange.
Incremental updates	Mutually exclusive on a single build.

The guard is bidirectional and order-independent. Requesting encryption (or a signature) on a document already marked for linearization throws. Marking an already-encrypted (or already-signed) document for linearization also throws. Both paths throw 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.
}

Reading a linearized file

LinearizationView parses the linearization parameter dictionary at the front of a finished PDF. It is the only supported entry point for a transport that plans delivery; callers never re-implement the dictionary parser.

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 surface

Type	Kind	Key members	Stability	Since
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, public read-only dictionary fields	stable	3.2.0

enableLinearization() throws InvalidConfigException when encryption or a PAdES signature is already configured. LinearizationView::fromPdf() returns a view whose isLinearized flag is false for a document with no linearization dictionary.

Limitations

• A linearized document cannot also be encrypted or signed with PAdES. Choose one per build.
• The legacy v1 backend emits non-conformant Annex F parameters and exists only for byte-compatibility with older output. The conformance gate runs against v2.
• Fast Web View is a delivery optimization, not a security or validation feature. It does not change the rendered page content.