線形化：Fast Web View 出力

概要

線形化された PDF（Fast Web View）は、ファイルの残りが届く前にリーダーが最初のページを表示できるようにレイアウトされています。最初のページのオブジェクト、それに対応する相互参照サブセクション、そして他のすべてのページの位置を特定するヒントテーブルは、いずれもファイルの先頭付近に配置されます。NextPDF はこのレイアウトを決定論的に出力します。同じドキュメントからは、どのホストでも同じバイト列が生成され、その結果は qpdf --check-linearization を通過します。

線形化は Core の機能です。Document でオプトインします。エンジンが 3 パスのレイアウト、線形化パラメーター辞書、およびヒントテーブルを処理します。読み取り側の LinearizationView は完成したファイルの線形化辞書を解析するため、トランスポートはフォーマットを再実装することなく配信を計画できます。

インストール

composer require nextpdf/core:^3

概念の概要

標準的な PDF は相互参照テーブルを末尾に配置するため、リーダーはオブジェクトを resolve（解決）する前にファイルの末尾まで取得する必要があります。線形化された PDF は、ファイルを 2 つの部分に並べ替えます。最初の部分には、線形化パラメーター辞書、最初のページ、およびページオフセットのヒントテーブルが含まれます。2 つ目の部分には、残りのページが含まれます。Fast Web View をサポートするリーダーは、最初の部分から 1 ページ目をレンダリングし、バイトが届き続ける間にヒントテーブルを使用して任意の後続ページへ直接シークできます（ISO 32000-2 Annex F）。

NextPDF は 2 つのバックエンドを提供します。デフォルトの v2 バックエンドは 3 パスの線形化処理を行い、準拠したページオフセットのヒントテーブルと、ファイルの正確なバイト長に等しい /L の長さを備えた ISO 32000-2 Annex F 出力を生成します。レガシーの v1 バックエンドは、v2 より前に生成されたドキュメントとのバイト互換性のために保持されています。このバックエンドは非準拠の Annex F パラメーターを出力し、オプトインの場合にのみ使用されます。新規の作業ではデフォルトを使用してください。

決定論性は強い保証です。ファイル識別子はランダムなソースではなくコンテンツダイジェストから導出されるため、enableLinearization() はドキュメントの純粋関数です。これにより、ゴールデンバイトテストで出力を固定でき、下流でコンテンツアドレス指定のキャッシュや安定した ETag を実現できます。

線形化の有効化

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

デフォルトのバックエンドは v2 です。レガシーの v1 バックエンドにオプトインするには、useLegacyLinearizer() を呼び出します（順序はどちらでも構いません）。

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

構成からの有効化

宣言的にオプトインする方法として、Config を使用することもできます。この設定はドキュメントのビルド時に適用されるため、各ドキュメントでメソッドを呼び出す代わりに配信フォーマットを事前に固定するパイプラインに適しています。

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() は、他の Config オプションと同様に、デフォルトでは無効です。無効であることを明示するには false を渡します。この方法でビルドされたドキュメントは同じ enableLinearization() パスを経由するため、以下の準拠ガードが同一に適用されます。

準拠に関する相互作用

線形化はタグ付きプロファイルおよびアーカイブプロファイルと併用できますが、先頭に配置されたヒントテーブルやバイトレンジ署名を無効化する機能とは相互排他的です。

機能	相互作用
PDF/A、PDF/UA	併用可能。v2 はオブジェクト番号を保持するため、構造とタグの参照は有効なまま維持されます。
暗号化（AES-256、AES-GCM、および公開鍵による暗号化）	相互排他的。ヒントストリームが平文で出力されてしまうため、エンジンはこの組み合わせを拒否します。
PAdES 署名	相互排他的。再線形化はバイトオフセットを書き換えるため、署名の `/ByteRange` が破損します。
インクリメンタル更新	単一のビルドでは相互排他的。

このガードは双方向であり、順序に依存しません。すでに線形化が指定されたドキュメントに対して暗号化（または署名）を要求すると例外がスローされ、すでに暗号化（または署名）されたドキュメントに線形化を指定しても例外がスローされます。いずれの場合も 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.
}

線形化されたファイルの読み取り

LinearizationView は、完成した PDF の先頭にある線形化パラメーター辞書を解析します。これは配信を計画するトランスポートに対してサポートされる唯一のバインディングポイントであり、呼び出し側が辞書解析を再実装する必要はありません。

<?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 サーフェス

型	種別	主なメンバー	安定性	導入バージョン
`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`、パブリックな読み取り専用の辞書フィールド	stable	3.2.0

enableLinearization() は、暗号化または PAdES 署名がすでに構成されている場合に InvalidConfigException をスローします。LinearizationView::fromPdf() は、線形化辞書を持たないドキュメントに対しては、isLinearized フラグが false のビューを返します。

制限事項

線形化されたドキュメントは、同時に暗号化したり PAdES で署名したりすることはできません。ビルドごとにいずれか 1 つを選択してください。
レガシーの v1 バックエンドは非準拠の Annex F パラメーターを出力し、古い出力とのバイト互換性のためにのみ存在します。準拠ゲートは v2 に対して実行されます。
Fast Web View は配信の最適化であり、セキュリティや検証のための機能ではありません。レンダリングされるページの内容は変更されません。