契約 / バーコード

概要

バーコードドメインには、4 つの契約があります。1D エンコーダー、2D エンコーダー、レジストリから検出できる汎用エンコーダー、そして GS1 データパーサーです。これらは、エンコーダーが満たすべき形を定義します。シンボロジーの実装は、これらの契約に対して登録されます。

インストール

composer require nextpdf/core:^3

概念的な概要

バーコードエンコーダーは、ペイロード文字列を PDF ライターが描画するモジュールマトリックスへ変換します。NextPDF は、契約を次元数で分けています。Barcode1DEncoderInterface は、線形シンボロジー（Code 128、EAN-13 など）をエンコードし、BarcodeData 値オブジェクトを返します。Barcode2DEncoderInterface は、マトリックスシンボロジー（QR Code、Data Matrix）をエンコードします。これは、エラー訂正レベルなど、シンボロジー固有のパラメーター用オプションマップを備えた Barcode2DData 値オブジェクトを返します。

BarcodeEncoderInterface は、汎用サービスプロバイダー向けの契約です。BarcodeEncoderRegistry を通じて検出される 2D エンコーダーは、これを実装します。この契約は、モノクロの Barcode2DData またはカラーの BarcodeColorData マトリックスのいずれかを返します。そのため、登録済みエンコーダーは、別のインターフェイスを追加せずにカラーシンボルを生成できます。エンコーダーは、構築時の構成を超える状態を持たないことが期待されます。レジストリは、登録された型ごとに 1 つの共有インスタンスを渡すため、呼び出しごとの状態を持つことは欠陥になります。

Gs1DataParserInterface は、構造化データを扱う契約です。GS1 要素文字列を型付きオブジェクトに解析し、そのオブジェクトを QR Code、Data Matrix、または Code 128 キャリア向けに再エンコードします。これにより、GS1 文法はシンボロジーから分離されます。パーサーは、Application Identifier を一度だけ検証します。キャリア固有のメソッドは、同じ解析済み構造を各ターゲット向けにフォーマットします。この 4 つの契約は stable です。BarcodeEncoderInterface は 3.0.0 以降 stable で、その他は 1.0.0 以降です。新しいメソッドは、デフォルト実装を伴う場合にのみ追加されます。

API サーフェス

型	種別	主なメンバー	安定性	導入バージョン
`Barcode1DEncoderInterface`	interface	`encode(string): BarcodeData`	stable	1.0.0
`Barcode2DEncoderInterface`	interface	`encode(string, array): Barcode2DData`	stable	1.0.0
`BarcodeEncoderInterface`	interface	`encode(string, array): Barcode2DData\|BarcodeColorData`	stable	3.0.0
`Gs1DataParserInterface`	interface	`parse()`, `encodeForQrCode()`, `encodeForDataMatrix()`, `encodeForCode128()`	stable	1.0.0

2D 契約の $options 配列は、シンボロジー固有です（たとえば、QR Code のエラー訂正レベルなど）。この契約は、そのキーを制約しません。登録された各エンコーダーが、独自のオプションセットをドキュメント化します。

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

<?php

declare(strict_types=1);

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

use NextPDF\Barcode\Barcode2DType;
use NextPDF\Barcode\BarcodeType;
use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Barcode Examples');
$doc->addPage();

$doc->setFont('helvetica', '', 10);
$doc->cell(0, 6, 'Code 128:', newLine: true);
$doc->write1DBarcode('NEXTPDF-2026', BarcodeType::C128, x: 15, y: null, w: 80, h: 20);
$doc->ln(28);

$doc->cell(0, 6, 'QR Code (URL):', newLine: true);
$doc->write2DBarcode('https://nextpdf.dev', Barcode2DType::QRCode, x: 15, y: null, w: 40, h: 40);

$doc->save(__DIR__ . '/output/10-barcodes.pdf');

write1DBarcode() と write2DBarcode() は、レジストリを通じてエンコーダーを解決します。アプリケーションコードが契約に直接触れることはまれです。シンボロジーを名前で指定すると、レジストリがエンコーダーを提供します。

コードサンプル — プロダクション

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\Barcode2DEncoderInterface;
use NextPDF\Contracts\Gs1DataParserInterface;
use NextPDF\Exception\BarcodeException;
use Psr\Log\LoggerInterface;

final readonly class Gs1LabelService
{
    public function __construct(
        private Gs1DataParserInterface $parser,
        private Barcode2DEncoderInterface $dataMatrix,
        private LoggerInterface $logger,
    ) {}

    /**
     * Parse a GS1 element string and encode it as a Data Matrix.
     *
     * @param string $elementString A GS1 element string with Application Identifiers.
     */
    public function encodeLabel(string $elementString): \NextPDF\Barcode\Barcode2DData
    {
        try {
            $parsed = $this->parser->parse($elementString);
            $payload = $this->parser->encodeForDataMatrix($parsed);

            return $this->dataMatrix->encode($payload, ['errorCorrection' => 'high']);
        } catch (BarcodeException $e) {
            $this->logger->error('GS1 label encoding failed', [
                'error' => $e->getMessage(),
            ]);

            throw $e;
        }
    }
}

このサービスは、パーサー契約とエンコーダー契約に依存します。catch ブロックでは、具体的な BarcodeException をログに記録して再スローし、素の \Exception は決してスローしません。

エッジケースと注意点

登録されたエンコーダーは共有されます。エンコーダーに呼び出しごとの状態を保存すると、同時実行中のレンダリングが壊れます。エンコーダーは、コンストラクターの構成を超える状態を持たないようにしてください。
BarcodeEncoderInterface::encode() は、カラーまたはモノクロのデータを返す場合があります。これを利用するコードは、モノクロを前提とせず、Barcode2DData と BarcodeColorData の両方を処理する必要があります。
2D の $options 配列は、契約では検証されません。不明なキーは、ほとんどのエンコーダーで警告なしに無視されます。キー名は、エンコーダー自身のドキュメントと照合して確認してください。
GS1 の解析は、文法に厳密です。不明な Application Identifier を含む要素文字列は、部分的な解析結果を生成せず、BarcodeException を発生させます。上流の入力を検証してください。
1D 契約と 2D 契約は、互換性がありません。QR ペイロードを 1D エンコーダーに渡すと、無効なシンボルが生成されます。レジストリはシンボロジー型に基づいてルーティングするため、契約を直接呼び出すよりもレジストリを優先してください。

パフォーマンス

エンコードコストは、契約ではなく、ペイロード長とターゲットマトリックスのサイズに比例します。短い Code 128 ペイロードは、マイクロ秒単位でエンコードされます。高いエラー訂正を備えた高密度の QR Code は、2D の中で最も重いケースです。それでも、複数シンボルのサンプルページの performance_budget（実時間 1500 ms、ピーク 64 MB）には十分収まります。マトリックスは一度だけ計算され、PDF 演算子として描画されます。同じペイロードとオプションは常に同じモジュールマトリックスを生成するため、再現性は bitwise です。レジストリの検索は O(1) です。処理の中心は、シンボロジーのアルゴリズムです。

セキュリティに関する注意

バーコードのペイロードは、攻撃者が影響を及ぼせる場合がよくあります。スキャンされた URL、シリアル番号、トラッキングコードなどが該当します。契約はバイトをエンコードするだけで、それらを解釈しません。悪意のある URL をエンコードした QR Code も有効な QR Code であるため、ペイロードの信頼性はエンコーダーではなく利用側の責任です。過大なシンボルによるサービス拒否を回避するため、マトリックスサイズを制限し、エンコード前にペイロード長を制約してください。GS1 パーサーは不正な形式の Application Identifier を拒否し、これにより 1 つのインジェクションサーフェスが除去されます。有効なフィールドの意味的な内容までは精査しません。デコードされたバーコードデータは、アプリケーションに再び入る箇所では常に信頼できない入力として扱ってください。

適合性

主張	規格	参照
QR Code シンボルの QR Code マトリックスシンボロジー仕様への準拠	ISO/IEC 18004	QR Code シンボロジー
Data Matrix シンボルの Data Matrix シンボロジー仕様への準拠	ISO/IEC 16022	Data Matrix シンボロジー
Code 128 シンボルの Code 128 線形シンボロジー仕様への準拠	ISO/IEC 15417	Code 128 シンボロジー
GS1 要素文字列の GS1 Application Identifier 文法に従った解析	GS1 General Specifications	Application Identifier

これらの規格は、番号と条項で参照されます。検証可能な引用コーパスには存在しないため、reference_id は記録されません。エンジンは要件を言い換え、出典を引用します。権威あるエンコードルールについては、公開されている規格を参照してください。

商用コンテキスト

Core はエンコーダー契約を定義して固定し、共通のシンボロジーを提供します。Pro エディションと Enterprise エディションは、同じ BarcodeEncoderInterface に対して、追加のバーコードシンボロジー向けの拡張エンコーダーセットを登録します。そのため、商用デプロイメントは API を変更せずにシンボロジーのカバレッジを広げられます。Core は、BarcodeEncoderRegistry を通じて登録済みエンコーダーを解決します。契約のサーフェスは、すべてのエディションで同一です。