Common

概要

NextPDF Enterprise は、Enterprise モジュール全体で再利用される小さな共有プリミティブのセットを同梱します。最初のものは、解像度に依存しない空間配置のための正規化されたバウンディングボックスです。これらはコンプライアンス、適合性、暗号の挙動を持たない value object です。

提供とライセンス

この機能は NextPDF Enterprise (nextpdf/enterprise) に同梱され、Enterprise ティアのライセンスエンベロープで有効化されます。そのエンタイトルメントを持たないデプロイメントでは、この機能のクラスはロードされません。エディションを比較してライセンスを取得。

Enterprise パッケージは Core パッケージと並べてインストールされます。これらの共有プリミティブは他の Enterprise モジュールによって内部的に使用され、パッケージとともに解決されます。Core ティアや Pro ティアの同等品はありません。

インストール

composer require nextpdf/enterprise:^3

概念の概要

BoundingBox は不変の value object であり、その 4 つの座標 — x、y、width、height — はページ寸法に対して [0.0, 1.0] の範囲に正規化されます。座標が正規化されているため、ボックスは解像度に依存せず、ページジオメトリを扱う Enterprise モジュール全体で再利用できます。コンストラクターは、すべての座標が範囲内であること、および x + width と y + height が 1.0 を超えないこと (小さな浮動小数点許容誤差の範囲内) を検証し、そうでなければ引数エラーを発生させます。

area()、contains(self $other)、overlaps(self $other) を公開します。面積がゼロのボックス (退化した点や線) は、定義上オーバーラップできません。

このモジュールが主張すること

このモジュールは、検証済みのジオメトリプリミティブを提供します。コンプライアンスや適合性の主張は行わず、I/O も実行しません。

ティアの境界

Common は、他の Enterprise モジュールが利用する Enterprise 専用のサポートサーフェスです。Core のジオメトリを複製または置換するものではなく、Enterprise モジュールが共有する小さな検証済みプリミティブを提供します。

なぜこのように機能するのか

要となる決定は、すべての座標を [0.0, 1.0] の範囲に正規化し、コンストラクターで検証することです。正規化された座標はボックスを解像度に依存しないものにするため、一度記述された領域はどのようなページサイズやレンダースケールでも正しいままです。フェイルクローズの構築は、無効なボックスやオーバーフローするボックスが存在しえないことを意味します。コンストラクターはクランプや推測ではなく拒否します。したがって消費側の Enterprise モジュールは、受け取ったジオメトリを再検証することは決してありません。構築されたボックスはすでに有効と分かっているからです。不変性により、共有ボックスは防御的コピーなしでモジュール間を安全に受け渡しできます。 設計背景: 推測を拒否する API。

API サーフェス

クラス	責務
BoundingBox	不変の正規化ボックス。area()、contains()、overlaps()。

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

use NextPDF\Enterprise\Common\BoundingBox;

$box = new BoundingBox(0.1, 0.1, 0.5, 0.2);
$inside = $box->contains(new BoundingBox(0.2, 0.15, 0.1, 0.02));

コードサンプル — 本番

$region = new BoundingBox($x, $y, $w, $h); // throws on out-of-range input

if ($region->overlaps($redactionZone)) {
    $logger->info('common.overlap', ['area' => $region->area()]);
}

エッジケースと注意点

• いずれかの座標を [0.0, 1.0] の外で、または x + width / y + height を 1.0 超で構築すると、引数エラーが発生します — 入力は上流で検証してください。
• 面積がゼロのボックスは決してオーバーラップしません。交差を計算する際はこれを考慮してください。
• 座標はピクセルではなく正規化されています。レンダリングの境界で変換してください。

パフォーマンス

すべての操作は、4 つの float に対する定数時間の算術演算です。

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

BoundingBox は I/O を実行せず、ドキュメントコンテンツを保持しません。コンストラクターは範囲外のジオメトリを拒否し、退化した値が消費側のモジュールへ伝播することを防ぎます。

データレジデンシーと PII の緩和策

このモジュールは個人データを保持せず、永続化やネットワーク I/O を実行しません。レジデンシーの考慮事項は適用されません。

安全なテレメトリとログのスクラブ

ボックスの座標と面積は機密でないジオメトリであり、ログに記録しても安全です。

適合性

このモジュールは規範的な標準を実装せず、適合性の主張も行いません。ジオメトリプリミティブです。

FIPS モードの挙動

このモジュールは暗号操作を実行しません。FIPS モードは適用されません。

脅威モデル

唯一の入力は 4 つの float です。コンストラクターの範囲および境界の検証が緩和策です。無効なジオメトリは構築できません。

挙動コントラクト

• BoundingBox は不変の value object であり、その 4 つの座標はページ寸法に対して [0.0, 1.0] の範囲に正規化され、解像度に依存しません。
• コンストラクターは、すべての座標が範囲内であること、および x + width と y + height が 1.0 を超えないこと (小さな浮動小数点許容誤差の範囲内) を検証し、そうでなければ引数エラーを発生させます。
• area()、contains()、overlaps() を公開します。面積がゼロのボックスは定義上決してオーバーラップしません。
• このモジュールは I/O を実行せず、ドキュメントコンテンツを保持せず、コンプライアンスや適合性の主張を行いません。

公開の境界

このページは、外部から観測できる挙動とサポート対象の公開 API サーフェスのみを説明します。内部の名前空間パス、ヘルパークラス、メカニズムの表、ランブックのファイル名、チケットプレフィックスは対象外です。

Core フォールバック

Core フォールバック — ありません。これは Enterprise 専用の共有サポートプリミティブです。Core のジオメトリを複製または置換するものではなく、Core ティアの同等品はありません。

Pro フォールバック

Pro フォールバック — ありません。この機能には Pro ティアの同等品はありません。共有 BoundingBox プリミティブは nextpdf/enterprise パッケージにのみ同梱されています。

Enterprise の境界に関する注記

検証済みのジオメトリプリミティブは、挙動レベルで記述しています。これは、他の Enterprise モジュールが利用する Enterprise 専用のサポートサーフェスです。文書化されたコントラクトを超えた内部のサブメカニズムはありません。

デプロイメントの境界

デプロイメントの境界 — 適用されるものはありません。このモジュールは永続化、ネットワーク I/O を実行せず、ドキュメントコンテンツや個人データを保持しません。このサーフェスにオペレーターが所有するリソースはありません。

法令遵守の境界

このサーフェスに輸出管理の制限は適用されません。このモジュールは規範的な標準を実装せず、適合性、認証、または規制上の主張を行いません。このドキュメントは法的見解ではありません。

関連項目

• Validation — 共有プリミティブを利用します。
• Evidence — 共有プリミティブを利用します。
• Common — Deep Reference — 共有プリミティブの詳細リファレンス。