Pro エディション

Barcode — 詳細リファレンス

概要

NextPDF Pro のバーコードサーフェスは、Core のバーコードモジュールの上に特殊 2D およびサプライチェーンシンボロジーを追加します。レジストリで解決される 6 つの 2D エンコーダー（Micro QR、DotCode、Han Xin Code、JabCode、rMQR、GS1 DataBar）、1 つの GS1 Composite 2D コンポーネントエンコーダー（CC-C）、USPS Intelligent Mail 1D エンコーダー、そして GS1 Application Identifier パーサーとサプライチェーンバリデーターを同梱します。エンコーディングは決定的です。同じペイロードとオプションは常に同一のモジュールマトリックスを生成します。このページでは、パブリック API、挙動契約、失敗モード、そしてシンボロジーごとの適合性エビデンスを述べます。

提供とライセンス

この機能は NextPDF Pro（nextpdf/pro）で提供され、Pro ティアのライセンスエンベロープで有効化されます。そのエンタイトルメントのないデプロイメントは、この機能のクラスをロードしません。エディションを比較してライセンスを取得。

composer require nextpdf/pro:^3

各シンボロジーは、ライセンスエンベロープの中で独自のケーパビリティ名をバインドします：barcode.microqr、barcode.dotcode、barcode.hanxin、barcode.jabcode、barcode.rmqr、barcode.gs1databar、barcode.gs1-composite-cc-c。ケーパビリティがライセンスされていない場合、レジストリはそのエンコーダーを解決しません。GS1 Composite CC-A および CC-B のフルシンボルエンコーディングはサポートされていない（サポートステータス表を参照）ため、barcode.gs1-composite-cc-a / barcode.gs1-composite-cc-b キーは登録されません。

パブリック API サーフェス

レジストリキーは、Core の NextPDF\Barcode\Barcode2DType ケース値と、リテラルキー gs1-composite-cc-c から構成されます。レジストリで解決されるエンコーダーでは、エンコーダーの FQCN ではなくレジストリキーが安定した契約です。

シンボル	パラメーター	既定の挙動	戻り値	スロー / 失敗	注記
`BarcodeProServiceProvider::register()`	`BarcodeEncoderRegistry $registry`	7 つの Pro レジストリキーをすべてバインド	`void`	—	静的。冪等 — 2 回目の呼び出しは最初のバインディングを置き換え
`MicroQrEncoder::encode()`	`$data`；オプション `ecLevel`（`'L'`、`'M'`、`'Q'`；既定 `'L'`）、`version`（1–4 または null）、`mask`（0–3 または null）	適合する最小バージョン M1–M4 を自動選択	`Barcode2DData`	`InvalidArgumentException`	サポートされない `'H'` は暗黙のうちに `'L'` に強制変換（フェイルクローズドな EC 選択が必要な呼び出し元は事前検証が必須）。M1 は `ecLevel` を無視
`DotCodeEncoder::encode()`	`$data`；オプション `gs1`（bool、既定 false）、`columns`（int）、`rows`（int）、`ratio`（float、既定 1.5）	幅:高さ 1.5 でグリッドを自動サイジング	`Barcode2DData`	`InvalidArgumentException`	グリッド寸法は軸ごとに強制指定可能
`HanXinEncoder::encode()`	`$data`；オプション `ecLevel`（0–3、既定 1）、`version`（1–84、既定 auto）	適合する最小バージョン	`Barcode2DData`	`InvalidArgumentException`	ISO/IEC 20830 に準拠した GB 2312 Region 1/2 テキストモード
`JabCodeEncoder::encode()`	`$data`；オプション `colors`（4, 8, 16, 32, 64, 128, 256；既定 8）、`eccLevel`（0–10、既定 3）、`symbolNumber`（1–61、既定 1）、`symbolVersions`、`symbolPositions`、`symbolEccLevels`	単一の 8 色シンボル	`BarcodeColorData`	`InvalidArgumentException`、`JabCodeEncodingException`	パレット付きのポリクロームモジュールマトリックス
`RmqrEncoder::encode()`	`$data`；オプション `ecLevel`（既定 `RmqrConstants::EC_M`、または `EC_H`）、`version`（例：`'R7x43'`、既定 auto）	32 の ISO/IEC 23941 バージョンのうち適合する最小のもの	`Barcode2DData`	`InvalidArgumentException`	容量を超えるペイロードを拒否。切り詰めは決して行わない
`Gs1DataBarEncoder::encode()`	`$data`；オプション `variant`（`Gs1DataBarVariant`、既定 `OMNIDIRECTIONAL`）、`linkage`（bool、既定 false）、`height`（int、既定はバリアント最小値；Expanded Stacked では行ごと）、`segmentsPerRow`（int、既定 4；Expanded Stacked のみ）	GTIN 入力（§5/§6 ファミリー）または GS1 AI エレメント文字列（§7 ファミリー）をエンコード	`Barcode2DData`	`InvalidArgumentException`；`InvalidSymbolStructureException`	7 つの ISO/IEC 24724 Annex J バリアントすべてをエンコード
`Gs1DataBarVariant`	—	`isImplemented()` は 7 ケースすべてで true を返す	列挙型（7 ケース）	—	Annex J に準拠した `minimumHeightX()` と `defaultHeightX()`
`ImbEncoder::encode()`	`string $code`（20, 25, 29, または 31 桁）	65 本の 4 ステートバー	`BarcodeData`	`InvalidArgumentException`	1D エンコーダーインターフェイス。2D レジストリキーではない
`ImbEncoder::encodeToString()`	`string $code`	バー状態を T/A/D/F 文字列として	`string`	`InvalidArgumentException`	USPS リファレンスベクターとの照合用
`Gs1DataParser::parse()`	`string $data`	Digital Link URI を自動検出、それ以外は `(AI)value` 形式	`Gs1ParsedData`	`InvalidArgumentException`	Core の `Gs1DataParserInterface` 契約を実装
`Gs1DataParser::parseDigitalLink()`	`string $uri`	GS1 Digital Link URI を解析	`Gs1ParsedData`	`InvalidArgumentException`	—
`Gs1DataParser::encodeForCode128()` / `::encodeForQrCode()` / `::encodeForDataMatrix()`	`object $parsed`	そのキャリアの FNC1 規約を用いたキャリアバイトシーケンス	`string`	—	`Gs1ParsedData` インスタンスを期待
`Gs1DataParser::validateAI()`	`string $ai`、`string $value`	1 つの AI 値の構造チェック	`bool`	—	—
`Gs1Validator::validate()`	`string $barcodeData`、`Gs1SupplyChainProfile $profile`（既定 `NONE`）	`run()` に対する静的なクイックパス	`Gs1ValidationResult`	—	解析失敗は例外ではなく所見となる
`Gs1Validator::run()`	`validate()` と同じ	解析、チェックデジット、日付、クロス AI ルール、プロファイル	`Gs1ValidationResult`	—	インスタンスパス。コンストラクターは注入されたパーサーを受け付ける
`Gs1SupplyChainProfile`	—	`NONE` はプロファイルルールをスキップ	列挙型（5 ケース）	—	`RETAIL`、`FOOD`、`PHARMA`、`LOGISTICS`、`NONE`；`requiredAIs()`、`recommendedAIs()`、`primaryIdentifiers()`
`Gs1ValidationResult`	—	構築時に所見を重大度で分割	readonly クラス	—	`isValid`、`findings`、`errors`、`warnings`、`infos`、`parsedData`；`passes()`、`fails()`、`totalFindings()`
`Gs1ValidationFinding` / `Gs1FindingSeverity`	—	`severity`、`ruleId`、`message`、オプションの `ai` と `suggestion`	readonly クラス / 列挙型	—	重大度：`Error`、`Warning`、`Info`
`CompositeComponentA::codewordsFor()`	`string $data`	§5 汎用バイナリ文字列エンコーデーション、base-928 変換、ラウンドトリップ自己チェック	`list<int>`（各 0–927）	`InvalidArgumentException`	`linkFor()` または外部 CC-A キャリアレンダラーに供給
`CompositeComponentA::encode()`	無視	CC-A のフルシンボルレンダリングを拒否	—	`UnsupportedBarcodeFeature`（常に）	フェイルクローズド。「エッジケース」を参照
`CompositeComponentB::encode()`	無視	CC-B の 2D エンコーディングを拒否	—	`UnsupportedBarcodeFeature`（常に）	`linkFor()` は引き続き利用可能（CCSI 901）
`CompositeComponentC::encode()`	`$data`；オプションは PDF417 キャリアに転送；`carrierType`（既定 `GS1_128`）	CCSI コードワード 920 を先頭に置いた完全な PDF417 キャリア	`Barcode2DData`	`BarcodeException`；`CompositeLinkageException`	`GS1_128` キャリアのみが許容される
`CompositeComponent{A,B,C}::linkFor()`	`string $carrierId`、`array $codewords`、`CompositeCarrierType $carrierType`	コンポーネントコードワードを 1D キャリアと対にする	`CompositeLinkage`	`CompositeLinkageException`	キャリアの許容性と容量を強制
`CompositeVariant` / `CompositeCarrierType`	—	`CC_A`、`CC_B`、`CC_C`；`GS1_DATABAR`、`GS1_128`	列挙型	—	`maxCodewords()`、`ccsi()`、`allowedCarriers()`、`usesFullPdf417()`

エントリーポイントのシグネチャ

public static function register(BarcodeEncoderRegistry $registry): void

public function encode(string $data, array $options = []): Barcode2DData

public static function validate(
    string $barcodeData,
    Gs1SupplyChainProfile $profile = Gs1SupplyChainProfile::NONE,
): Gs1ValidationResult

public function run(
    string $barcodeData,
    Gs1SupplyChainProfile $profile = Gs1SupplyChainProfile::NONE,
): Gs1ValidationResult

public function parse(string $data): Gs1ParsedData
public function parseDigitalLink(string $uri): Gs1ParsedData
public function encodeForCode128(object $parsed): string
public function encodeForQrCode(object $parsed): string
public function encodeForDataMatrix(object $parsed): string
public function validateAI(string $ai, string $value): bool

public function codewordsFor(string $data): array

挙動契約

レジストリ解決

Core の既定レジストリファクトリは、Pro のエンコーダーを遅延型かつケーパビリティライセンス付きのエントリーとして事前バインドします。BarcodeProServiceProvider::register() は、既定なしでレジストリを構成するアプリケーション（例：独自のコンテナーを持つフレームワーク統合）のためのサポートされたフォールバックです。各エンコーダーは、文字列ペイロードとシンボロジーごとのオプションを、ページレンダラーが PDF コンテンツ演算子に変換するバーコードデータオブジェクトに変換します。

GS1 の解析と検証

Gs1DataParser は、人間が読める AI 文字列（(01)09521234543213(17)260131）と GS1 Digital Link URI を受け付けます。GS1-128、QR Code、Data Matrix のキャリア向けにエンコードされたバイトシーケンスを生成し、各キャリアの FNC1 およびグループセパレーター規約を適用します。Gs1Validator は、解析、チェックデジット（GTIN、SSCC）、日付ロジック、クロス AI ルール、業界プロファイルの必須 AI という 5 ステップのパイプラインを実行します。解析失敗は所見を伴う無効な結果を生成し、スローはしません。所見は、エラー、警告、情報という重大度で分割されます。

GS1 DataBar のバリアントディスパッチ

Gs1DataBarEncoder::encode() は、7 つの ISO/IEC 24724:2011 Annex J バリアントすべてを 1 つのオプション契約を通じてディスパッチします。Omnidirectional、Truncated、Stacked、Stacked Omnidirectional は、mod-79 チェックキャラクターを伴う §5 のエレメント幅代数を共有します。Limited は、mod-89 チェックキャラクターを伴う独自の §6 シンボルキャラクター代数を使用します。Expanded と Expanded Stacked は §7 の (17,4) 代数を使用します：§7.2.5.5 の 3 モード数値、英数字、ISO/IEC 646 コンパクション状態機械に、mod-211 チェックキャラクター（§7.2.6）を加えたものです。§5/§6 ファミリーは、mod-10 チェックデジットを伴う 14 桁の GTIN-14、または 13 桁の商品識別を取ります。§7 ファミリーは、生の GS1 AI エレメント文字列（数字、文字、ISO/IEC 646 句読点サブセット、バイト 0x1D としての FNC1）を取ります。linkage オプションは、GS1 Composite シンボルのリニアコンポーネントとして使用するために 2D コンポーネントリンケージフラグを設定します。

GS1 Composite コンポーネント

CC-C は、完全な PDF417 キャリア上で完全な 2D 拡張コンポーネントを生成し、必須の CCSI コードワード 920 を先頭のデータコードワードとして注入します（ISO/IEC 24723:2010 §5.4）。CC-A は、codewordsFor() を通じて適合する base-928 データコードワードを生成し、フェイルクローズドなエンコード・デコードのラウンドトリップ自己チェックを伴いますが、フルシンボルレンダリングは拒否します。CC-B は 2D エンコーディングを全面的に拒否します。linkFor() は、コンポーネントコードワードを CompositeLinkage 値として 1D キャリアと対にし、キャリアの許容性と容量を強制します。

エッジケースと失敗モード

すべてのエンコーダーは、空のペイロードを InvalidArgumentException で拒否します。
Micro QR：サポートされない H エラー訂正レベルを要求すると、失敗する代わりに暗黙のうちに L に強制変換されます（フェイルクローズドな EC 選択が必要な場合はオプションを事前検証してください）。これは、ISO/IEC 18004 が Micro QR シンボルに対して L、M、Q のみを定義しているためです。
rMQR：エラー訂正レベルは M または H でなければなりません。32 のバージョンの容量を超えるペイロードは、切り詰められることなく拒否されます。
JabCode：サポートされる 2 のべき乗のセット外の色数、0–10 の範囲外の ECC レベル、1–61 の範囲外のシンボル数は拒否されます。下流のエンコーディング失敗は JabCodeEncodingException を発生させます。
GS1 DataBar：§5/§6 ファミリーは GTIN の mod-10 チェックデジットを検証し、Limited は指標桁を 0 または 1 に制限します。§7 ファミリーは、エンコード不可能な文字と、末尾または重複した FNC1 セパレーターを拒否します。Expanded Stacked は、行ごとの奇数のシンボルキャラクター数と、34X 最小値未満の行ごとの高さを拒否します。内部構造の自己チェックは、不正な形式のシンボルを出力するのではなく InvalidSymbolStructureException で失敗します。
GS1 Composite：CC-A と CC-B の encode() は常に UnsupportedBarcodeFeature をスローします（フェイルクローズド）。CC-C は、空のデータまたは PDF417 の容量オーバーフロー（925 コードワード超）で BarcodeException を、許容されないキャリアで CompositeLinkageException をスローします。
GS1 検証は、エンコーディングの前に不正な形式の AI 構造と不正なチェックデジットをフラグします。無効なサプライチェーン文字列が、スキャン可能な適合シンボルを生成することは決してありません。
IMB は、20、25、29、または 31 桁の入力のみを受け付けます。
バーコードエンコーディングは暗号処理を一切行いません。FIPS モード固有の挙動はありません。エンコーダーは FIPS プロファイルにかかわらず同一に実行されます。

適合性

NextPDF は、下記に引用する公開された標準に対してこれらのシンボロジーを実装し、テストスイートにリファレンストレースを固定しています。このページの記述はケーパビリティの主張です：サポートは適合性ではなく、適合性は認証ではありません。NextPDF はシンボロジー認証を保持していません。節アンカーは、製品ソースとその適合性フィクスチャからパラフレーズされています。コンプライアンスエンジンのコーパスはバーコードシンボロジー標準をカバーしていないため、下記のアンカーはリファレンス識別子のない製品由来のものです。

サーフェス	標準	節アンカー（パラフレーズ）
GS1 DataBar element-width algebra	ISO/IEC 24724:2011	§5.2 symbol-character structure; Annex F.1 worked example (Omnidirectional); Annex F.2 (Limited); Annex F.3 (Expanded)
GS1 DataBar stacked layouts	ISO/IEC 24724:2011	§5.4 Stacked; §5.5 Stacked Omnidirectional; §7.2.8 Expanded Stacked row partition and separators
GS1 DataBar Expanded encodation	ISO/IEC 24724:2011	§7.2.5.5 three-mode compaction state machine; §7.2.6 mod-211 check character
GS1 Composite linkage and CC-C	ISO/IEC 24723:2010	§5.4 CCSI codeword semantics; §5.1 carrier admissibility
GS1 Composite CC-A codewords	ISO/IEC 24723:2010	§5 general-purpose binary-string encodation with base-928 conversion
rMQR symbol structure	ISO/IEC 23941:2022	§6.3.2 Table 1 version dimensions; §7.8.2 fixed mask; Annex C / Annex I format-information reference
Micro QR	ISO/IEC 18004	Micro QR M1–M4 capacity and format information
Han Xin Code	ISO/IEC 20830:2021	Symbol structure; finder and alignment patterns; GB 2312 Region 1/2 modes; Reed–Solomon ECC; masking
JabCode	ISO/IEC 23634	Symbol, colour, and ECC structure
Postal symbology	USPS-B-3200	Intelligent Mail Barcode field structure

シンボロジーごとのサポートステータス

バリアントが Verified となるのは、pro/tests/** のフィクスチャがそれを行使する場合で、望ましくは公開されたワークドエグザンプルに固定されたリファレンストレースです。専用フィクスチャのない出荷済みバリアントは Claimed のままです。エンコーダーのないバリアントは Not supported です。

シンボロジー / バリアント	ステータス	エビデンス（テストパス）	注記
Micro QR (M1–M4)	Verified	`pro/tests/Unit/Barcode/MicroQrEncoderTest.php`	ユニットレベル。ワークドエグザンプルのリファレンストレースフィクスチャは追跡対象のバックフィル
DotCode	Verified	`pro/tests/Unit/Barcode/DotCodeEncoderTest.php`；`DotCodeGfArithmeticTest.php`	ガロア体演算をカバー。ベンダーデコーダーのラウンドトリップなし
Han Xin Code	Verified	`pro/tests/Unit/Barcode/HanXinEncoderTest.php`；`HanXinRsEncodingTest.php`	リード・ソロモンエンコーディング経路を明示的に行使
JabCode (1–61 symbols, 4–256 colors, ECC 0–10)	Verified	`pro/tests/Unit/Barcode/JabCode/JabCodeEncoderTest.php`（同ディレクトリ内の 11 コンポーネントスイート）	マルチシンボルカスケードと ECC 範囲を行使。ベンダーデコーダーのラウンドトリップなし
USPS Intelligent Mail Barcode	Verified	`pro/tests/Unit/Barcode/ImbEncoderTest.php`；`ImbRoutingCodeTest.php`	ルーティングコードと 20/25/29/31 桁の長さ検証を行使
rMQR — all 32 ISO/IEC 23941 versions	Verified	`pro/tests/Conformance/Barcode/Rmqr/AnnexValidatedSizesTest.php`；`RmqrAnnexCFormatInfoTest.php`；`pro/tests/Unit/Barcode/Rmqr/RmqrEncoderTest.php`	バージョンと EC のペアを ISO/IEC 23941 Table 1、Annex C / Annex I の format-information リファレンス値に対して検証
GS1 DataBar — Omnidirectional / Truncated	Verified	`pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarReferenceTest.php`	Annex F.1 のワークドエグザンプルと byte-equal。Truncated は同一のエンコーディングを高さを低減して共有
GS1 DataBar — Stacked / Stacked Omnidirectional	Verified	`pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarStackedReferenceTest.php`	Annex F.1 トレースから派生した行分割。§5.4 と §5.5 に準拠したセパレーター構築
GS1 DataBar — Limited	Verified	`pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarLimitedReferenceTest.php`；`pro/tests/Unit/Barcode/Gs1DataBar/Gs1DataBarLimitedEncoderTest.php`	Annex F.2 のワークドエグザンプル（item 00098765432105）と byte-equal
GS1 DataBar — Expanded	Verified	`pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarExpandedReferenceTest.php`；`pro/tests/Integration/Barcode/Gs1DataBarExpandedTwoDecoderTest.php`	Annex F.3 のワークドエグザンプル（`(10)12A`）と byte-equal。zxing-cpp と ZBar に対する独立デコーダーのラウンドトリップ
GS1 DataBar — Expanded Stacked	Verified	`pro/tests/Unit/Barcode/Gs1DataBar/Gs1DataBarExpandedEncoderTest.php`（stacked ケース）；上記の統合ラウンドトリップ	単一行 Expanded と同じデータパイプライン。§7.2.8 の行分割とセパレーターをアサート
GS1 Composite — CC-C (PDF417 carrier)	Verified	`pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentCTest.php`；`CompositeRoundtripTest.php`；`CompositeLinkageTest.php`	CCSI コードワード 920 とリンケージフラグの相互作用をカバー
GS1 Composite — CC-A	Partial	`pro/tests/Unit/Barcode/Gs1Composite/CompositeComponentACodewordTest.php`；`pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentATest.php`	コードワード生成は Verified（base-928、ラウンドトリップ自己チェック）。フルシンボルレンダリングは非サポート — `encode()` はフェイルクローズド
GS1 Composite — CC-B	Not supported	`pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentBTest.php`（フェイルクローズドな拒否をアサート）	2D エンコーディングなし。リンケージヘルパー（CCSI 901）は引き続き利用可能
GS1 AI parser	Verified	`pro/tests/Unit/Barcode/Gs1DataParserTest.php`；`Gs1DataParserFnc1Test.php`	両方の入力形式と 3 つすべてのキャリアバイトシーケンス出力を行使
GS1 supply-chain validator	Verified	`pro/tests/Unit/Barcode/Gs1ValidatorTest.php`；`Gs1ValidatorCrossAiTest.php`；`pro/tests/Unit/Barcode/Gs1/Gs1ValidatorDateValidationEdgeCaseTest.php`	チェックデジット、クロス AI の必須組み合わせ、日付ロジックを行使

開発ノート

このページのエビデンスアンカーは pro/tests/** 配下のテストパスです。このモジュールに examples/ ディレクトリは同梱されません。
「提供とライセンス」に挙げた 7 つのケーパビリティ名は、サービスプロバイダーがバインドするキーです。IMB エンコーダーは直接構築され、レジストリキーを持ちません。
CC-A は汎用エンコーデーション方式のみを出力します。アプリケーション固有の圧縮方式は、正確性のギャップではなく、文書化された密度上の残余です。

公開範囲

このページは、外部から観測可能な挙動とサポートされたパブリック API サーフェスのみを文書化します。内部の名前空間パス、ヘルパークラス、メカニズム表、ランブックのファイル名、チケットプレフィックスは対象外です。