バーコード：1D および 2D シンボロジーエンコーダ

概要

バーコードモジュールは、シンボロジーの実装レイヤーです。リニアシンボロジー（Code 128、EAN、UPC、Interleaved 2 of 5、Codabar、郵便コード）とマトリックスシンボロジー（QR Code、Data Matrix、PDF417）をエンコードし、それぞれの誤り訂正を計算します。各エンコーダをバーコードコントラクトの背後に登録し、ドキュメントライターが結果を描画できるようにします。コントラクトの定義は別ページにあります。以下の注記を参照してください。

関心事ごとに 1 つの正規ページ。 エンコーダが満たすインターフェイス (Barcode1DEncoderInterface、Barcode2DEncoderInterface、 BarcodeEncoderInterface、Gs1DataParserInterface) は Contracts / Barcode に記載されています。このページでは、それらのコントラクトを実装する具体的なエンコーダを扱います。この 2 つは重複ではなく補完的な関係です。SPI についてはコントラクトページを参照してください。シンボロジーについては、このページを参照してください。

インストール

composer require nextpdf/core:^3

概念的な概要

バーコードエンコーダは、ペイロード文字列をモジュールマトリックス（2D）またはバーシーケンス（1D）に変換し、ライターはそれを PDF グラフィックスとして描画します。このモジュールには具体的なエンコーダが同梱されています。

Barcode1D はリニアエンジンです。BarcodeType は、サポートされるリニアシンボロジーとして、Code 39（チェックサムあり・なし）、Code 93、Code 128 ファミリー、EAN-8/EAN-13、UPC-A/UPC-E、Interleaved および Standard 2 of 5、Codabar、Code 11、POSTNET、PLANET、Intelligent Mail（IMB）、および MSI を列挙します。generate() は、バーパターンを記述する BarcodeData 値オブジェクトを返します。

2D エンコーダ — QrEncoder、DataMatrixEncoder、Pdf417Encoder — は BarcodeEncoderInterface を実装し、Barcode2DData マトリックスを返します。Barcode2DType は、エンジンが認識するマトリックスシンボロジーを列挙し、QR Code、Data Matrix、PDF417 を含みます。Micro QR、rMQR、GS1 DataBar、Han Xin などの追加シンボロジーも、レジストリルーティング用に列挙されています。対応するエンコーダセットはエディションによって異なります。マトリックスの誤り訂正は Galois 体上で計算されます。GaloisField と GaloisFieldPrime は、QR、Data Matrix、PDF417 の各エンコーダが共有する Reed-Solomon 演算を提供します。

BarcodeEncoderRegistry はルックアップ用のレジストリです。これは PSR-11 ContainerInterface を実装し、createDefault() を通じてデフォルト登録を提供し、resolve() でシンボロジーを対応するエンコーダに解決します。アプリケーションコードがエンコーダに直接アクセスすることはほとんどありません。高レベルの Document::write1DBarcode() / write2DBarcode() ファサードでシンボロジーを指定すると、レジストリがエンコーダを供給します。1D エンジンは @since 1.0.0 です。2D エンコーダは @since 1.3.0 です。レジストリは @since 3.0.0 です。

API サーフェス

クラス	主要メンバー	役割
`Barcode1D`	`generate(string $code, BarcodeType $type): BarcodeData`	リニアシンボロジーエンコーダ (`@since 1.0.0`)
`QrEncoder`	`encode(string $data, array $options = []): Barcode2DData`	QR Code エンコーダ (`@since 1.3.0`)
`DataMatrixEncoder`	`encode(string $data, array $options = []): Barcode2DData`	Data Matrix エンコーダ (`@since 1.3.0`)
`Pdf417Encoder`	`encode(string $data, array $options = []): Barcode2DData`	PDF417 エンコーダ (`@since 1.3.0`)
`BarcodeEncoderRegistry`	`createDefault()`, `register()`, `resolve()`, `has()`, `get()`, `registered()`	PSR-11 エンコーダレジストリ (`@since 3.0.0`)
`BarcodeType` / `Barcode2DType`	enum ケース	サポートされるシンボロジー列挙
`GaloisField` / `GaloisFieldPrime`	有限体演算	Reed-Solomon 誤り訂正

完全な PHPDoc テーブルを生成するには composer docs:generate-api-php -- --module=Barcode を実行してください。

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

ソース：examples/10-barcodes.php。ファサードはシンボロジーに基づき、レジストリ経由でエンコーダを解決します。

<?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->addPage();

$doc->write1DBarcode('4006381333931', BarcodeType::EAN13, x: 15, y: null, w: 60, h: 20);
$doc->write2DBarcode('https://nextpdf.dev', Barcode2DType::QRCode, x: 15, y: 40, w: 40, h: 40);

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

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

レジストリを通じて 2D エンコーダを直接解決し、ペイロードを制限してからエンコードします。

<?php

declare(strict_types=1);

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

use NextPDF\Barcode\Barcode2DType;
use NextPDF\Barcode\BarcodeEncoderRegistry;
use NextPDF\Exception\BarcodeException;
use Psr\Log\LoggerInterface;

final readonly class TrackingCodeService
{
    private const int MAX_PAYLOAD = 512;

    public function __construct(
        private BarcodeEncoderRegistry $registry,
        private LoggerInterface $logger,
    ) {}

    /** @return \NextPDF\Barcode\Barcode2DData */
    public function encode(string $trackingId): \NextPDF\Barcode\Barcode2DData
    {
        if (strlen($trackingId) > self::MAX_PAYLOAD) {
            throw new \LengthException('Tracking payload exceeds the encode bound.');
        }

        try {
            $encoder = $this->registry->resolve(Barcode2DType::QRCode->value);

            return $encoder->encode($trackingId, ['errorCorrection' => 'high']);
        } catch (BarcodeException $e) {
            $this->logger->error('Barcode encode failed', ['error' => $e->getMessage()]);

            throw $e;
        }
    }
}

エッジケースと注意点

シンボロジーの文字セットやチェックディジット規則に違反するリニアペイロードは BarcodeException を発生させます。EAN/UPC はチェックディジットを計算して付加します。事前に付加しないでください。
2D の $options 配列はシンボロジー固有です（たとえば QR の誤り訂正レベルなど）。不明なキーは、ほとんどのエンコーダで無視されます。キーはエンコーダ自身のドキュメントと照合して確認してください。
Barcode2DType は、コアエディションにエンコーダが同梱されている範囲よりも多くのシンボロジーを列挙します。BarcodeEncoderRegistry::resolve() は、未登録のシンボロジーに対してプレースホルダーを返すのではなく例外を発生させます。
登録済みのエンコーダは共有インスタンスです。コンストラクタでの構成を除き、ステートレスに保ってください。呼び出しごとの状態は同時レンダリングを損ないます。
過度に長いペイロードは、より密で大きなマトリックスを生成します。シンボルサイズに起因するサービス拒否を避けるため、エンコード前にペイロード長を制限してください。

パフォーマンス

エンコードコストは、レジストリルックアップ（O(1)）ではなく、ペイロード長とマトリックスサイズに比例します。短い Code 128 ペイロードはマイクロ秒単位でエンコードされます。高い誤り訂正を指定した密な QR Code が最も重いケースです。マルチシンボルのサンプルページでは、1500 ms ウォール / 64 MB ピークの予算内に収まります。再現性プロファイルは bitwise です。同じペイロードとオプションは常に同じモジュールマトリックスと同じ描画バイトを生成します。

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

バーコードペイロードは、スキャンされた URL、シリアル番号、トラッキングコードなど、攻撃者の影響を受けることがよくあります。エンコーダはバイトをエンコードするだけで、それらを解釈しません。敵対的な URL をエンコードした QR Code も有効な QR Code であるため、ペイロードを信頼するかどうかは利用者の責任です。マトリックスサイズ（ひいては処理量と出力サイズ）を予算内に保つため、エンコード前にペイロード長を制限してください。どこかでバーコードからデコードされたデータがアプリケーションに再び入る際は、信頼できない入力として扱ってください。エンジンの脅威モデルについては /modules/core/security/ を参照してください。

適合性

主張	標準	参照
QR Code シンボルの QR Code マトリックスシンボロジー仕様への準拠	ISO/IEC 18004	QR Code シンボロジー
Data Matrix シンボルの Data Matrix シンボロジー仕様への準拠	ISO/IEC 16022	Data Matrix シンボロジー
PDF417 シンボルの PDF417 シンボロジー仕様への準拠	ISO/IEC 15438	PDF417 シンボロジー
Code 128 シンボルの Code 128 リニアシンボロジー仕様への準拠	ISO/IEC 15417	Code 128 シンボロジー
EAN/UPC シンボルの EAN/UPC シンボロジー仕様への準拠	ISO/IEC 15420	EAN/UPC シンボロジー

これらのシンボロジー標準は検証可能な引用コーパスに存在しないため、reference_id は記録されません。エンジンは要件をパラフレーズし、出典を番号と条項で引用します。正式なエンコード規則については、公開されている標準を参照してください。エンコーダは tests/Unit/Barcode/ によって検証されます。シンボロジー仕様に対する正しさはテストスイートで担保される範囲であり、エンドツーエンドの PDF 適合性を述べるものではありません。