條碼：一維與二維符號編碼器

概覽

條碼模組是符號的實作層。它會編碼線性符號（Code 128、EAN、UPC、Interleaved 2 of 5、Codabar、郵政碼）與矩陣符號（QR Code、Data Matrix、PDF417），並為這些符號計算錯誤更正。它將每個編碼器註冊在條碼合約背後，讓文件寫入器能繪製結果。合約的定義位於另一個頁面。請參閱下方備註。

每個關注點都有各自的正規頁面。 編碼器所滿足的介面（Barcode1DEncoderInterface、Barcode2DEncoderInterface、 BarcodeEncoderInterface、Gs1DataParserInterface）記載於 Contracts / Barcode。本頁記載實作這些合約的具體編碼器。兩者是互補的，並非重複。若要了解 SPI，請閱讀合約頁面。若要了解符號，請閱讀本頁面。

安裝

composer require nextpdf/core:^3

概念總覽

條碼編碼器會將酬載字串轉換為模組矩陣（二維）或條紋序列（一維），供寫入器繪製成 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 值物件。

二維編碼器（QrEncoder、DataMatrixEncoder、Pdf417Encoder）實作 BarcodeEncoderInterface，並回傳 Barcode2DData 矩陣。Barcode2DType 列舉引擎可辨識的矩陣符號，包括 QR Code、Data Matrix 與 PDF417。其他符號（例如 Micro QR、rMQR、GS1 DataBar 與 Han Xin）也納入列舉，以供登錄路由使用。支援各符號的編碼器集合視版本而定。矩陣錯誤更正是在伽羅瓦體上計算的。GaloisField 與 GaloisFieldPrime 提供 QR、Data Matrix 與 PDF417 編碼器共用的 Reed-Solomon 算術。

BarcodeEncoderRegistry 是查找機制。它實作 PSR-11 ContainerInterface，透過 createDefault() 隨附預設註冊，並以 resolve() 將符號解析為對應的編碼器。應用程式碼很少直接存取編碼器。高階的 Document::write1DBarcode() / write2DBarcode() 表面層會指定符號，再由登錄提供對應的編碼器。一維引擎自 @since 1.0.0 起提供。二維編碼器自 @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 錯誤更正

執行 composer docs:generate-api-php -- --module=Barcode 即可取得完整 PHPDoc 表格。

程式碼範例 — 快速開始

來源：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');

程式碼範例 — 生產環境

直接透過登錄解析二維編碼器，並在編碼前界定酬載上限。

<?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 會計算並附加檢查碼，請勿預先附加。
二維 $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 符合性聲明。

另請參閱

Contracts / Barcode — 這些類別所實作的編碼器介面（SPI）。
Graphics 模組 — 繪製編碼後矩陣的繪圖層。
Document 模組 — 高階 write1DBarcode() / write2DBarcode() 表面層。
符合性總覽
引擎安全模型