Common — 深入參考

概覽

本頁是 NextPDF\Enterprise\Common 命名空間的深入參考。此命名空間僅提供一個公開符號：BoundingBox 值物件。它是一個不可變、正規化的矩形，用於在頁面上進行與解析度無關的空間定位。Enterprise Intelligence 與 Privacy 介面會使用它來表示表格儲存格幾何、實體位置與遮蔽區域。此模組不執行任何 I/O、不持有任何文件內容，也不涉及任何密碼學運算。若需工作流程指引，請先閱讀 Common 能力頁面。

供應與授權

此能力隨 NextPDF Enterprise（nextpdf/enterprise）提供，並在具備 Enterprise 層級授權封套時啟用。缺少該授權的部署不會載入此能力的類別。比較版本並取得授權。

此原語本身不執行任何授權閘控；閘控發生在使用它的 Enterprise 介面上。此類別沒有 Core 層級或 Pro 層級的對應物。它僅隨 nextpdf/enterprise 套件提供，且不重複或取代 Core 的幾何型別。

公開 API 介面

符號	參數	預設行為	回傳	拋出或失敗於	備註
BoundingBox::__construct	float $x、float $y、float $width、float $height	先驗證每個值是否落在 [0.0, 1.0]，再驗證兩個邊緣總和	BoundingBox	當某個值超出範圍，或某個邊緣總和超過 1.0 + 1e-9 時拋出 InvalidArgumentException	四個值都會成為 public readonly 屬性
BoundingBox::area	無	將 width 乘以 height	float	未宣告任何項目	對退化方框回傳 0.0
BoundingBox::contains	self $other	測試 $other 是否完全落在此方框內	bool	未宣告任何項目	右緣與下緣容許 +1e-9；左緣與上緣以精確方式比較
BoundingBox::overlaps	self $other	測試嚴格的矩形相交	bool	未宣告任何項目	任一側為零面積運算元時回傳 false

進入點簽章

final readonly class BoundingBox
{
    public function __construct(
        public float $x,
        public float $y,
        public float $width,
        public float $height,
    )

    public function area(): float

    public function contains(self $other): bool

    public function overlaps(self $other): bool
}

行為合約

座標模型

• 四個值都是頁面尺寸的分數，正規化到 [0.0, 1.0] 範圍。
• x 定位方框的左緣，y 定位方框的上緣。x + width 與 y + height 界定右緣與下緣。
• 正規化讓每個運算都與解析度無關。同一個方框在任何算繪尺寸或 DPI 下都指向相同的頁面區域。

建構

• 建構子是唯一的驗證點。座標超出 [0.0, 1.0] 會引發 InvalidArgumentException；訊息會指出出問題的元件與收到的值。
• 邊緣總和超過 1.0 + 1e-9 會引發 InvalidArgumentException；訊息會回報兩個運算元及其總和。1e-9 容差用於吸收上游正規化運算的浮點捨入誤差。
• 建構完成的實例是不可變的。此類別為 final readonly，因此寫入屬性會以 PHP Error 失敗，且此類別無法被擴充。

述詞

• area() 回傳 width * height。它是純運算，沒有任何副作用。
• contains() 在另一個方框完全落在此方框內時回傳 true。右緣與下緣的比較帶有 +1e-9 容差；左緣與上緣的比較則為精確。每個方框都包含自身，而零面積的方框也可以被包含。
• overlaps() 在嚴格矩形相交時回傳 true。四個邊緣的比較全部為嚴格，沒有任何容差。若任一運算元為零面積，結果為 false。
• 因此包含並不蘊含重疊：位於另一個方框內的退化方框會被包含，但永遠不會重疊。
• 沒有任何方法會執行 I/O、持久化、網路存取或記錄，也沒有任何方法持有文件內容或個人資料。此介面沒有任何由操作者擁有的資源。

使用方

Enterprise 模組共用此原語，而非各自定義各模組的幾何。在 Intelligence 中，TableExtractor 的輸出會將它帶在 TableCell 與 KeyValuePair 值上。在 Privacy 中，PiiEntity、RedactionFinding 與 ZoneRedaction 會用它來定位內容，而 RedactionEngine 會使用這些位置。這些介面的合約記載於它們各自的參考頁面上。

邊界案例與失敗模式

• 超出範圍的元件。 四個值中任一個低於 0.0 或高於 1.0，都會在建構時引發 InvalidArgumentException。INF 與 -INF 會被同一道防護拒絕。
• 邊緣總和溢位。 x + width 或 y + height 高於 1.0 + 1e-9 會引發 InvalidArgumentException。落在 1e-9 容差內的總和則能成功建構。
• NAN 輸入。 範圍防護使用有序比較，而任何與 NAN 的有序比較皆為 false，因此 NAN 元件不會被拒絕。此類實例會回報 NAN 面積，且兩個述詞都會回傳 false。請在建構前先清理上游的浮點來源。
• 零面積方框。 寬度或高度為零的方框永遠不會與任何東西重疊，包括自身。它仍然可以被非退化的方框包含。請在相交邏輯中將此不對稱性納入考量。
• 邊緣接觸的方框。 只共用一條邊或一個角的兩個方框不會重疊；相交測試為嚴格。
• 包含容差的不對稱性。 內方框的左緣或上緣只要有任何程度落在外方框之外，就無法通過包含；只有右緣與下緣會獲得 1e-9 的寬容。
• FIPS 模式。 此模組不執行任何密碼學運算；FIPS 模式不會改變其行為。

一致性

本模組未實作任何規範性標準，也不做任何一致性聲明。它是一個經驗證的幾何原語。使用它的功能所涉及的 PDF 座標空間語意，記載於那些功能各自的頁面上。NextPDF 未持有任何認證，也不授予任何認證；支援不等於一致性，一致性也不等於認證。此介面不適用任何出口管制限制，且本參考並非法律意見。

開發註記

• 此類別自 nextpdf/enterprise 2.2.0 起提供；其公開介面在 3.1.0 中維持不變。
• 請在建構前將絕對頁面空間座標轉換為相對於頁面的分數。此類別驗證的是範圍，而非語意；它無法偵測合理但錯誤的區域。
• 實例是單純的值物件，建構成本低廉。請勿將它們池化或快取。
• 兩個座標相同的實例在鬆散相等（==）下比較為相等；嚴格相同（===）則能區分它們。在測試中請優先使用座標比較。
• 若需要布林述詞以外的幾何，請從公開屬性推導邊緣：右緣為 x + width，下緣為 y + height。
• 測試容差邊界時，請在邊緣總和防護以及包含的右/下緣比較上，探測 1e-9 的兩側。

發佈邊界

本頁僅記載外部可觀察的行為與受支援的公開 API 介面。內部命名空間路徑、輔助類別、機制表、runbook 檔名與工單前綴皆不在範圍內。

另請參閱

• Common 能力頁面
• Intelligence — 深入參考
• Privacy — 深入參考
• Validation — 深入參考
• Evidence — 深入參考