Pro 版本

Barcode

概览

NextPDF Pro 在开源版本的线性与 QR 制式之上，增加了特殊 2D 与供应链条码制式。每种制式都作为一个确定性的内容流，直接渲染到 PDF 页面表面上。

可用性与授权

此能力随 NextPDF Pro（nextpdf/pro）发布，并通过 Pro 层级的授权信封激活。没有该权利的部署不会加载此能力的类。比较版本并获取授权。

安装

composer require nextpdf/pro:^3

Pro 编码器通过标准的条码编码器注册表自行注册。构建自有注册表的应用，可通过已发布的 service provider 显式地重新注册 Pro 编码器。

概念概览

开源版本覆盖日常的线性与 QR 制式。NextPDF Pro 用面向零售、物流、邮政与高密度工业用途的特殊制式，扩展了同一个注册表：

Micro QR Code — 适用于小标签空间的紧凑 QR 变体。
DotCode — 为高速工业标记设计的一种点阵制式。
Han Xin Code — 一种原生具备大字符集 CJK 文本容量的 2D 制式，依据 ISO/IEC 20830。
JabCode — 一种带多符号级联的多色 2D 制式。
rMQR — 适用于窄而宽标签的矩形 Micro QR 变体。
GS1 DataBar — GS1 零售与优惠券制式族。
GS1 Composite (CC-C) — 一个链接的 1D 基底，加上一个承载 GS1 Application Identifier 数据的高密度 PDF417 2D 扩展组件。（本次发布不支持 CC-A 与 CC-B 2D 扩展组件编码；参见支持矩阵。）

每个编码器产出一个条码数据对象，由页面渲染器将其转换为 PDF 内容操作符。编码是确定性的：相同的输入与选项总是产出相同的模块图案，这使已签名与已归档的文件保持可复现。

条码深度参考携带一份逐制式的、带证据的支持矩阵。对于每一种制式与变体，矩阵记录三种状态之一：一个仓库内的符合性夹具对其进行验证（Verified）、实现面在没有专门夹具的情况下断言它（Claimed），或它落在范围之外（Not supported）。NextPDF 如实报告该矩阵：一个附带编码器但缺少参考轨迹夹具的变体会以一条补录说明保持 Claimed，而非被夸大。

为什么这样设计

每个 Pro 编码器都是一个纯函数：相同的负载与选项总是产出相同的模块矩阵，没有隐藏状态或带种子的随机性。这种确定性是承重的设计决策。它让一个条码得以往返穿越一份已签名或已归档的文件而不扰动字节流，因此重新渲染绝不会使签名失效。它也让符合性可审计：支持矩阵将每种制式钉定到一段存储的参考轨迹，逐位与一个 golden file 核对。扩展 Core 的 BarcodeEncoderRegistry 而非将其分叉，使这些保证在开源版与 Pro 版之间保持一致。

设计背景：每次都是同样的字节：可复现的 PDF。

API 范围

composer require nextpdf/pro:^3

Pro 条码公开范围由以下组成：

一个静态的 service-provider 入口点，将 Pro 2D 编码器注册到一个条码编码器注册表中（MicroQR、DotCode、HanXin、JabCode、RMQR、GS1DataBar，以及 GS1 Composite CC-C 组件键 gs1-composite-cc-c）。本次发布不支持 GS1 Composite CC-A 与 CC-B 2D 扩展组件编码，也不予注册。
一个 GS1 Application Identifier 解析器，它既接受人类可读的 AI 字符串，也接受 GS1 Digital Link URI，并为 GS1-128、QR Code 与 Data Matrix 载体产出编码后的字节序列。
一个 GS1 供应链验证器，它检查校验位、AI 结构、日期逻辑，以及行业配置文件的强制 AI 组合。

完整生成的方法签名表渲染在条码深度参考上。

代码示例 — 快速开始

use NextPDF\Barcode\BarcodeEncoderRegistry;
use NextPDF\Pro\Barcode\BarcodeProServiceProvider;

$registry = new BarcodeEncoderRegistry();
BarcodeProServiceProvider::register($registry);
// $registry now resolves the Pro specialty symbologies.

代码示例 — 生产

use NextPDF\Pro\Barcode\Gs1\Gs1Validator;
use NextPDF\Pro\Barcode\Gs1\Gs1SupplyChainProfile;

$result = Gs1Validator::validate(
    '(01)09521234543213(17)260131(10)ABC123',
    Gs1SupplyChainProfile::NONE,
);

if (! $result->isValid) {
    // Surface findings to your observability pipeline before encoding.
    foreach ($result->findings as $finding) {
        $logger->warning('GS1 validation finding', [
            'rule' => $finding->ruleId,
            'detail' => $finding->message,
        ]);
    }
}

边界情形与坑

默认注册表惰性地预绑定 Pro 编码器条目，并通过能力注册表对其加以管控。当一个应用在没有默认值的情况下组合自有注册表时，受支持的回退是一次显式的 BarcodeProServiceProvider::register() 调用。
重新注册是幂等的：第二次 register() 调用会替换第一次的绑定，而非抛出异常。
GS1 DataBar 的变体覆盖在设计上是部分的。Omnidirectional、Truncated、Stacked、Stacked Omnidirectional 与 Limited 经过参考验证；Expanded 与 Expanded Stacked 在本次发布中不在范围之内。参见支持矩阵。
rMQR 通过经 Annex 验证的符合性套件接受每一个 ISO 23941 版本。早于后续尺寸范围扩展的范围跟踪元数据可能会低估这一点；支持矩阵记录的是经代码验证的实情。

性能

编码代价随负载长度与目标符号尺寸扩展。每种制式以单次遍历布局其符号，没有回流。JabCode 多符号级联随符号数量（1–61）扩展。编码将模块矩阵保存在内存中；所选最大符号版本限制了代价上界。

安全说明

条码编码器不执行负载内容；它们把内容编码为数据。GS1 验证在编码之前拒绝格式错误的 AI 结构与无效的校验位，这防止一个格式错误的供应链字符串产出一个可扫描但不符合规范的符号。编码器本身不记录任何负载；应用必须从自己的日志中清除敏感负载。

符合性

每种制式遵循其相关的已发布标准（GS1 DataBar 用 ISO/IEC 24724、GS1 Composite 用 ISO/IEC 24723、rMQR 用 ISO/IEC 23941、Micro QR 用 ISO/IEC 18004 Annex、Han Xin Code 用 ISO/IEC 20830、JabCode 用 ISO/IEC 23634、邮政制式用 USPS-B-3200）。带引用标识符的条款级符合性映射渲染在条码深度参考上。

发布边界

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