PDF に 1D および 2D バーコードを生成する

概要

このレシピでは、1D および 2D バーコードを PDF ページに直接描画します。Core の HasBarcodes トレイトは、write1DBarcode() と write2DBarcode() を提供します。どちらも現在のページにネイティブの PDF パス演算子としてシンボルを描画するため、出力はシンプルで決定論的なベクターコンテンツになります。このレシピは examples/10-barcodes.php に沿っています。

インストール

composer require nextpdf/core:^3

追加の拡張機能は必要ありません。バーコードエンコーダーは純粋な PHP で実装されており、シンボルは標準の PDF 矩形演算子（ISO 32000-2 §8.5）で描画されます。

概念的な概要

バーコードは画像として埋め込まれるのではなく、描画されます。ペイロードとは、製品番号や Web アドレスなど、エンコード対象のデータを指します。

write1DBarcode() は、選択した BarcodeType に対してペイロードを bar/space パターンにエンコードし、塗りつぶされた矩形のシーケンスを出力します。write2DBarcode() は、選択した Barcode2DType に対してモジュールマトリックスを構築し、暗いモジュールごとに塗りつぶされた矩形を 1 つ出力します。Data Matrix と QR Code はリードソロモン誤り訂正を使用するため、シンボルの一部が損傷していてもスキャナーがデータを復元できます。

各モジュールはエントロピーソースを持たない決定論的な re … f パスであるため、バーコードのコンテンツ自体は完全に再現可能です。再現性プロファイルが structural であるのは、周囲のドキュメントには保存ごとのアトム、つまりトレーラーの /ID と /CreationDate および /ModDate タイムスタンプが依然として含まれるためです。ハーネスは、それらのアトムを取り除いた qpdf 正規化済みの構造を比較します。

API サーフェス

NextPDF\Core\Concerns\HasBarcodes（Document にミックスイン）：

write1DBarcode(string $code, BarcodeType $type, ?float $x = null, ?float $y = null, float $w = 0, float $h = 30, float $barWidth = 0.4, bool $skipZeroWidthBars = true): static
write2DBarcode(string $code, Barcode2DType $type, ?float $x = null, ?float $y = null, float $w = 0, float $h = 0, float $moduleSize = 1.0, string $ecLevel = 'L', ?int $mask = null, ?int $version = null, bool $gs1 = false, bool $dmre = false, bool $rectangular = false): static

シンボロジーとは、データをバーまたはモジュールへ変換する方法を定義するバーコード規格です。BarcodeType は 1D シンボロジー（C128、EAN13、UPCA、I25、CODABAR、ISBN、GS1_128 など）を列挙し、Barcode2DType は 2D シンボロジー（QRCode、DataMatrix、PDF417、HanXin、MicroQR など）を列挙します。

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

<?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 Quick Start');
$doc->addPage();

$doc->write1DBarcode('NEXTPDF-2026', BarcodeType::C128, x: 15, y: 30, w: 80, h: 20);
$doc->write2DBarcode('https://nextpdf.dev', Barcode2DType::QRCode, x: 15, y: 60, w: 40, h: 40);

$doc->save(__DIR__ . '/barcodes.pdf');
echo "Wrote barcodes.pdf\n";

コードサンプル — 本番

以下の完全な例はハーネスで実行可能で、examples/10-barcodes.php を反映しています。この例は、ハーネスが NEXTPDF_COOKBOOK_OUTPUT を通じて提供するパスに PDF を書き込み、手動で実行する場合はローカルファイルにフォールバックします。これにより、再現性ハーネスはこの例を 2 回実行し、構造的な同一性を検証できます。構造は qpdf 正規化済みで、保存ごとの /ID とタイムスタンプのアトムが取り除かれています。

<?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', 'B', 18);
$doc->cell(0, 12, 'Barcode Examples', newLine: true);
$doc->ln(5);

// --- 1D barcodes ---
$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, '1D Barcodes', newLine: true);
$doc->ln(3);

$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, 'EAN-13:', newLine: true);
$doc->write1DBarcode('4006381333931', BarcodeType::EAN13, x: 15, y: null, w: 60, h: 20);
$doc->ln(28);

// --- 2D barcodes ---
$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, '2D Barcodes', newLine: true);
$doc->ln(3);

$doc->setFont('helvetica', '', 10);
$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->ln(48);

$doc->cell(0, 6, 'DataMatrix:', newLine: true);
$doc->write2DBarcode('NextPDF-DM-2026', Barcode2DType::DataMatrix, x: 15, y: null, w: 30, h: 30);

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false ? $out : __DIR__ . '/barcodes.pdf');

echo "Wrote barcodes PDF (Code 128, EAN-13, QR Code, DataMatrix)\n";

期待される出力：

Wrote barcodes PDF (Code 128, EAN-13, QR Code, DataMatrix)

エッジケースと注意点

ペイロードの妥当性はシンボロジーごとに異なります。 EAN13 は 12 桁または 13 桁を想定します。無効なペイロードでは、コンテンツが書き込まれる前に例外がスローされます。UPCA、ISBN、ISSN には、それぞれ独自の桁数およびチェックディジットの規則があります。
x/y は省略可能です。 これらを省略すると、バーコードは現在のカーソル位置に配置されます。予測可能なレイアウトにするには、明示的な座標を渡します。
w = 0 は自動サイズ調整を行います。 幅をゼロにすると、エンコーダーが自然なモジュール幅を選択します。固定のボックスに収めるには、正の幅を渡します。
2D の誤り訂正レベル。 write2DBarcode() のデフォルトは、最も低いレベルである ecLevel: 'L' です。印刷時の損傷に耐える必要がある QR Code では、レベルを上げます（'M'、'Q'、'H'）。レベルが高くなるほど、マトリックスは大きくなります。
GS1 アプリケーション識別子。 FNC1 プレフィックスを持つ GS1 構造化データの場合は、gs1: true を write2DBarcode() に渡すか、BarcodeType::GS1_128 を使用します。
ページは暗黙的に作成されます。 addPage() の前にバーコードメソッドを呼び出すと、NextPDF はまずページを追加します。これは便利ですが、ページのジオメトリが重要な場合は addPage() を明示的に呼び出します。

パフォーマンス

エンコードは 1D では O(ペイロード長)、2D では O(マトリックス面積) であり、いずれもマイクロ秒スケールです。各モジュールは 1 つの re … f パス演算子であるため、密度の高い QR Code はコンテンツストリームに数キロバイトを追加します。ラスタライズの手順がないため、シンボルのサイズに関係なくメモリ使用量は一定に保たれます。このレシピは、1500 ms / 64 MB のバジェットに十分収まります。

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

バーコードは渡したペイロードをそのまま保持するため、消費側ではバーコードの値を他の信頼できない入力と同様に扱ってください。このライブラリは、ペイロードに署名したり、認証したりすることはありません。2D シンボルは暗号化ではありません。スキャナーを持っていれば、誰でも読み取ることができます。

適合性

記述	仕様	箇条
バーコードモジュールは矩形パス構築演算子で描画	ISO 32000-2	§8.5
Code 128 のシンボル文字は、定義された bar/space 要素構造を使用	ISO/IEC 15417	§4.3.1
Data Matrix シンボルはリードソロモン誤り訂正を採用	ISO/IEC 16022	§7.6.1
QR Code データは誤り訂正ブロックに分割	ISO/IEC 18004	§7.5.2

NextPDF は引用されたシンボロジーのエンコードを実装していますが、バーコード規格に対する正式な認証を主張するものではありません。バーコードシンボロジーのコーパスドキュメントは、ライセンス上 Tier C に制限されています。引用は箇条 ID と reference_id のポインターのみであり、規格本文は転載されていません。