品牌標記

速覽

品牌標記子系統會在評估期間對產生的 PDF 套用可見的評估品牌標記，而在付費授權下不套用任何標記。它隨附於 nextpdf/enterprise 套件、跨版本治理評估行為，並完全由授權驅動——而非由應用程式碼驅動。關於完整的評估流程，請參閱 試用與評估品牌標記；本頁記載品牌標記子系統本身。

供應與授權

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

與大多數 Enterprise 介面不同，它擁有一個專屬的能力代碼 enterprise.branding，因為它跨所有版本治理評估行為——包括僅有 Core 與僅有 Pro 的部署。品牌標記模式在執行階段從簽署過的授權封套解析；沒有任何應用程式旗標會選定它，且任一版本中的付費授權都會解析為 BrandingMode::None。

安裝

composer require nextpdf/enterprise:^3

概念總覽

執行階段有一個具兩種狀態的品牌標記模式，由 BrandingMode 建模：

• None — 無評估品牌標記。付費與一般輸出永不被修改。這是預設值。
• EvaluationWatermark — 對產生的 PDF 套用可見的評估品牌標記。

BrandingStrategyFactory 會將模式對應到策略：None 對應 NullBrandingStrategy（它不做任何工作、不產生任何修改），EvaluationWatermark 對應 EvaluationBrandingStrategy。是授權狀態——而非應用程式碼——選定模式。付費授權永不產生帶標記的輸出，且沒有要切換的正式環境建置，也沒有要切換的程式碼旗標。

本頁僅描述執行階段行為。它不做任何保證，也不對資格或法律效力做任何陳述；適用於你評估或訂閱的條款，完全由你的授權合約定義。

API 介面

概念	行為
BrandingMode	兩種狀態：None（預設，無修改）或 EvaluationWatermark。
BrandingStrategyFactory	將一個 BrandingMode 解析為一個策略。
EvaluationBrandingStrategy	套用評估浮水印與中繼資料裝飾。
NullBrandingStrategy	供付費 / 一般輸出使用的無作用策略。
EvaluationBrandingConfig	不可變的浮水印文字、中繼資料裝飾、字型大小、灰階值與角度。
BrandingStrategy	整合層所使用的合約：isActive()、buildPageWatermark()、decorateProducer()、decorateSubject()。
BrandingApplicator	將已解析的策略套用至已渲染的 PDF 位元組；fail-closed——當啟用中的品牌標記無法標記時，會擲出 BrandingApplicationException。

品牌標記子系統為整合層提供一個小型的可呼叫介面，用以套用授權所解析出的策略；應用程式碼永不選擇是否加上品牌標記。下方範例展示兩個接觸點：讀取一個已解析的策略，以及用 fail-closed 套用器為已渲染的位元組加上標記。

程式碼範例 — 快速上手

解析授權所選定的策略並讀取其行為。付費授權會解析為 BrandingMode::None，其策略未啟用，會將每個值原封不動地傳遞。

resolve-strategy.php

<?php

declare(strict_types=1);

use NextPDF\Enterprise\Branding\BrandingMode;
use NextPDF\Enterprise\Branding\BrandingStrategyFactory;

// The license resolves the mode; None is what a paid license produces.
$strategy = BrandingStrategyFactory::create(BrandingMode::None);

\var_dump($strategy->isActive());                 // bool(false)
echo $strategy->decorateProducer('NextPDF 3.1');  // NextPDF 3.1 (unchanged)

程式碼範例 — 正式環境

用授權所解析出的策略為已渲染的 PDF 位元組加上標記。BrandingApplicator::apply() 在付費授權下會原封不動地回傳輸入；在評估授權下，則會附加浮水印與中繼資料標記，同時保留原始位元組不變。當啟用中的品牌標記無法安全套用時，它會擲出 BrandingApplicationException——請將其視為終結性錯誤，且絕不提交未標記的位元組。

apply-evaluation-branding.php

<?php

declare(strict_types=1);

use NextPDF\Enterprise\Branding\BrandingApplicationException;
use NextPDF\Enterprise\Branding\BrandingApplicator;
use NextPDF\Enterprise\Branding\BrandingMode;
use NextPDF\Enterprise\Branding\BrandingStrategyFactory;
use NextPDF\Enterprise\Branding\EvaluationBrandingConfig;

/**
 * Apply the branding the license resolved to freshly rendered PDF bytes.
 *
 * @param string       $renderedPdf Bytes from the render engine.
 * @param BrandingMode $mode        Resolved from the signed license envelope.
 *
 * @throws BrandingApplicationException When active branding cannot be marked.
 */
function markEvaluationOutput(string $renderedPdf, BrandingMode $mode): string
{
    $strategy = BrandingStrategyFactory::create(
        $mode,
        new EvaluationBrandingConfig(
            watermarkText: 'EVALUATION COPY — Not for Production Use',
        ),
    );

    try {
        return (new BrandingApplicator())->apply($renderedPdf, $strategy);
    } catch (BrandingApplicationException $e) {
        // Fail-closed: never emit unbranded evaluation output. Dead-letter.
        throw $e;
    }
}

評估品牌標記做了什麼

當啟用中的授權選定 EvaluationWatermark 時，評估策略會：

• 在每一頁繪製一段淺灰色的對角浮水印文字，以一個隔離的圖形狀態下的頁面內容串流呈現，因此它不會更動周圍內容或你的版面；
• 在文件的 producer 中繼資料後附加一個評估後綴；
• 在文件的 subject 中繼資料前加上一個評估前綴。

浮水印使用一種 Base14 字型與一個旋轉矩陣，將文字對角定位於頁面中央。設定物件是不可變的，並會驗證其輸入（例如浮水印文字不可為空，且字型大小必須為正值）。

付費授權如何移除品牌標記

在付費（非評估）授權下，品牌標記模式為 None，並選定空策略：無浮水印、無 producer 後綴、無 subject 前綴。輸出與完全沒有品牌標記子系統時所產生的輸出完全相同。移除評估品牌標記不需任何程式碼變更——安裝一份付費授權，下一份產生的文件就不帶標記。

邊界案例與陷阱

• 當授權狀態為評估式時，會出現品牌標記。這反映的是授權狀態，而非缺陷；請檢查授權狀態，並透過授權入口網站續約。
• 浮水印按設計為置中且對角，使評估輸出明確無疑；它並非為了在正式環境調校而設。付費授權會將它完全移除。
• producer 與 subject 中繼資料在評估期間帶有評估標記，而在付費授權下則不存在。

效能

浮水印是一段小而固定、每頁的內容串流，對產生時間或文件大小的影響可忽略。在付費授權下，子系統不做任何工作。本頁的效能預算反映的是文件渲染。

安全注意事項

評估品牌標記是一個可見性標記，不是安全控制。它指出的是評估輸出。它不是數位簽章，且絕不可被當作數位簽章來依賴。若需要防竄改證據的輸出，請使用功能對照表中所述的簽署能力。選定品牌標記模式的那份授權是一個簽署過的封套，執行階段會驗證其簽發者簽章。

資料落地與 PII 緩解措施

品牌標記子系統加入一個固定的浮水印與中繼資料標記；它不讀取或傳輸文件內容，也不進行任何網路呼叫。

安全遙測與日誌清洗

子系統不記錄文件內容。會改變品牌標記模式的授權狀態轉換，是透過授權子系統呈現，而非在此處。

一致性

本頁不主張任何標準一致性。它僅描述執行階段行為。它不陳述或暗示任何保證、認證或資格。你評估或訂閱的條款，完全由你的授權合約定義。

FIPS 模式行為

此模組不執行任何密碼學運算。授權簽章驗證由授權子系統處理。

威脅模型

品牌標記子系統本身，除了已解析的品牌標記模式外，不處理任何外部輸入。選定模式的授權封套是簽署過的，其簽發者簽章由執行階段驗證；要偽冒模式，就需要偽造該簽章。

行為合約

• BrandingMode 有兩種狀態：None（預設；不修改輸出）與 EvaluationWatermark。
• 在付費（非評估）授權下，模式為 None，並選定空策略：輸出與完全沒有品牌標記子系統時所產生的輸出完全相同。
• 在評估授權下，策略會在一個隔離的圖形狀態下繪製一段對角浮水印，並在 producer 與 subject 中繼資料後附加評估標記。
• 設定物件是不可變的，並會驗證其輸入（浮水印文字非空、字型大小為正值）。

發佈邊界

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

Core 回退

品牌標記子系統隨附於 nextpdf/enterprise 套件，但跨所有版本治理評估行為，包括使用評估授權、僅有 Core 與僅有 Pro 的部署。沒有可回退的僅限 Core 品牌標記子系統；任一版本中的付費授權都會解析為 BrandingMode::None。

Pro 回退

沒有獨立的 Pro 品牌標記子系統。同一個 nextpdf/enterprise 品牌標記子系統也治理 Pro 部署的評估行為；一份付費 Pro 授權會解析為 BrandingMode::None，與付費 Enterprise 授權完全相同。

Enterprise 邊界註記

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

部署邊界

選定品牌標記模式的授權封套是一個簽署過的成品，執行階段會驗證其簽發者簽章；授權供裝、續約，以及授權的安全儲存是操作者的責任。子系統不進行任何網路呼叫，也不讀取任何文件內容。

法律合規邊界

本頁僅描述執行階段行為。它不陳述或暗示任何保證、認證或資格，也不構成法律建議。你評估或訂閱的條款——包括套用哪種品牌標記與套用多久——完全由你的授權合約定義。請查閱該合約或洽詢銷售。

另請參閱

• 品牌標記 — 深入參考 — 此子系統的公開 API 與行為合約。
• 試用與評估品牌標記 — 完整的評估流程。
• 授權啟用
• Enterprise 概覽
• 核心、Pro 與 Enterprise 功能對照表