ナビゲーション：注釈、リンク、アウトライン、アクション、添付ファイル

概要

Navigation モジュールは、PDF のインタラクティブ層を構築します。対象となるのは、注釈、リンク注釈と URL 注釈、ドキュメントアウトライン（ブックマーク）と目次、アクションとトリガーチェーン、ページ遷移、関連ファイル関係を伴う埋め込みファイル添付です。

インストール

composer require nextpdf/core:^3

概念の概要

ISO 32000-2 §12 は、PDF のインタラクティブ機能として、注釈、アクション、デスティネーション、ドキュメントアウトラインを定義しています。このモジュールは、その層を扱うエンジン側のエンコーダーです。意図を蓄積する一連のマネージャークラスと、マネージャーが出力する値オブジェクト群で構成されています。

AnnotationManager は、最も広い範囲を扱うサーフェスです。テキスト、フリーテキスト、線、四角形、円、多角形、折れ線、インク、テキストマークアップ注釈（ハイライト、下線）を追加します。堅牢性を考慮して設計されており、未知の注釈サブタイプは安全なデフォルトにフォールバックし、有効な PDF 名前トークンではないアイコン名は置き換えられます。また、テキストマークアップの QuadPoints は 8 の倍数の浮動小数点数として渡されなければならず、そうでない場合は破棄されます。これらは PDF インジェクションに対する防御であり、検証を便利にするためのものではありません。LinkManager は、内部リンク、名前付きデスティネーション、URL 注釈を処理します。注釈オブジェクトを事前に割り当てることで、Writer はシリアライズ前にそれらを参照できます。

BookmarkManager と TocBuilder は、ナビゲーション階層を構築します。ドキュメントアウトラインは、ビューアーがサイドバーに表示するブックマークツリーです。TocBuilder はページ内の目次をレンダリングし、leader/width レイアウトに FontMetrics を使用できます。OutlineAutoGenerator は、ドキュメント構造からアウトラインを導出します。

NextPDF\Navigation\Action 配下の Action 階層は、トリガー駆動の動作をモデル化します。対象は、GoTo（リモートおよび埋め込み）、launch、named、hide、reset/submit フォーム、オプショナルコンテンツ状態の設定です。§13 のスクリーン注釈レンディションアクションは延期されています。将来の作業であり、まだ接続されていないため、サポート対象のアクションとして依存しないでください。Action::withNext() は、単一のトリガーイベントが実行するアクションチェーンを構築します。PageTransition は、プレゼンテーション遷移をモデル化します。FileAttachment は、パスまたはバイト文字列からファイルを埋め込み、AFRelationship（関連ファイル関係の列挙型）でタグ付けします。FileAttachmentResult を返し、writeAttachments() を通じて書き込みます。コアマネージャーは @since 1.0.0、アクション階層は @since 2.1.0 です。FileAttachment コンストラクターと AFRelationship は、@since 1.8.0 / @since 1.1.0 で導入されました。

API サーフェス

クラス	主なメンバー	役割
`AnnotationManager`	`addAnnotation()`, `addFreeText()`, `addLine()`, `addSquare()`, `addCircle()`, `addPolygon()`, `addInk()`, `addHighlight()`, `addUnderline()`	インジェクション耐性のある入力を備えた注釈ビルダー (`@since 1.0.0`)
`LinkManager`	`addLink()`, `setLink()`, `setDestination()`, `addLinkAnnotation()`, `addUrlAnnotation()`, `preallocateAnnotationObjects()`	内部リンク、名前付きデスティネーション、URL 注釈 (`@since 1.0.0`)
`BookmarkManager`	`addBookmark()`, `hasBookmarks()`, `write()`	ドキュメントアウトライン (ブックマーク) ツリー (`@since 1.0.0`)
`TocBuilder`	`addEntry()`, `hasEntries()`, `render()`, `getEntries()`	ページ内の目次 (`@since 1.0.0`)
`Action` (インターフェイス)	`subtype()`, `toDictionary()`, `withNext()`, `nextChain()`	トリガーアクション + アクションチェーン (`@since 2.1.0`)
`PageTransition`	`toDict()`, `toInlineDict()`	プレゼンテーションのページ遷移 (`@since 1.2.0`)
`FileAttachment`	`embedFile()`, `embedFileFromString()`, `hasAttachments()`, `getCount()`, `writeAttachments()`	埋め込みファイル添付 (`@since 1.0.0`)
`AFRelationship` (列挙型)	`toPdfName()`	関連ファイル関係 (`@since 1.1.0`)
`AnnotationFlags`	`with()`, `without()`, `has()`, `toInt()`	イミュータブルな注釈フラグセット (`@since 1.2.0`)

完全な PHPDoc 表は、composer docs:generate-api-php -- --module=Navigation を実行して取得できます。

コードサンプル — クイックスタート

ソース：examples/12-bookmarks-and-toc.php は、BookmarkManager をラップする高レベルファサードでドキュメントアウトラインを構築します。マネージャーを直接操作する場合：

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Navigation\BookmarkManager;

$bookmarks = new BookmarkManager();
$bookmarks->addBookmark(title: 'Chapter 1', level: 0, pageIndex: 0);
$bookmarks->addBookmark(title: '1.1 Overview', level: 1, pageIndex: 0);
$bookmarks->addBookmark(title: 'Chapter 2', level: 0, pageIndex: 4);

if ($bookmarks->hasBookmarks()) {
    // The Writer calls $bookmarks->write(...) during catalog serialization.
}

コードサンプル — 本番

明示的な関連ファイル関係を指定して添付ファイルを埋め込み、ドキュメントを確定する前に結果を確認します。

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Navigation\AFRelationship;
use NextPDF\Navigation\FileAttachment;

$attachments = new FileAttachment();

$attachments->embedFile(
    path: '/srv/invoices/INV-2026-0042.xml',
    description: 'Structured invoice source (Factur-X)',
    afRelationship: AFRelationship::Source,
);

if ($attachments->hasAttachments()) {
    // writeAttachments() is invoked by the Writer with a live ObjectRegistry;
    // getCount() lets the application assert the expected attachment count.
    assert($attachments->getCount() === 1);
}

エッジケースと注意点

AnnotationManager は、敵対的な入力を暗黙的に正規化します。無効なサブタイプはデフォルトに置き換わり、名前ではないアイコンはデフォルトアイコンになり、不正な形式の QuadPoints は破棄されます。それでも注釈は生成されます。入力を正確に反映させる必要がある場合は、上流で入力を検証してください。
LinkManager::preallocateAnnotationObjects() は、Writer が参照をシリアライズする前に実行されなければならず、そうでなければリンクターゲットは解決されません。
Action::withNext() は、チェーンが付加された新しいアクションを返します。このインターフェイスは、インプレース変更ではなく、イミュータブルな連結を行う設計です。
FileAttachment::writeAttachments() は、Writer からのアクティブな ObjectRegistry を必要とします。マネージャー単体では意図は蓄積されますが、Writer がそれを駆動するまで何も書き込まれません。
AnnotationFlags は、イミュータブルなフラグセットです。with()/without() は新しいインスタンスを返し、元のインスタンスは変更されません。

パフォーマンス

注釈、リンク、ブックマークの蓄積はリフローを伴わず、項目数に対して O(n) です。埋め込みファイル添付のコストは、マネージャーではなく、埋め込まれるバイトサイズに左右されます。デフォルトのリファレンスワークロードは、1500 ms の実時間 / 64 MB のピークという予算内に収まります。再現性プロファイルは structural です。つまり、オブジェクト番号とトレーラーの /ID は実行ごとに異なります。同じナビゲーション意図を持つ 2 つのドキュメントは構造的には等しくなりますが、バイト単位では同一になりません。

セキュリティに関する注意事項

AnnotationManager は、注釈サブタイプ、アイコン、QuadPoints を信頼できないものとして扱います。つまり、それぞれが許可リストまたはパターンに対して検証され、不正な値はそのまま書き込まれるのではなく置き換えられます。これにより、PDF 名前インジェクションのベクターを塞ぎます。LinkManager::addUrlAnnotation() は、URL をリンクアクションにエンコードします。URL の信頼性は利用者側の責任です。悪意のある URL も有効な URL であるため、追加する前にデスティネーションをサニタイズしてください。FileAttachment は、任意のバイト列を埋め込みます。埋め込みサイズに上限を設け、添付ファイルのソースがユーザー由来である場合は、それを信頼できないものとして扱ってください。エンジンの脅威モデルについては、/modules/core/security/ を参照してください。

準拠

このモジュールが出力する構造は、ISO 32000-2 §12（注釈、アクション、デスティネーション）およびドキュメントアウトライン階層に従います。機能ごとの条項参照（注釈アイコン §12.5.6.4、テキストマークアップ QuadPoints §12.5.6.10、アクション §12.6）は、src/Navigation/ 内にインラインで文書化され、tests/Unit/Navigation/ によって検証されます。これらは実装上の事実であり、エンドツーエンドの PDF 2.0 準拠を表明するものではありません。ドキュメント全体の準拠は、/modules/core/conformance/ で説明されているオラクルおよびゴールデンスイートによって検証されます。