安定性: 実験的

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）でフェイルクローズします。これは文書化されたスコープ境界であり、欠陥ではありません。

GS1 Composite シンボルは、リニアコンポーネント（一次的なアイテム識別子）と 2D コンポジットコンポーネント（バッチや有効期限などの拡張データ）を組み合わせます。このレシピは、コンポジット機能がどのように登録・解決されるか、Core が何を提供し、Premium が何を追加し、サポートが正確にどこで止まるかを示します。

インストール

composer require nextpdf/core:^3

CC-C コンポジットエンコーダーには Premium パッケージが必要です。

composer require nextpdf/pro

概念の概要

NextPDF は、Barcode モジュールが任意のエンコーダーを解決するのと同じ方法で、機能レジストリを通じてシンボロジーを解決します。GS1 Composite 機能はそこに 1 つ登録されています。

barcode.gs1-composite-cc-c は、Core の CapabilityRegistry に、Pro 製品ティアの下で登録されています。これは CC-C コンポジットコンポーネント向けの完全な PDF417 キャリア（ISO/IEC 15438）です。Pro エンコーダーはペイロードを正規のコア PDF417 エンコーダーへ経路付けします。この機能は 常に登録されますが、Available になるのは Premium がインストールされている場合のみ です。Core のみの場合はステータスが Unavailable であり、登録はされていても不活性です（オプトイン、デフォルトはオフ）。

CC-A または CC-B の機能は登録されていません。適合する CC-A/CC-B の 2D コンポーネントには、ISO/IEC 24723 Clause 5 の base-928 高水準エンコーデーションと、コンポーネント固有のキャリアが必要であり、このリリースはそのパスを実装していません。そのため、CC-A/CC-B 機能を公表することは、デコード可能なシンボルを出力できないエンコーダーに名前を付けることになってしまいます。

フェイルクローズ境界 — まだ利用できないもの

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 をスローします。

これらはフェイルクローズします。いずれかをエンコードするリクエストは、部分的または誤ったシンボルを出力するのではなく、型付き例外を送出します。これは意図的なスコープラインであり、欠陥ではありません。

出荷済みの 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() でフェイルクローズします。

生成されたエンコーダーテーブルについては、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 です。has() ではなく get(...)->status でゲートしてください — has() は Core のみでも true です。エントリが常に登録されるためです。
使用可能な CC-A エンコーダーはありません。 低水準の base-928 基数プリミティブは内部に存在しますが、完全な ISO/IEC 24723 Clause 5 CC-A 高水準エンコーデーションと CC-A 固有のキャリアは実装されていないため、 CC-A シンボルは生成されません。
CC-A と CC-B はフェイルクローズします。 それらの encode() は、部分的なシンボルを出力するのではなく、常に型付きの UnsupportedBarcodeFeature 例外をスローします。これは意図的に文書化されたスコープ境界です。
GS1 アプリケーション識別子は依然として適用されます。 リニアコンポーネントは、 1D および 2D バーコードを生成すると同様に、FNC1 プレフィックス付きの GS1 構造化データを運びます。
ペイロードを有界化してください。 より大きなコンポジットペイロードは、より密なシンボルを生み出します。エンコードの前にペイロード長を有界化してください。

パフォーマンス

コードワード生成はペイロード長に対して線形で、キャリアの出力はマトリクス面積に対して線形です。ラスタライズステップはなく — 各モジュールはパス演算子です — シンボルサイズにかかわらずメモリはフラットなままです。このレシピは 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 例外でフェイルクローズします。出荷済みの CC-C コードワードはゴールデンに対してピン留めされ、独立したデコーダーでクロスチェックされます。GA、適合性、または GS1 Composite 標準に対するエンドツーエンドの認証は一切主張せず、規格本文の複製も行っていません。