生成 GS1 Composite 条码（CC-C 载体）

概览

可选启用的预览能力——默认关闭。 GS1 Composite 支持是一项实验性、可选启用的特性。唯一已分发的复合是 CC-C（完整的 PDF417 载体）：Core 注册 barcode.gs1-composite-cc-c 能力，Premium（nextpdf/pro）包对其背后的编码器进行门控。仅有 Core 时，该能力被注册，但其状态为 Unavailable，因此不会发出任何东西。CC-A 与 CC-B 尚不可用：编码任一者的请求会以一个带类型的异常（UnsupportedBarcodeFeature）fail closed。这是一条有文档记录的范围边界，而非缺陷。

一个 GS1 Composite 符号把一个线性分量（主项标识符）与一个二维复合分量（诸如批次或有效期之类的扩展数据）配对。本配方展示复合能力如何被注册与解析、Core 提供什么、Premium 增加什么，以及支持恰好在何处止步。

安装

composer require nextpdf/core:^3

CC-C 复合编码器需要 Premium 包：

composer require nextpdf/pro

概念总览

NextPDF 通过能力注册表解析一种符号体系，方式与 Barcode 模块 解析任何编码器一样。那里注册了一个 GS1 Composite 能力：

• barcode.gs1-composite-cc-c 在 Core 的 CapabilityRegistry 中、于 Pro 产品层级下被注册。它是用于 CC-C 复合分量的完整 PDF417 载体（ISO/IEC 15438）。Pro 编码器会把载荷路由经规范的核心 PDF417 编码器。该能力始终被注册，但只有在 Premium 已安装时才为 Available——仅有 Core 时其状态为 Unavailable，因此它虽被注册却处于惰性（可选启用，默认关闭）。

没有注册 CC-A 或 CC-B 能力。一个符合规范的 CC-A/CC-B 二维分量需要 ISO/IEC 24723 第 5 条的 base-928 高层编码加上一个分量专用载体，而本次发行未实现该路径，因此宣称一个 CC-A/CC-B 能力将会命名一个无法发出可解码符号的编码器。

Fail-closed 边界——尚不可用的部分

CC-A 与 CC-B 被有意地不作为可用符号体系分发：

• CC-A——内部存在一个底层 base-928 基数原语（Base928Converter，仅码字）和一个第 5 条的二进制串构造器，但完整的 ISO/IEC 24723 第 5 条 CC-A 高层编码以及 CC-A 专用载体未被实现，因此不会产出可用的 CC-A 符号。CompositeComponentA::encode() 总是抛出带类型的 UnsupportedBarcodeFeature 异常。
• CC-B——中等容量的复合分量同样未被实现；CompositeComponentB::encode() 总是抛出 UnsupportedBarcodeFeature。

这些会 fail closed：编码任一者的请求会抛出一个带类型的异常，而不是发出一个部分或错误的符号。这是一条刻意划定的范围线，而非缺陷。

已分发的 CC-C 路径遵循码字黄金样本纪律：其所生成的码字被钉定于一个黄金样本，并与一个独立解码器交叉核对，因此一个 CC-C 码字流是经过验证的，而不仅仅是被产出的。此处不主张针对 GS1 Composite 标准的任何端到端认证。

API 接口

GS1 Composite 符号通过能力注册表解析，而非通过一个新的顶层外观方法：

• NextPDF\Support\CapabilityRegistry——用于报告 barcode.gs1-composite-cc-c 在当前版本中是否为 Available 的查询。用 get('barcode.gs1-composite-cc-c')->status 作为可用性判定；has() 只报告该能力已被注册（即便在仅有 Core 的安装上也为 true），因此它不是可用性门控。
• CC-C 复合编码器由 nextpdf/pro 提供，并在 契约 / 条码 页所记述的同一个编码器契约之后注册。
• 没有可调用的 CC-A 或 CC-B 编码器。CC-A/CC-B 分量类在 encode() 上 fail closed。

运行 composer docs:generate-api-php -- --module=Barcode 以获取生成的编码器表。

代码范例——快速上手

在你依赖 CC-C 载体能力之前，先检查它是否可用。仅有 Core 时它被注册但为 Unavailable；安装了 Premium 时它为 Available。请以状态而非 has() 作为门控——has() 在仅有 Core 的安装上也为 true，因为该能力始终被注册。

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Support\CapabilityRegistry;
use NextPDF\Support\CapabilityStatus;

$registry = CapabilityRegistry::getInstance();

$capability = $registry->get('barcode.gs1-composite-cc-c');

if ($capability->status === CapabilityStatus::Available) {
    echo "CC-C composite carrier is available (Premium present)\n";
} else {
    echo "CC-C composite carrier needs nextpdf/pro\n";
}

代码范例——正式环境

以能力状态作为门控，并显式对待不可用的分量。要么是一个忠实的 CC-C 符号，要么是一次清晰的拒绝——绝不是一个错误的复合。

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Support\CapabilityRegistry;
use NextPDF\Support\CapabilityStatus;

final readonly class CompositeLabelService
{
    public function __construct(private CapabilityRegistry $registry) {}

    /**
     * Assert that the only shipped GS1 Composite (CC-C) is available before use.
     *
     * The capability is opt-in and default-OFF: on a Core-only install it is
     * registered but its status is Unavailable, so check the status — not has().
     */
    public function assertCompositeAvailable(): void
    {
        $status = $this->registry->get('barcode.gs1-composite-cc-c')->status;

        if ($status !== CapabilityStatus::Available) {
            // Core-only install. The CC-C encoder needs Premium. Fail fast with
            // a clear upgrade message rather than emitting a degraded symbol.
            throw new \RuntimeException(
                'GS1 Composite CC-C requires nextpdf/pro.',
            );
        }
    }

    // CC-A and CC-B are NOT yet available. Their component classes fail closed:
    // calling encode() always throws NextPDF\Pro\Barcode\Gs1Composite\
    // UnsupportedBarcodeFeature. There is no runnable CC-A/CC-B encode path —
    // CC-C is the only shipped GS1 Composite symbology. Do not call encode() on
    // CC-A/CC-B expecting a symbol.
    public function note(): string
    {
        return 'CC-A and CC-B are not available; use CC-C.';
    }
}

边界情况与陷阱

• CC-C 需要 Premium 才能可用，且默认关闭。 Core 在 Pro 层级下注册该能力；其背后的编码器分发于 nextpdf/pro。在仅有 Core 的安装上，该能力被注册但其状态为 Unavailable。请以 get(...)->status 而非 has() 作为门控——has() 即便在仅有 Core 时也为 true，因为该条目始终被注册。
• 没有可用的 CC-A 编码器。 内部存在一个底层 base-928 基数原语，但完整的 ISO/IEC 24723 第 5 条 CC-A 高层编码与 CC-A 专用载体未被实现，因此不会产出 CC-A 符号。
• CC-A 与 CC-B 会 fail closed。 它们的 encode() 总是抛出带类型的 UnsupportedBarcodeFeature 异常，而不是发出一个部分符号。这是一条有文档记录的范围边界，是有意为之。
• GS1 应用标识符仍然适用。 线性分量携带带 FNC1 前缀的 GS1 结构化数据，如 生成一维与二维条码 中所述。
• 限定载荷。 更大的复合载荷会产出更密集的符号。请在编码之前限定载荷长度。

性能

码字生成在载荷长度上呈线性；载体发出在矩阵面积上呈线性。没有栅格化步骤——每个模块都是一个路径运算符——因此无论符号大小内存都保持平坦。本配方保持在 1500 ms / 64 MB 预算之内。

安全性注意事项

一个复合符号携带你所传入的任何载荷；在消费侧把该值当作不受信任来对待。编码器对字节进行编码，并不对它们进行鉴别。请在编码之前限定载荷长度，以使符号大小与工作量保持在预算内。

符合性

主张	标准	条款
已分发的 CC-C 复合分量使用一个 PDF417 载体。	ISO/IEC 15438 (PDF417)	§5
CC-A 的 base-928 高层编码是本次发行未实现的第 5 条方法。	ISO/IEC 24723 (GS1 Composite)	§5

这是一个实验性、可选启用的预览实现。Core 在 Pro 层级下注册 barcode.gs1-composite-cc-c 能力；Premium 包对 CC-C 编码器进行门控，在仅有 Core 的安装上它默认关闭（状态 Unavailable）。CC-A 与 CC-B 尚不可用——它们的 encode() 会以带类型的 UnsupportedBarcodeFeature 异常 fail closed。已分发的 CC-C 码字被钉定于一个黄金样本，并与一个独立解码器交叉核对。此处不主张任何 GA、符合性或针对 GS1 Composite 标准的端到端认证，也未重制任何标准原文。

另请参阅

• Barcode 模块
• 生成一维与二维条码
• 契约 / 条码