SPI 穩定性規則

概覽

NextPDF 的服務供應者介面遵循語意化版本（Semantic Versioning）。每個公開合約都帶有一個 @stability 標記與一份向後相容承諾。本頁說明這些規則，讓你判斷哪些內容可以作為依賴。

安裝

composer require nextpdf/core:^3

概念總覽

服務供應者介面指的是 NextPDF\Contracts 與 NextPDF\Event 命名空間中的一組公開合約。只有當型別的原始碼 PHPDoc 帶有 @stability 標記時，該型別才屬於這個介面。這個標記就是邊界。沒有這個標記的型別屬於內部用途，即使它在 PHP 中技術上是 public 也一樣。

NextPDF 遵循語意化版本（Semantic Versioning）2.0.0。對 stable 合約的破壞性變更會遞增主版本。新增合約或非破壞性的新增會遞增次版本。錯誤修正會遞增修補版本。

@stability 標記

每個合約都會宣告以下三種穩定性值之一：

標記	意義	變更規則
`stable`	可用於正式環境。可放心依賴。	在次版本或修補版本中不會有破壞性變更。新方法只會帶著預設行為加入，或加在新的合約上。
`experimental`	可使用，但尚未凍結。	此介面可能在次版本中變更，但會先發出棄用通知。
`deprecated`	已排定移除。	合約會載明替代方案與移除版本。

各合約的承諾會記錄在產生出的合約對映表（contracts map）中，並在每次發行時都從原始碼重新產生。承諾文字會載明該合約確切的規則。請將合約原始碼中的 PHPDoc 視為唯一真實來源。

向後相容承諾的類別

合約對映表記錄了這份承諾。承諾分為四種類別：

介面承諾。 「在次版本或修補版本中不會有破壞性變更。新方法只會帶著預設實作加入。」適用於大多數 stable 介面，包括 FontRegistryInterface、SignerInterface、HsmSignerInterface 與 HtmlSecurityPolicyInterface。
列舉承諾。 「不移除任何 case。次版本中可能會新增 case。」適用於 stable 的列舉，例如 Alignment、Orientation 與 OutputDestination。
凍結值物件承諾。 「建構式簽章與公開屬性都已凍結。可能會新增方法。」適用於值物件，例如 TextPreprocessResult、TextSegment，以及與其繫結的事件酬載。
實驗性承諾。 「此介面可能在次版本中變更，但會先發出棄用通知。」適用於 experimental 合約，例如 DeferredSignerInterface、TimestampProviderInterface、CursorInterface 與 StreamingWriterInterface。

例如 EventDispatcher 或 ListenerProvider 這類 final 類別，會凍結其公開方法的簽章。請以組合（composition）的方式擴充 final 類別。不要為它建立子類別。

實驗性的串流合約

CursorInterface 與 StreamingWriterInterface 為 experimental（自 3.1.0 起）。NextPDF 為這兩個合約都提供一份最終版且已測試的引擎實作；這些實作類別屬於內部實作，不是公開介面的一部分。你透過公開的 experimental 合約來使用串流行為。在常見情況下，你不需要自行實作這份合約。

因為這份合約是 experimental，其簽章可能在次版本中變更，但會先發出棄用通知（即實驗性承諾）。在正式環境依賴它之前，請鎖緊版本，或用自己的轉接器（adapter）把它包起來。請把這個串流合約視為仍在穩定中的擴充點，而不是已凍結的擴充點。

API 介面

本頁沒有執行期 API。相關的介面是每個公開合約上的 @stability PHPDoc 標記，以及重新產生、彙整各合約承諾的合約對映表。

程式碼範例 — 快速上手

依賴某個合約之前，請先從其原始碼讀取它的穩定性。

<?php

declare(strict_types=1);

use ReflectionClass;

$doc = (new ReflectionClass(\NextPDF\Contracts\FontRegistryInterface::class))
    ->getDocComment();

// Look for the "@stability stable" line in the contract PHPDoc.
\assert(\is_string($doc) && \str_contains($doc, '@stability stable'));

程式碼範例 — 正式環境

Composer 的版本限制條件會鎖定主版本，而主版本正是 stable 合約破壞性變更的單位。

{
    "require": {
        "nextpdf/core": "^3.0"
    }
}

鎖定到 ^3.0，即可接收次版本與修補版本更新，而不會對任何 stable 合約造成破壞性變更。當你依賴 experimental 合約時，請鎖得更緊，因為 experimental 合約可能在次版本中變更。

邊界情況與陷阱

是標記，不是可見性。 一個 public 的 PHP 方法，除非其宣告型別帶有 @stability 標記，否則並不屬於服務供應者介面。
實驗性漂移。 一個 experimental 合約可能在次版本中變更。請鎖緊版本，或用自己的轉接器把它包起來。即使串流合約已隨附實作，這一點仍然適用於它們。
新增的預設方法。 一個 stable 介面可能會新增一個帶有預設行為的方法。升級時請實作這個新方法，讓自己的實作保持明確。
版本一致性。 NextPDF Pro 與 NextPDF Enterprise 遵循相同的規則。你在 Core 中對接的合約，對於同一份合約的 Premium 實作仍然有效。

棄用生命週期

合約會經過一套明確定義的生命週期：

標示。 維護者在原始碼 PHPDoc 中設定 @stability deprecated，並記錄替代方案與移除版本。
通知。 棄用會在標示它的那次發行中於變更日誌（changelog）公告。
並存。 已棄用的合約與其替代方案會至少並存一個次版本。
移除。 合約會在所載明的主版本中移除。移除絕不會在次版本或修補版本中發生。

一旦某個合約被標示為 deprecated，就請盡早規劃升級。替代方案一律都會載明。

效能

本頁定義的是政策，沒有執行期成本。

安全性注意事項

簽署合約為 stable，並遵循介面承諾。簽署合約上的新方法只會帶著預設行為加入，或加在新合約上，因此硬體支援的實作不會因為次版本升級而中斷。在進行主版本升級前，請審閱變更日誌，因為主版本可能會變更 stable 合約。

符合性

此版本規則符合語意化版本（Semantic Versioning）2.0.0。變更日誌的產生遵循約定式提交（Conventional Commits）1.0.0。

商業情境

NextPDF Pro 與 NextPDF Enterprise 遵循與 Core 相同的服務供應者介面穩定性規則。你在 Core 中對接的合約，對於該合約的 Premium 實作仍然有效，因此你的擴充程式碼可在不同版本之間移植。