Release — 深入參考

概覽

NextPDF\Enterprise\Release 命名空間將產品發行建模為不可變、具型別的值物件。其公開介面是七個 final class 與五個字串背後值的列舉。ReleaseManifest 匯總逐成品的 ArtifactManifest 項目以及供應鏈佐證路徑。BuildProfile 是單一成品變體的單一事實來源。ArtifactNamer 與 PackageMapping 由設定檔衍生出決定性的檔名與 Composer 套件識別。PublishingPlan::fromProfiles 會將每個設定檔解析為具型別的 PublishingTarget 項目，並帶有正確的通道與存取邊界。ReleaseStatus 為發行生命週期定型。本模組不執行任何 I/O、不進行網路呼叫，也不涉及密碼學；它純粹是中繼資料建模。

供應與授權

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

此介面由 nextpdf/enterprise 套件邊界授權，沒有獨立的逐功能能力代碼。Core 與 Pro 不隨附發行建模層。

公開 API 介面

composer require nextpdf/enterprise:^3

符號	參數	預設行為	回傳	拋出或失敗於	備註
ReleaseManifest::__construct	version, sourceCommit, builtAt, artifacts = [], sbomPath = null, gpgSignature = null, checksumPath = null	建立不可變的頂層發行文件	實例	—	final readonly；SCHEMA_VERSION 為 '1.0'；新增欄位為次版號、破壞性變更為主版號；自 3.0.0 起
ReleaseManifest::createWithDefaults	string $version, string $sourceCommit, DateTimeImmutable $builtAt, array $artifacts = []	透過 ArtifactNamer 預先接上預設的 SBOM、簽章與 checksum 檔名	self	—	發行建置器的正規進入點；若要覆寫個別路徑請使用建構子
ReleaseManifest::toArray / ::toJson	無	將資訊清單連同所有成品項目序列化	array / JSON 字串	toJson：編碼失敗時拋出 JsonException	美化輸出、不轉義斜線；built_at 採 ATOM 格式
ReleaseManifest::validate	無	檢查成品清單非空，且每個成品都與發行版本與 commit 相符	錯誤的 list<string>；空清單即代表有效	永不拋出	呼叫端必須將非空清單視為缺陷
ArtifactManifest::__construct	filename, version, sourceCommit, edition, deliveryMode, encodingTechnology, channel, phpTarget, sha256, ioncubeExpire, builtAt	記錄單一已建置成品：建置了什麼、如何建置，以及如何驗證它	實例	—	final readonly；不到期的成品其 ioncubeExpire 為 null
ArtifactManifest::fromProfile	BuildProfile $profile, string $version, string $sourceCommit, string $sha256, ?DateTimeImmutable $builtAt = null	衍生檔名與所有設定檔維度	self	—	builtAt 預設為目前時間
ArtifactManifest::toArray	無	為 JSON 編碼進行序列化	array<string, string|null>	—	列舉欄位序列化為其背後的字串值
BuildProfile::__construct / ::fromArray	設定檔欄位 / array $data	定義單一成品變體；命名、資訊清單與計畫的單一事實來源	實例 / self	fromArray：必要欄位缺漏或為空時拋出 InvalidArgumentException	必要鍵：name、edition、delivery、encoding_technology、channel、php_target
BuildProfile::requiresEncoding / ::isEvaluation	無	針對設定檔維度的述詞輔助方法	bool	—	編碼需同時具備 DeliveryMode::Encoded 與 EncodingTechnology::IonCube
ArtifactNamer::format	BuildProfile $profile, string $version	產生 nextpdf-{edition}-{delivery}-{channel}-php{target}-{version}.zip	non-empty-string	—	決定性的；PHP 目標版本會移除點號（8.4 變成 php84）
ArtifactNamer::checksumFile / ::signatureFile / ::sbomFile / ::manifestFile	string $version（manifestFile：無）	產生 SHA256SUMS-{v}.txt、SHA256SUMS-{v}.txt.asc、sbom-{v}.cdx.json、release-manifest.json	non-empty-string	—	此 SBOM 檔名與 Core 的 SBOM 產生器所寫出的 CycloneDX 文件相符
PackageMapping::packageName / ::resolvePackageName	BuildProfile / LicenseEdition + LicenseChannel	對應到 nextpdf/pro 或 nextpdf/enterprise；評估通道會附加 -evaluation	non-empty-string	版本未知時拋出 InvalidArgumentException	獨立的評估命名空間可避免與付費成品混雜
PackageMapping::distUrlPattern	BuildProfile $profile, string $version	解析成品在正規成品倉庫上的下載 URL	non-empty-string	—	編碼版與明文版共用套件名稱；但兩者的 dist URL 不同
PackageMapping::accessBoundary / ::artifactOrigin / ::consumptionChannel / ::allPackageNames	BuildProfile / 無 / 無 / 無	邊界依循授權通道；固定的來源與取用通道；所有面向客戶的套件名稱	AccessBoundary / DistributionChannel / DistributionChannel / list<non-empty-string>	—	Core 不是 premium 套件，會被排除於名稱清單之外
PublishingPlan::fromProfiles	array $profiles, string $version, PublishingEnvironment $environment = Staging	每個設定檔解析出兩個目標：一個成品來源、一個取用層	self	—	環境預設為 Staging；正式環境一律需明確指定
PublishingPlan::targetsByBoundary / ::targetsByChannel / ::packageNames	AccessBoundary / DistributionChannel / 無	針對已解析目標的篩選與列舉輔助方法	list<PublishingTarget> / list<PublishingTarget> / list<non-empty-string>	—	packageNames 會排序並去除重複
PublishingPlan::validate	無	檢查目標非空、版本與計畫相符，且沒有評估套件落在付費邊界內	錯誤的 list<string>；空清單即代表有效	永不拋出	在任何上傳步驟之前執行
PublishingPlan::toArray	無	為試跑輸出與記錄進行序列化	array<string, mixed>	—	包含 target_count 與套件清單
PublishingTarget::fromProfile	BuildProfile $profile, string $version, PublishingEnvironment $environment, DistributionChannel $channel	為單一通道解析套件名稱、存取邊界與成品檔名	self	—	final readonly；toArray 為記錄進行序列化
AccessBoundary	列舉：Paid、Evaluation、Internal	isCustomerFacing 只有在 Paid 與 Evaluation 時為 true	背後值為 'paid'、'evaluation'、'internal'	—	requiresAuthentication 對每個邊界都回傳 true
DistributionChannel	列舉：GitHubReleases、PrivatePackagist、DirectDownload	isArtifactOrigin 與 isConsumptionLayer 區分這兩種角色	背後值為 'github_releases'、'private_packagist'、'direct_download'	—	DirectDownload 保留給未來的簽章 URL 通道
EncodingTechnology	列舉：IonCube、None	指出編碼工具，與交付形式有所區別	背後值為 'ioncube'、'none'	—	明文成品一律回報 None
PublishingEnvironment	列舉：Staging、Production	isCustomerFacing 只有在 Production 時為 true	背後值為 'staging'、'production'	—	Staging 是內部驗證目標
ReleaseStatus	列舉：Built、Audited、Staged、Published、Revoked、Superseded	canPromote、nextStatus、isCustomerVisible、isTerminal 為生命週期定型	nextStatus 回傳 ?self	—	晉升鏈為 Built → Audited → Staged → Published；Revoked 與 Superseded 為終端狀態

進入點簽章，逐字取自原始碼：

public static function createWithDefaults(string $version, string $sourceCommit, DateTimeImmutable $builtAt, array $artifacts = []): self

public static function fromProfile(BuildProfile $profile, string $version, string $sourceCommit, string $sha256, ?DateTimeImmutable $builtAt = null): self

public static function fromArray(array $data): self

public static function format(BuildProfile $profile, string $version): string

public static function fromProfiles(array $profiles, string $version, PublishingEnvironment $environment = PublishingEnvironment::Staging): self

public static function fromProfile(BuildProfile $profile, string $version, PublishingEnvironment $environment, DistributionChannel $channel): self

行為合約

• 每個 class 都是 final；每個值類別都是 readonly。建構時即固定所有狀態。本模組不執行任何檔案系統、網路或密碼學操作。
• ReleaseManifest 是某個版本的不可變頂層文件：語意版本號、來源 commit、建置時間戳記、成品清單，以及選用的供應鏈佐證路徑（SBOM、GPG 簽章、checksum）。其結構描述版本採「新增為次版號、破壞性變更為主版號」。
• BuildProfile 是「一個成品包含什麼、如何封裝」的單一事實來源。命名、資訊清單與計畫全都由此設定檔衍生；沒有第二個組態來源。
• EncodingTechnology 指出編碼工具；DeliveryMode（來自 Licensing 模組）指出交付的形式。兩者刻意分開，且明文成品一律回報 EncodingTechnology::None。
• DistributionChannel 將成品來源（二進位儲存；上傳目的地）與套件取用層（composer require 所讀取的登錄）分離開來。來源儲存二進位檔；取用層提供指向它的中繼資料。
• AccessBoundary 列舉 Paid、Evaluation 與 Internal。每個邊界都需要驗證。Internal 成品服務於 CI、QA 與 staging，永不面向客戶。
• PublishingPlan::fromProfiles 會將每個設定檔精確解析為兩個目標：一個成品來源目標與一個取用層目標，其存取邊界由設定檔的授權通道衍生，讓付費與評估成品正確路由。
• 此計畫描述的是預期的目標，而非傳輸。實際上傳由周邊的發行工具執行，而資訊清單記錄（但本身不產生）供應鏈佐證。
• ReleaseStatus 為生命週期定型：Built → Audited → Staged → Published，Revoked 與 Superseded 為自 Published 的終端出口。只有 Published 面向客戶可見；自 Published 起 canPromote 為 false。
• ReleaseManifest::validate 與 PublishingPlan::validate 以字串清單回報一致性錯誤，且永不拋出。空清單是唯一有效的結果。

邊界案例與失敗模式

• BuildProfile::fromArray 若遇到必要欄位缺漏、非字串或為空：拋出點名該欄位的 InvalidArgumentException。
• BuildProfile::fromArray 若 ioncube_expire 為空或非字串：正規化為 null（不到期）。encode_paths 與 exclude_paths 中非字串或為空的項目會被靜默捨棄。
• PackageMapping::resolvePackageName 若版本不在已知對應中：拋出 InvalidArgumentException。
• ReleaseManifest::toJson 遇到無法編碼的資料：拋出 JsonException。序列化使用 JSON_THROW_ON_ERROR；沒有靜默的退回機制。
• ReleaseManifest::validate 會將空的成品清單，以及任何版本或來源 commit 與發行不符的成品，回報為錯誤。
• PublishingPlan::validate 會回報空的目標清單、任何與計畫分歧的目標版本，以及任何被解析到付費邊界內的評估套件。
• ReleaseStatus::nextStatus 在 Published、Revoked 與 Superseded 時回傳 null。呼叫端必須處理 null；沒有循環回繞。
• 來源通道與取用層通道各自獨立；請勿將 composer require 指向成品來源。
• Internal 邊界的成品永不面向客戶；將其路由到客戶通道是明確的建模錯誤。
• 本模組不執行任何密碼學操作。GPG 簽署與 checksum 產生屬於外部作業，此處僅作參照。

一致性

本模組不主張任何標準一致性；它是一個發行建模層，且 NextPDF 未持有任何認證。預設的 SBOM 檔名（sbom-{version}.cdx.json）與 Core 的 SBOM 產生器所寫出的 CycloneDX 文件相符；資訊清單參照該佐證，但不驗證它。GPG 簽章與 checksum 由周邊的發行管線產生與驗證。記錄佐證路徑是一種能力，而非證明：資訊清單本身不是證明、不證明來源、不認證任何發行，也不構成法律建議。

開發注意事項

• 偏好使用 ReleaseManifest::createWithDefaults，讓佐證檔名始終與 ArtifactNamer 一致。原始建構子則保留給刻意的逐路徑覆寫。
• 在任何發布步驟之前於 CI 執行兩個 validate() 閘門，並在錯誤清單非空時讓管線失敗。
• PublishingPlan::fromProfiles 預設為 PublishingEnvironment::Staging。請明確傳入 Production；本模組不會隱含地晉升環境。
• 已序列化的資訊清單帶有列舉背後值（paid、encoded、ioncube 等）與 ATOM 時間戳記；請將這些字串視為傳輸協定契約。
• 評估成品位於獨立的套件命名空間（-evaluation 後綴）。請在你的 Composer 組態中將付費與評估登錄分開。
• 逐通道的路由、憑證與儲存是操作者的責任。計畫告訴工具成品該歸屬何處，而非如何對它進行驗證。

發布邊界

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

另請參閱

• Release（能力頁）
• Licensing — 深入參考 — 設定檔所取用的 LicenseEdition、LicenseChannel 與 DeliveryMode 列舉。
• Enterprise 概觀
• 授權啟用