Barcode

概要

NextPDF Pro は、オープンソースエディションのリニアおよび QR シンボル体系の上に、特殊な 2D およびサプライチェーンのバーコードシンボル体系を追加します。各シンボル体系は、決定論的なコンテンツストリームとして、PDF ページサーフェスに直接レンダリングされます。

提供状況とライセンス

このケイパビリティは NextPDF Pro（nextpdf/pro）に同梱され、Pro ティアのライセンスエンベロープで有効化されます。そのエンタイトルメントを持たないデプロイメントは、このケイパビリティのクラスを読み込みません。エディションを比較してライセンスを取得。

インストール

composer require nextpdf/pro:^3

Pro エンコーダーは、標準のバーコードエンコーダーレジストリを通じて自身を登録します。独自のレジストリを構築するアプリケーションは、公開されたサービスプロバイダーを通じて Pro エンコーダーを明示的に再登録できます。

概念の概要

オープンソースエディションは、日常的なリニアおよび QR のシンボル体系をカバーします。NextPDF Pro は、小売、物流、郵便、高密度産業用途のために、同じレジストリを特殊なシンボル体系で拡張します。

• Micro QR Code — 小さなラベルスペース向けのコンパクトな QR バリアント。
• DotCode — 高速産業マーキング向けに設計されたドットマトリクスシンボル体系。
• Han Xin Code — ISO/IEC 20830 に従い、大規模な CJK テキスト容量をネイティブに備えた 2D シンボル体系。
• JabCode — マルチシンボルカスケードを備えた多色 2D シンボル体系。
• rMQR — 狭く幅広いラベル向けの長方形 Micro QR バリアント。
• GS1 DataBar — GS1 の小売およびクーポンのシンボル体系ファミリー。
• GS1 Composite (CC-C) — GS1 アプリケーション識別子データを保持する、リンクされた 1D ベースに高密度 PDF417 2D 拡張コンポーネントを加えたもの。（CC-A および CC-B の 2D 拡張コンポーネントのエンコーディングは、このリリースではサポートされていません。サポートマトリクスを参照してください。）

各エンコーダーは、ページレンダラーが PDF コンテンツオペレーターに変換するバーコードデータオブジェクトを生成します。エンコーディングは決定論的です。同じ入力とオプションは常に同じモジュールパターンを生成し、署名済みおよびアーカイブ済みのドキュメントを再現可能に保ちます。

バーコード詳細リファレンスは、証拠を伴うシンボル体系ごとの サポートマトリクス を保持します。すべてのシンボル体系とバリアントについて、マトリクスは 3 つの状態のいずれかを記録します。リポジトリ内の適合性フィクスチャがそれを実行する（Verified）、実装サーフェスが専用のフィクスチャなしにそれを主張する（Claimed）、または範囲外である（Not supported）です。NextPDF はマトリクスを正直に報告します。エンコーダーを同梱しているがリファレンストレースフィクスチャを欠くバリアントは、過大に表示されるのではなく、バックフィルの注記とともに Claimed のままにとどまります。

なぜこの仕組みなのか

すべての Pro エンコーダーは純粋関数です。同じペイロードとオプションは常に同じモジュールマトリクスを生成し、隠れた状態やシードされたランダム性はありません。その決定論性が要となる設計判断です。これにより、バーコードは署名済みまたはアーカイブ済みのドキュメントをバイトストリームを乱すことなくラウンドトリップでき、再レンダリングが署名を無効化することは決してありません。また、適合性を監査可能にします。サポートマトリクスは各シンボル体系を保存されたリファレンストレースに固定し、ゴールデンファイルに対してビット単位で照合します。Core の BarcodeEncoderRegistry をフォークするのではなく拡張することで、これらの保証はオープンエディションと Pro エディションで同一に保たれます。

設計の背景：毎回同じバイト：再現可能な PDF。

API サーフェス

composer require nextpdf/pro:^3

Pro バーコードのパブリックサーフェスは、以下から構成されます。

• Pro の 2D エンコーダー（MicroQR、DotCode、HanXin、JabCode、RMQR、GS1DataBar、および GS1 Composite CC-C コンポーネントキー gs1-composite-cc-c）をバーコードエンコーダーレジストリに登録する、静的なサービスプロバイダーエントリーポイント。GS1 Composite CC-A および CC-B の 2D 拡張コンポーネントのエンコーディングは、このリリースではサポートされておらず、登録されません。
• 人間が読める AI 文字列と GS1 Digital Link URI の両方を受け付け、GS1-128、QR Code、Data Matrix のキャリア向けにエンコードされたバイト列を生成する、GS1 アプリケーション識別子パーサー。
• チェックディジット、AI 構造、日付ロジック、業界プロファイルの必須 AI 組み合わせをチェックする、GS1 サプライチェーンバリデーター。

完全な生成済みメソッドシグネチャテーブルは、バーコード詳細リファレンスにレンダリングされます。

コードサンプル — クイックスタート

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() の呼び出しは、アプリケーションがデフォルトなしで独自のレジストリを構成する場合の、サポートされるフォールバックです。
• 再登録はべき等です。2 回目の 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 サーフェスのみを文書化します。内部のネームスペースパス、ヘルパークラス、メカニズムテーブル、ランブックのファイル名、チケットプレフィックスは範囲外です。

関連項目

• Core barcode module
• Chart — NextPDF Pro
• Barcode deep reference