Enterprise 版本

品牌化

速览

品牌化子系统会在评估期间对生成的 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 字节；失败即关闭——当无法标记生效的品牌化时抛出 `BrandingApplicationException`。

品牌化子系统为集成层暴露了一个小型可调用接口，用以应用授权已解析的策略；应用程序代码从不决定是否进行品牌化。下方示例展示了两个接触点：读取一个已解析的策略，以及用失败即关闭的应用器标记已渲染的字节。

代码示例 — 快速上手

解析授权所选的策略并读取其行为。付费授权解析为 BrandingMode::None，其策略处于非生效状态，会原样透传每一个值。

<?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——将其视为终止性错误，且绝不可提交未标记的字节。

<?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 元数据在评估期间携带评估标记，在付费授权下则不存在。

性能

水印是一个固定的小型逐页内容流，对生成时间或文档大小的影响微乎其微。在付费授权下，该子系统不做任何工作。本页的性能预算反映的是文档渲染。

安全说明

评估品牌化是一个可见性标记，而非安全控制。它表明这是评估输出。它不是数字签名，也绝不能被当作数字签名来依赖。若需防篡改输出，请使用功能对照表中所述的签名能力。选择品牌化模式的授权是一个签名封套，运行时会验证其颁发者签名。

数据驻留与个人信息缓解

品牌化子系统添加一个固定水印与元数据标记；它既不读取也不传输文档内容，且不发起任何网络调用。

安全遥测与日志清洗

该子系统不记录文档内容。改变品牌化模式的授权状态转变，通过授权子系统暴露，而非在此处暴露。

符合性

本页不声明任何标准符合性。它仅描述运行时行为。它不陈述或暗示任何担保、认证或资格。你的评估或订阅条款，仅由你的授权协议定义。

FIPS 模式行为

本模块不执行任何密码学运算。授权签名验证由授权子系统处理。

威胁模型

品牌化子系统本身除了已解析的品牌化模式之外，不处理任何外部输入。选择该模式的授权封套是签名的，其颁发者签名由运行时验证；伪造该模式将需要伪造那个签名。

行为契约

BrandingMode 有两种状态：None（默认；不修改输出）与 EvaluationWatermark。
在付费（非评估）授权下，模式为 None，并选用空策略：其输出与完全没有品牌化子系统时所产生的输出一致。
在评估授权下，策略会在隔离图形状态下绘制一段对角线水印，并向 producer 与 subject 元数据追加评估标记。
配置对象是不可变的，并会校验其输入（水印文本非空，字号为正）。

发布边界

本页仅记录外部可观察的行为与受支持的公开 API 接口。内部命名空间路径、辅助类、机制表、运维手册文件名，以及工单前缀均不属于范围。

Core 回退

品牌化子系统随 nextpdf/enterprise 包发行，但它跨所有版本统辖评估行为，包括使用评估授权、仅 Core 与仅 Pro 的部署。不存在可供回退的仅 Core 品牌化子系统；任何版本中的付费授权都解析为 BrandingMode::None。

Pro 回退

不存在单独的 Pro 品牌化子系统。同一个 nextpdf/enterprise 品牌化子系统统辖 Pro 部署的评估行为；付费 Pro 授权解析为 BrandingMode::None，与付费 Enterprise 授权完全相同。

Enterprise 边界说明

内部机制细节保留在源代码库的内部文档中，不属于本手册的范围。

部署边界

选择品牌化模式的授权封套是一个签名工件，运行时会验证其颁发者签名；授权的预置、续订与安全存储是操作方的责任。该子系统不发起任何网络调用，也不读取任何文档内容。

法务合规边界

本页仅描述运行时行为。它不陈述或暗示任何担保、认证或资格，也不构成法律建议。你的评估或订阅条款——包括应用何种品牌化以及为期多久——仅由你的授权协议定义。请查阅该协议或联系销售。

另请参阅

品牌化 —— 深度参考 —— 本子系统的公开 API 与行为契约。
试用与评估品牌化 —— 端到端的评估全貌。
授权激活
Enterprise 总览
Core、Pro 与 Enterprise 功能对照表