Pro エディション

プロジェクション

概要

Projection は、PDF コンテンツストリームを平坦なトークンリストに解析し、それらのトークンから新しいコンテンツストリームを出力します。出力には明示的に宣言された意図が必要です。このモジュールは汎用の PDF エディターではありません。

注記。 ここでの「Projection」は、コンテンツストリームのトークン投影を意味します。座標や地理空間の投影ではありません。地理空間機能については、Geo モジュールを参照してください。

可用性とライセンス

この機能は NextPDF Pro（nextpdf/pro）に同梱され、Pro 層のライセンスエンベロープで有効化されます。その権利を持たないデプロイでは、この機能のクラスは読み込まれません。エディションを比較してライセンスを取得する。

機能ごとの個別のライセンスフラグはありません。必須の ProjectionIntent 引数が、ライセンスのスイッチではなく API レベルで出力をゲートします。

インストール

composer require nextpdf/pro:^3

コードは NextPDF\Pro\Projection 名前空間の下にあります。

概念の概要

ContentProjectionWriter は、3 つの静的な操作を提供します。

tokenize() は、コンテンツストリームを平坦で順序付けられたトークンリストに解析します。これは読み取り専用であり、意図を必要としません。
emit() は、（変更されている可能性のある）トークンリストから新しいコンテンツストリームを書き出します。ProjectionIntent を必要とします。
roundTrip() は、検証のために、変更を加えずにトークン化して再出力します。

出力は概念的には、元のものを編集したコピーではなく、新しいコンテンツストリームです。エミッターは空白とコメントを正規化しますが、演算子のシーケンスとオペランドの値は正確に保ちます。意図の列挙型はちょうど 2 つのケース（サニタイズ（墨消し）とステガノグラフィー埋め込み）を持ち、意図的に汎用のケースを持たないため、静的解析が意図しない使用を検出できます。

なぜこのように動作するのか

Projection は汎用の PDF エディターであることを拒みます。出力は平坦なトークンリストから新しいコンテンツストリームを再構築するため、元のものがその場で変更されることは決してありません。その一方向のモデルこそが、墨消しを信頼できるものにします。除去されたトークンは、上から塗りつぶされるのではなく、出力に存在しません。したがって emit() は明示的な ProjectionIntent を要求し、列挙型はサニタイズとステガノグラフィー埋め込みのみを提供します。汎用のケースはありません。これにより静的解析は、宣言された既知の目的を欠くあらゆる出力を検出できます。この設計は、破壊的な意図が常に呼び出し箇所で可視であるという保証と引き換えに、編集の利便性を手放します。

設計の背景：墨消しは黒い矩形ではありません。

振る舞いの契約

tokenize($contentStream) は、文字列、名前、数値、配列、辞書、ブール値、null、演算子を網羅するトークンのリストを返します。
emit($tokens, $intent) は明示的な意図を必要とします。型システムが呼び出し箇所でこれを強制します。
roundTrip() の出力は入力とバイト単位で同一ではありませんが、演算子のシーケンスとオペランドの値は一致します。
エミッターは、整数と浮動小数点の区別を保つように数値をフォーマットし、リテラル文字列を再エスケープします。
宣言される 2 つの意図は、サニタイズ（破壊的で不可逆な墨消し操作）とステガノグラフィー埋め込みです。

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

以下は、文書化された公開 API を反映したものです。このモジュールについては、リポジトリに実行可能な例は付属していません。

use NextPDF\Pro\Projection\ContentProjectionWriter;

$tokens = ContentProjectionWriter::tokenize($contentStream);

コードサンプル — 本番

use NextPDF\Pro\Projection\ContentProjectionWriter;
use NextPDF\Pro\Projection\ProjectionIntent;

$tokens = ContentProjectionWriter::tokenize($contentStream);

// Validate first: a clean round-trip must hold before any modification.
$check = ContentProjectionWriter::roundTrip($contentStream);

// Apply your modification to $tokens, then emit with a declared intent.
$output = ContentProjectionWriter::emit($tokens, ProjectionIntent::Sanitization);

エッジケースと落とし穴

modify-and-emit のシーケンスを信頼する前に、roundTrip() を実行し、それが成立することを確認してください。失敗するラウンドトリップは停止条件として扱ってください。
サニタイズの意図は不可逆です。除去された内容は出力から復元できません。
エミッターは空白を正規化しコメントを削除するため、変更していないラウンドトリップであっても、元のものとのバイトレベルの比較は異なります。

パフォーマンス

トークン化と出力は、コンテンツストリームの長さに対して線形です。トークナイザーは、8 進エスケープの読み取りと 16 進文字列の処理に境界を設けます。公表されたスループット値はありません。代表的なコンテンツストリームで測定してください。

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

必須の意図引数が、汎用エディターとしての誤用を防ぎます。サニタイズの意図は破壊的かつ不可逆です。最初にラウンドトリップを検証し、配布前に墨消しされた出力を確認してください。このモジュールは内容をログに記録しません。

適合性

トークン化は、ISO 32000-2 のレキシカルおよびコンテンツストリームの規約に従います。ソースは関連する節に注釈を付けています。執筆時点で RAG コーパスが利用できなかったため、このページは外部の節識別子を一切主張せず、適合性に関する記述をモジュールのテストで検証された振る舞いに限定します。

Enterprise の境界に関する注記

Enterprise は Projection の振る舞いを変更しません。Enterprise は、別途文書化された上位層のプライバシーおよびコンプライアンス機能を追加します。それらは投影 API を使用するのには必要ありません。

Core のフォールバック/代替手段

これに相当する Core の機能はありません。Pro がない場合、呼び出し元は独自のコンテンツストリームトークナイザーを構築する必要があります。意図でゲートされた投影モデルは Pro 専用の追加機能です。

公開の境界

このページは、外部から観測可能な振る舞いと、サポートされる公開 API サーフェスのみを記述しています。内部の名前空間パス、ヘルパークラス、メカニズムの表、ランブックのファイル名、チケットのプレフィックスは対象外です。