產生 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 符號將一個線性元件（主要項目識別碼）與一個 2D 複合元件（延伸資料，例如批號或有效期限）配對。這份食譜示範了複合能力如何被註冊與解析、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 2D 元件需要 ISO/IEC 24723 Clause 5 的 base-928 高階編碼，加上一個元件專屬的載體，而本版本並未實作該路徑，因此宣傳一個 CC-A/CC-B 能力會等於指名一個無法發出可解碼符號的編碼器。

Fail-closed 邊界——尚未提供的部分

CC-A 與 CC-B 是刻意未作為可用符號系統出貨的：

• CC-A——一個低階的 base-928 基數基本元件（Base928Converter，僅碼字）與一個 Clause-5 二進位字串建構器在內部已存在，但完整的 ISO/IEC 24723 Clause 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 提供，並註冊在 Contracts / Barcode 頁面所記載的同一個編碼器契約之後。
• 沒有可呼叫的 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 Clause 5 CC-A 高階編碼與 CC-A 專屬載體並未實作，因此不會產生任何 CC-A 符號。
• CC-A 與 CC-B 會 fail closed。 它們的 encode() 總是拋出具型別的 UnsupportedBarcodeFeature 例外，而不是發出一個部分符號。這是一個有文件記載的範圍邊界，刻意如此。
• GS1 應用識別碼仍然適用。 線性元件會攜帶帶有 FNC1 前綴的 GS1 結構化資料，一如 產生 1D 與 2D 條碼 中所述。
• 為酬載設限。 較大的複合酬載會產生較密的符號。請在編碼之前為酬載長度設限。

效能

碼字產生的時間複雜度與酬載長度呈線性；載體發出的時間複雜度與矩陣面積呈線性。沒有點陣化步驟——每個模組都是一個路徑運算子——因此無論符號大小，記憶體都保持平坦。這份食譜維持在 1500 ms / 64 MB 的預算之內。

安全性注意事項

一個複合符號會攜帶你傳入的任何酬載；請在消費端將該值視為不受信任。編碼器編碼位元組，但不對它們進行鑑別。請在編碼之前為酬載長度設限，以將符號大小與工作量維持在預算之內。

一致性

陳述	規範	條款
已出貨的 CC-C 複合元件使用一個 PDF417 載體。	ISO/IEC 15438 (PDF417)	§5
CC-A 的 base-928 高階編碼是本版本未實作的 Clause 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 碼字會被固定對照一份黃金樣本，並以一個獨立解碼器交叉檢查。此處不主張對 GS1 Composite 標準的任何 GA、一致性或端到端認證，亦未重現任何規範文字。

另請參閱

• Barcode 模組
• 產生 1D 與 2D 條碼
• Contracts / Barcode