Branding — 深入參考

概覽

本頁是 NextPDF\Enterprise\Branding 模組的深入參考。此模組會標記評估輸出，並讓付費輸出保持原封不動。由授權解析而得的 BrandingMode 會選定一個策略；BrandingApplicator 會將解析出的策略套用到已渲染的 PDF 位元組上。在付費授權下，此轉換即為恆等轉換：輸出逐位元組完全不變，且不需要任何程式碼變更。若要了解評估工作流程，請先閱讀品牌標示能力頁。

可用性與授權

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

此子系統帶有專屬的 enterprise.branding 能力碼，因為它管轄所有版本的評估行為。品牌標示模式在執行階段從簽署過的授權封套解析而來；沒有任何應用程式旗標選定它。付費授權會將模式解析為 None，且絕不會產生帶品牌標示的輸出。不存在任何可切換的正式環境建置。

公開 API 介面

符號	參數	預設行為	回傳	拋出或失敗於	備註
BrandingMode	—	None（'none'）：不做任何修改	—	—	以字串為底的 enum；EvaluationWatermark（'evaluation'）啟用評估品牌標示。
BrandingStrategy	—	由整合點所使用的合約	—	—	介面；呼叫端絕不直接對 BrandingMode 分支。
BrandingStrategy::isActive	—	null 策略為 false，評估策略為 true	bool	—	false 表示其他每個方法都回傳恆等值。
BrandingStrategy::buildPageWatermark	float $pageWidth、float $pageHeight（點）	未啟用時為空字串；啟用時為對角浮水印運算子	string	—	串流假設頁面上有一個 /helvetica 字型資源。
BrandingStrategy::decorateProducer	string $producer	未啟用時為恆等；啟用時附加評估後綴	string	—	預設後綴： [EVALUATION]。
BrandingStrategy::decorateSubject	string $subject	未啟用時為恆等；啟用時前置評估前綴	string	—	空的 subject 會產生修剪過的標記。
BrandingStrategyFactory::create	BrandingMode $mode、?EvaluationBrandingConfig $config = null	將 None 對應為 NullBrandingStrategy，EvaluationWatermark 對應為 EvaluationBrandingStrategy	BrandingStrategy	—	靜態；null 設定使用預設值。
EvaluationBrandingConfig::__construct	六個選用的具名參數（text、suffix、prefix、size、gray、angle）	預設值：48 pt、gray 0.85、45 度	實例	文字為空、字型大小非正、或 gray 超出 0.0–1.0 時拋出 InvalidArgumentException	final readonly；不可變。
EvaluationBrandingStrategy	選用的 EvaluationBrandingConfig	套用浮水印與中繼資料裝飾	—	—	final readonly；實作 BrandingStrategy。
NullBrandingStrategy	—	每個方法皆為恆等	—	—	在付費授權下被選定。
BrandingApplicator::apply	string $pdfBytes、BrandingStrategy $strategy	未啟用策略：逐位元組回傳輸入；已啟用：附加一次增量更新	string	啟用的品牌標示無法安全套用時拋出 BrandingApplicationException	純粹、確定性的位元組轉換。
BrandingApplicationException	—	終端、fail-closed 的失敗訊號	—	—	帶有 SPEC_CODE（SPEC-BRANDING-UNAPPLICABLE）；工廠方法 unsupportedStructure()。

進入點簽章

enum BrandingMode: string
{
    case None = 'none';
    case EvaluationWatermark = 'evaluation';
}

public static function create(
    BrandingMode $mode,
    ?EvaluationBrandingConfig $config = null,
): BrandingStrategy

public function __construct(
    public string $watermarkText = 'EVALUATION COPY — Not for Production Use',
    public string $producerSuffix = ' [EVALUATION]',
    public string $subjectPrefix = '[EVALUATION] ',
    public float $watermarkFontSize = 48.0,
    public float $watermarkGray = 0.85,
    public float $watermarkAngle = 45.0,
)

public function apply(string $pdfBytes, BrandingStrategy $strategy): string

行為合約

模式與策略解析。 由授權狀態——而非應用程式碼——選定 BrandingMode。BrandingStrategyFactory::create 會將 None 對應為 NullBrandingStrategy，EvaluationWatermark 對應為 EvaluationBrandingStrategy。整合點使用 BrandingStrategy 介面，且絕不直接檢查模式，因此品牌標示邏輯保持集中。在付費授權下會選定 null 策略，且輸出與「完全沒有品牌標示子系統時所產生的輸出」完全相同。

浮水印產生。 buildPageWatermark 會為單一頁面發出 PDF 內容串流運算子：一個隔離的圖形狀態（q/Q）、透過 /helvetica 資源名稱使用的 standard-14 Helvetica 字型、填色文字渲染模式，以及一個將文字對角穿過頁面中心的旋轉矩陣。預設樣式為 48 pt 文字、gray 等級 0.85，旋轉 45 度。置中是以字符數量近似文字寬度——載入 intl 時使用字素叢集（grapheme cluster）、否則透過 mbstring 使用 Unicode 碼位、位元組長度則作為最終後備。依設計不查閱任何逐字符的前進寬度。浮水印文字會依 ISO 32000-2:2020 §7.3.4.2 轉義為 PDF literal string（反斜線與括號）。

中繼資料裝飾。 decorateProducer 會將 producer 後綴附加到 /Producer 值。decorateSubject 會將 subject 前綴前置到 /Subject 值；空的 subject 會產生修剪過的標記，因此即使文件沒有 subject 中繼資料仍會被標記。

位元組套用。 BrandingApplicator::apply 是品牌標示控制的終端使用者。在未啟用策略下，它會逐位元組回傳輸入。在已啟用策略下，它會附加一次符合 ISO 32000-2:2020 §7.5.6 所定義形狀的增量更新：原始位元組保持原封不動，附加的主體則含有一個經裝飾的 Info 物件（重用既有的物件編號）、每頁一個浮水印內容串流加一個已更新的頁面物件，以及一個新的交叉參照串流（/Type /XRef、/W [1 4 2]），其 /Prev 指回先前的 startxref。對於給定的輸入與設定，此轉換是純粹且確定性的。

Fail-closed 合約。 當策略為啟用時，輸入必須可被標示：具有 %PDF- 標頭、無 /Encrypt 項目、無物件串流（/ObjStm）、具交叉參照串流尾端，且每一頁都能解析出 /helvetica 字型資源。任何違反皆會拋出 BrandingApplicationException，而非回傳未標示的位元組。呼叫端必須將此例外視為終端，且不得提交原始、未標記的位元組。

邊界案例與失敗模式

• 帶品牌標示的輸出表示授權狀態為評估型。這反映的是授權狀態，而非缺陷。
• 浮水印在設計上置中且對角。它不可為正式環境調校；付費授權會將其完全移除。
• EvaluationBrandingConfig 會以 InvalidArgumentException 拒絕空的浮水印文字、非正的字型大小，以及超出 0.0–1.0 的 gray 等級。
• 一個啟用的策略若未產生任何 Producer、Subject 或浮水印變更，會被以 BrandingApplicationException 拒絕，而非發出看似付費的位元組。
• 沒有可用 /MediaBox（缺失或繼承而來）的頁面，會以 ISO 216 A4 預設值 595.276 × 841.890 點加上浮水印。
• 單一參照與陣列兩種形式的 /Contents 皆受支援；浮水印參照會被附加在最後，因此它會繪製在最上層。沒有 /Contents 的頁面會獲得一個。
• Info 字串值會以其原始表示形式往返：十六進位字串（UTF-16BE）保持十六進位，literal string 保持 literal。缺失的鍵會被附加，並在值含有非 ASCII 字元時以十六進位編碼。
• 加密的文件會被拒絕：在 /Encrypt 下改寫字串物件將需要文件加密金鑰。
• 失敗會帶有穩定碼 SPEC-BRANDING-UNAPPLICABLE（BrandingApplicationException::SPEC_CODE），因此使用端的管線可以對無法標示的輸出進行 dead-letter 與稽核。
• 此模組不進行任何加密運算。授權封套簽章驗證屬於授權子系統；請參閱授權深入參考。

一致性

主張	標準	條款
增量更新會將變更附加到檔案結尾，並讓原始內容保持原封不動。	ISO 32000-2	§7.5.6
該更新的交叉參照區段僅涵蓋已變更的物件，而附加的 trailer 帶有一個 Prev 項目以定位先前的交叉參照區段。	ISO 32000-2	§7.5.6
Literal string 以括號書寫；不成對的括號與反斜線需要轉義處理。	ISO 32000-2	§7.3.4.2

所有條款皆為改寫；NextPDF 不重製規範文字。NextPDF 不做任何認證主張。 此 applicator 以所引用的 ISO 32000-2 形狀寫入增量更新，作為一項能力陳述；它並非經認證或經獨立驗證的寫入器。本頁僅描述執行階段行為。它不做任何保證、不對資格或法律效力做任何陳述，也不構成法律建議；評估或訂閱的條款完全由授權合約定義。

開發注意事項

• BrandingMode、BrandingStrategy、兩個策略與該設定皆帶有 @since 3.0.0；BrandingApplicator 與 BrandingApplicationException 帶有 @since 3.1.0。
• 此子系統不進行任何網路呼叫。此 applicator 只讀取它會改寫的結構欄位：Info 字典字串、頁面字典，以及交叉參照尾端。
• 授權封套是一個簽署過的成品，執行階段會驗證其發行者簽章。授權佈建、續約與安全儲存是運維人員的責任。
• 所有具體型別皆為 final；策略與設定同時也是 readonly。若要變更浮水印樣式，請建構一個新的設定實例。
• BrandingStrategy::isActive() 回傳 false 時，保證其他每個方法皆回傳恆等值；呼叫端可為了效能對其做短路。
• 浮水印串流參照 /helvetica 資源名稱。Core 會為其自身的品牌標示註冊此資源；若整合停用了 Core 品牌標示，則必須確保此資源存在。
• 此 applicator 不計算任何摘要；呼叫端會在提交前對帶品牌標示的位元組重新計算摘要。
• 內部機制細節保留在原始碼儲存庫的內部文件中，不在本手冊的範圍內。

發布邊界

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

另請參閱

• Branding — 評估品牌標示子系統的能力頁。
• Trial and Evaluation Branding — 端到端的評估說明。
• Licensing — Deep Reference
• Enterprise overview