品牌标识 — 深度参考

概览

本页是 NextPDF\Enterprise\Branding 模块的深度参考。该模块标记评估输出，并保持付费输出不受影响。由授权解析得到的 BrandingMode 选择一个策略；BrandingApplicator 将解析出的策略施加到渲染后的 PDF 字节上。在付费授权下，该变换为恒等变换：输出逐字节保持不变，且无需任何代码更改。关于评估工作流，请先阅读品牌标识能力页。

可用性与授权

该能力随 NextPDF Enterprise（nextpdf/enterprise）发行，并在 Enterprise 级授权封套下激活。没有该权益的部署不会加载此能力的类。比较各版本并获取授权。

该子系统携带专用的 enterprise.branding 能力代码，因为它跨所有版本治理评估行为。品牌标识模式在运行时从签名后的授权封套解析；没有任何应用程序标志来选择它。付费授权将模式解析为 None，绝不产出带品牌标识的输出。没有要切换的生产构建。

公共 API 表面

符号	参数	默认行为	返回	抛出或失败于	说明
BrandingMode	—	None（'none'）：不修改	—	—	以字符串为底层值的枚举；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、灰度 0.85、45 度	实例	当 text 为空、字号非正、或灰度超出 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 资源名的标准 14 种 Helvetica 字体、填充文本渲染模式，以及一个将文本对角穿过页面中心放置的旋转矩阵。默认样式为 48 pt 文本、灰度级别 0.85、旋转 45 度。居中通过字形数量来近似文本宽度——加载了 intl 时用字素簇，否则经由 mbstring 用 Unicode 码点，字节长度作为最终回退。按设计不查询任何逐字形的步进宽度。水印文本按照 ISO 32000-2:2020 §7.3.4.2（反斜杠与圆括号）转义为 PDF 字面量字符串。

元数据装饰。 decorateProducer 将生产器后缀追加到 /Producer 值。decorateSubject 将主题前缀前置到 /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 的灰度级别。
• 一个未产生任何 Producer、Subject 或水印更改的激活策略，会以 BrandingApplicationException 被拒绝，而非发出看似付费的字节。
• 没有可用 /MediaBox（缺失或继承）的页面，会以 ISO 216 A4 默认的 595.276 × 841.890 点加水印。
• 单引用与数组两种形式的 /Contents 均受支持；水印引用被追加在最后，因此它绘制在最上层。没有 /Contents 的页面会获得一个。
• Info 字符串值以其原始表示进行往返：十六进制字符串（UTF-16BE）保持十六进制，字面量字符串保持字面量。缺失的键会被追加，当值包含非 ASCII 字符时以十六进制编码。
• 加密文档会被拒绝：在 /Encrypt 下重写字符串对象将需要文档加密密钥。
• 失败携带稳定代码 SPEC-BRANDING-UNAPPLICABLE（BrandingApplicationException::SPEC_CODE），以便消费管道可对无法加品牌标识的输出进行死信处理与审计。
• 本模块不执行任何密码学操作。授权封套签名验证属于授权子系统；参见授权深度参考。

符合性

主张	标准	条款
增量更新将更改追加到文件末尾，并保持原始内容完好。	ISO 32000-2	§7.5.6
该更新的交叉引用节仅覆盖已更改的对象，且新增的 trailer 携带一个 Prev 条目以定位先前的交叉引用节。	ISO 32000-2	§7.5.6
字面量字符串写在圆括号中；不平衡的圆括号与反斜杠需要转义处理。	ISO 32000-2	§7.3.4.2

所有条款均为释义；NextPDF 不复制规范性文本。NextPDF 不作任何认证声明。 施加器按所引 ISO 32000-2 的形态写入增量更新，作为一种能力陈述；它不是经认证或经独立验证的写入器。本页仅描述运行时行为。它不作任何保证，不就资格或法律效力作任何陈述，也不构成法律意见；一份评估或订阅的条款仅由授权协议定义。

开发说明

• BrandingMode、BrandingStrategy、两个策略以及配置都携带 @since 3.0.0；BrandingApplicator 与 BrandingApplicationException 携带 @since 3.1.0。
• 该子系统不发起任何网络调用。施加器仅读取它所重写的结构性字段：Info 字典字符串、页面字典，以及交叉引用尾部。
• 授权封套是一个签名后的制品，运行时会验证其签发方签名。授权供给、续订与安全存储是运维方的责任。
• 所有具体类型都是 final；策略与配置还是 readonly。构造一个新的配置实例以更改水印样式。
• BrandingStrategy::isActive() 返回 false 保证其他每个方法都返回恒等值；调用方可据此短路以提升性能。
• 水印流引用 /helvetica 资源名。Core 为其自身的品牌标识注册此资源；禁用 Core 品牌标识的集成必须确保该资源存在。
• 施加器不计算任何摘要；调用方在提交带品牌标识的字节之前对其重新计算摘要。
• 内部机制细节保留在源代码仓库的内部文档中，不在本手册范围之内。

发布边界

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

另请参阅

• 品牌标识 — 评估品牌标识子系统的能力页。
• 试用与评估品牌标识 — 端到端的评估叙事。
• 授权 — 深度参考
• Enterprise 概述