Enterprise 版本

PHPStan

速覽

NextPDF Enterprise 隨附一條自訂 PHPStan 規則 EditionBoundaryRule，會標示跨越 Core → Pro → Enterprise 版本邊界的 use 匯入。它是一項面向開發者的靜態檢查，會回報違規；它分析匯入陳述式，但不保證你程式碼的正確性。

供應與授權

此能力隨附於 NextPDF Enterprise（nextpdf/enterprise），並以 Enterprise 層級的授權封套啟用。它是一條建置時的 PHPStan 規則，透過你的 PHPStan 設定註冊，因此在靜態分析期間執行，沒有執行階段路徑；授權閘門即是 nextpdf/enterprise 套件邊界，沒有獨立的逐功能能力碼。比較各版本並取得授權。

安裝

composer require nextpdf/enterprise:^3

在你的 PHPStan 設定中註冊此規則：

rules:
    - NextPDF\Enterprise\PHPStan\EditionBoundaryRule

概念總覽

此規則會檢視每一個 use 陳述式，並將進行匯入的命名空間與被匯入符號的命名空間前綴相比較。它強制執行一個單向的相依順序：

Core 程式碼（NextPDF\，排除 Pro 與 Enterprise 子命名空間）不得從 NextPDF\Pro\* 或 NextPDF\Enterprise\* 匯入。
Pro 程式碼（NextPDF\Pro\*）不得從 NextPDF\Enterprise\* 匯入。
Enterprise 程式碼（NextPDF\Enterprise\*）是最頂層，可從其中任何一個匯入。

當某個匯入跨越邊界時，規則會回報一則帶有識別碼 nextpdf.editionBoundaryViolation 的錯誤，並在訊息中指名進行匯入的命名空間、被禁止的前綴，以及人類可讀的版本標籤。此檢查為純靜態：它在分析時讀取匯入圖。

為何以這種方式運作

此規則在分析時而非執行階段推論 use 陳述式，因為版本邊界是一項架構不變量，而非執行階段決策。Core、Pro 與 Enterprise 以各自獨立的套件出貨，因此較低層級絕不可相依於較小型安裝中不存在的符號。在靜態分析期間攔截跨越邊界的匯入，會在錯誤出貨之前使建置失敗。另一種做法更糟：同一個匯入日後會在僅有 Core 的部署中，浮現為一個致命的類別缺失錯誤。此順序刻意設計為單向的 Core → Pro → Enterprise，反映 open-core 套件彼此層疊的方式。Enterprise 維持不受限制，因為它是最頂層，可參考其下的每一個版本。

設計背景：開放核心，絕不鎖定。

API 介面

類別	職責
`EditionBoundaryRule`	針對 `use` 陳述式的 PHPStan 規則；回報版本邊界違規。

此規則在 Use_ 節點類型上實作標準的 PHPStan Rule 合約，並在 nextpdf.editionBoundaryViolation 識別碼下發出錯誤。

程式碼範例——快速上手

# phpstan.neon
includes:
    - vendor/nextpdf/enterprise/phpstan.neon.dist

程式碼範例——正式環境

# phpstan.neon
rules:
    - NextPDF\Enterprise\PHPStan\EditionBoundaryRule

parameters:
    level: 9
    paths:
        - src

舉例而言，違規會出現在 PHPStan 輸出中：Core 程式碼內的一個 Enterprise 匯入，會在違規的 use 行上、於 nextpdf.editionBoundaryViolation 下，被回報為版本邊界違規。

邊界案例與陷阱

此規則會推論被分析檔案的命名空間與被匯入符號的前綴。位於非 NextPDF\ 命名空間的程式碼不受此規則約束。
Enterprise 命名空間在設計上不受限制；此規則絕不會因 Enterprise 檔案匯入 Pro 或 Core 而標示它。
此規則分析 use 陳述式。在未使用 use 的情況下以行內方式寫出的完整限定類別參考，不在此規則的範圍內；請偏好使用匯入，以便強制執行邊界。
此檢查是靜態且建議性的：它回報邊界違規。它不證明你的程式在其他方面正確無誤。

效能

此規則會在 PHPStan 分析期間，針對每一個 use 陳述式執行，並進行字串前綴比較。它的額外開銷與匯入陳述式的數量成正比，且相對於整體分析時間可忽略不計。

安全注意事項

這是一條靜態分析規則。它在建置時於 PHPStan 內執行，僅讀取原始碼結構，並對產出的 PDF 沒有任何執行階段影響。

資料落地與 PII 緩解措施

此規則在分析時處理原始碼，並不處理任何文件或個人資料。

安全遙測與日誌清洗

規則輸出是 PHPStan 診斷。它含有來自你自己程式碼的命名空間與符號名稱；請以對待你原始碼的同等謹慎對待分析日誌。

一致性

不主張任何標準一致性。這是一條開發者工具規則，在下游建置中強制執行一項內部架構約束（版本分層）。

FIPS 模式行為

不適用；此規則不進行任何加密運算，且沒有執行階段路徑。

威脅模型

並非執行階段元件。此規則的目的是在出貨前，藉由使靜態分析階段失敗，來攔截一項架構錯誤——一個版本邊界匯入。

行為合約

此規則會檢視每一個 use 陳述式，並強制執行一個單向的相依順序：Core 不得匯入 Pro 或 Enterprise；Pro 不得匯入 Enterprise；Enterprise 可匯入任何一個。
跨越邊界的匯入會在 nextpdf.editionBoundaryViolation 識別碼下回報，並帶有進行匯入的命名空間與被禁止的前綴。
位於非 NextPDF\ 命名空間的程式碼不受此規則約束。
未使用 use 的行內完整限定類別參考不在此規則的範圍內；請偏好使用匯入，以便強制執行邊界。

發布邊界

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

Core 回退

NextPDF Core 不隨附版本邊界 PHPStan 規則。想在自己的建置中強制執行版本分層的僅有 Core 的使用者，必須自行撰寫或取得一條等價規則。

Pro 回退

NextPDF Pro 不隨附版本邊界 PHPStan 規則；它僅屬於 nextpdf/enterprise 套件。僅有 Pro 的部署沒有任何 Enterprise 元件可從中註冊此規則。Enterprise 介面請參閱 Enterprise 總覽。

Enterprise 邊界註記

內部機制細節保留在原始碼儲存庫的內部文件中，不在本手冊的範圍內。

部署邊界

這是一條建置時的靜態分析規則。它在分析期間於 PHPStan 內執行，僅讀取原始碼結構，並對產出的 PDF 或任何已部署的服務沒有任何執行階段影響。註冊它並選擇 PHPStan 層級是整合者的責任。

法律合規邊界

本頁描述一條開發者工具靜態分析規則。它對你的程式碼不做任何合規、認證或正確性的保證；它僅回報版本邊界匯入違規，且為建議性。它不構成法律建議。判斷你的建置是否符合你自己的架構或合約義務是你的責任。