跳转到内容
NextPDF

条码：一维和二维符号编码器

概览

标题为“概览”的章节

条码模块是符号的实现层。它编码线性符号（Code 128、EAN、UPC、Interleaved 2 of 5、Codabar、邮政码）与矩阵符号（QR Code、Data Matrix、PDF417），并计算这些符号的纠错。它将每个编码器注册于条码合约之后，让文档写入器能够绘制结果。合约定义位于另一个页面；请参阅下方说明。

每个关注点都有一个规范页面。 编码器所遵循的接口 （Barcode1DEncoderInterface、Barcode2DEncoderInterface、 BarcodeEncoderInterface、Gs1DataParserInterface）记录在 Contracts / Barcode。本页记录实现这些合约的具体编码器。两者互为补充， 并非重复。若要了解 SPI，请阅读合约页面；若要了解符号，请阅读本页面。

安装

标题为“安装”的章节
Terminal window
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 接口

标题为“API 接口”的章节
类别主要成员角色
Barcode1Dgenerate(string $code, BarcodeType $type): BarcodeData线性符号编码器（@since 1.0.0）
QrEncoderencode(string $data, array $options = []): Barcode2DDataQR Code 编码器（@since 1.3.0）
DataMatrixEncoderencode(string $data, array $options = []): Barcode2DDataData Matrix 编码器（@since 1.3.0）
Pdf417Encoderencode(string $data, array $options = []): Barcode2DDataPDF417 编码器（@since 1.3.0）
BarcodeEncoderRegistrycreateDefault()、register()、resolve()、has()、get()、registered()PSR-11 编码器注册表（@since 3.0.0）
BarcodeType / Barcode2DTypeenum 案例支持的符号枚举
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 18004QR Code 符号
Data Matrix 符号遵循 Data Matrix 符号规范。ISO/IEC 16022Data Matrix 符号
PDF417 符号遵循 PDF417 符号规范。ISO/IEC 15438PDF417 符号
Code 128 符号遵循 Code 128 线性符号规范。ISO/IEC 15417Code 128 符号
EAN/UPC 符号遵循 EAN/UPC 符号规范。ISO/IEC 15420EAN/UPC 符号

这些符号标准并未收录在可验证的引用语料库中，因此未记录任何 reference_id。引擎会改述需求，并以编号与条款引用来源。若需权威性的编码规则，请查阅已发布的标准。这些编码器由 tests/Unit/Barcode/ 进行测试。测试套件负责对照符号规范验证正确性；这不是端到端 PDF 符合性声明。

另请参阅

标题为“另请参阅”的章节