Tạo mã vạch 1D và 2D trong PDF

Tổng quan nhanh

Công thức này vẽ trực tiếp mã vạch một chiều (1D) và hai chiều (2D) lên trang Portable Document Format (PDF). Trait HasBarcodes trong Core cung cấp write1DBarcode() và write2DBarcode(). Cả hai phương thức đều vẽ ký hiệu bằng các toán tử đường dẫn PDF gốc trên trang hiện tại, vì vậy kết quả là nội dung vector thuần túy và có tính tất định. Công thức này dựa trên examples/10-barcodes.php.

Cài đặt

composer require nextpdf/core:^3

Bạn không cần thêm extension nào. Các bộ mã hóa mã vạch được viết bằng PHP thuần túy, còn NextPDF vẽ các ký hiệu bằng toán tử hình chữ nhật PDF chuẩn (ISO 32000-2 §8.5).

Tổng quan khái niệm

Mã vạch được vẽ trực tiếp, chứ không được nhúng dưới dạng hình ảnh. Payload là dữ liệu mà bạn mã hóa, chẳng hạn như mã sản phẩm hoặc địa chỉ web.

write1DBarcode() mã hóa payload thành mẫu bar/space cho BarcodeType đã chọn, rồi xuất một chuỗi hình chữ nhật được tô đầy. write2DBarcode() tạo ma trận module cho Barcode2DType đã chọn và xuất một hình chữ nhật được tô đầy cho mỗi module tối. Data Matrix và QR Code dùng phương pháp sửa lỗi Reed-Solomon, nên máy quét có thể khôi phục dữ liệu ngay cả khi một phần ký hiệu bị hỏng.

Mỗi module là một đường dẫn re … f có tính tất định và không dùng nguồn entropy nào, nên bản thân nội dung mã vạch hoàn toàn có thể tái tạo. Hồ sơ khả năng tái tạo là structural vì phần tài liệu bao quanh vẫn chứa các phần tử thay đổi theo từng lần lưu: /ID trong trailer, cùng với các dấu thời gian /CreationDate và /ModDate. Bộ kiểm thử so sánh cấu trúc đã được chuẩn hóa bằng qpdf sau khi loại bỏ các phần tử đó.

Bề mặt API

NextPDF\Core\Concerns\HasBarcodes (được trộn vào 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

Symbology là chuẩn mã vạch quy định cách chuyển dữ liệu thành các vạch hoặc module. BarcodeType liệt kê các symbology 1D (C128, EAN13, UPCA, I25, CODABAR, ISBN, GS1_128, …), còn Barcode2DType liệt kê các symbology 2D (QRCode, DataMatrix, PDF417, HanXin, MicroQR, …).

Ví dụ mã — khởi đầu nhanh

<?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";

Ví dụ mã — Production

Ví dụ đầy đủ dưới đây chạy được trong bộ kiểm thử và phản chiếu examples/10-barcodes.php. Ví dụ ghi PDF vào đường dẫn mà bộ kiểm thử cung cấp qua NEXTPDF_COOKBOOK_OUTPUT, đồng thời dùng tệp cục bộ làm phương án dự phòng khi bạn chạy thủ công. Sau đó, bộ kiểm thử khả năng tái tạo có thể chạy ví dụ này hai lần và xác nhận cấu trúc nhất quán. Cấu trúc được chuẩn hóa bằng qpdf sau khi loại bỏ /ID thay đổi theo từng lần lưu và các phần tử chứa dấu thời gian.

<?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";

Kết quả mong đợi:

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

Trường hợp biên & lưu ý

Tính hợp lệ của payload tùy theo từng symbology. EAN13 cần 12 hoặc 13 chữ số. Payload không hợp lệ sẽ ném ngoại lệ trước khi NextPDF ghi bất kỳ nội dung nào. UPCA, ISBN và ISSN có quy tắc riêng về độ dài và chữ số kiểm tra.
x/y là tùy chọn. Khi bạn không truyền chúng, mã vạch được đặt tại vị trí con trỏ hiện tại. Hãy truyền tọa độ tường minh để có bố cục dễ đoán.
w = 0 tự động chỉnh kích thước. Chiều rộng bằng không cho phép bộ mã hóa tự chọn chiều rộng module tự nhiên. Hãy truyền chiều rộng dương để vừa với một khung cố định.
Mức sửa lỗi 2D. write2DBarcode() mặc định là ecLevel: 'L', mức thấp nhất. Hãy nâng mức này lên ('M', 'Q', 'H') cho các QR Code cần chịu được hư hỏng khi in. Các mức cao hơn sẽ làm ma trận lớn hơn.
Mã định danh ứng dụng GS1. Hãy truyền gs1: true cho write2DBarcode(), hoặc dùng BarcodeType::GS1_128, đối với dữ liệu có cấu trúc GS1 với tiền tố FNC1.
Một trang được tạo ngầm định. Khi bạn gọi một phương thức mã vạch trước addPage(), NextPDF sẽ thêm một trang trước. Điều này tiện lợi, nhưng hãy gọi addPage() một cách tường minh khi hình học trang quan trọng.

Hiệu năng

Việc mã hóa là O(độ dài payload) đối với 1D và O(diện tích ma trận) đối với 2D, và cả hai đều chạy ở mức micro giây. Mỗi module là một toán tử đường dẫn re … f, nên một QR Code dày đặc chỉ thêm vài kilobyte vào luồng nội dung. Không có bước raster hóa, nên mức sử dụng bộ nhớ ổn định bất kể kích thước ký hiệu. Công thức này dễ dàng nằm trong ngân sách 1500 ms / 64 MB.

Lưu ý bảo mật

Mã vạch mang theo bất kỳ payload nào bạn truyền vào, nên hãy xử lý giá trị mã vạch như mọi đầu vào không đáng tin cậy khác ở phía tiêu thụ. Thư viện không ký hay xác thực payload. Ký hiệu 2D không phải là cơ chế mã hóa: bất kỳ ai có máy quét đều đọc được nó.

Sự tuân thủ

Tuyên bố	Đặc tả	Điều khoản
Các module mã vạch được vẽ bằng toán tử dựng đường dẫn hình chữ nhật.	ISO 32000-2	§8.5
Các ký tự ký hiệu Code 128 dùng cấu trúc phần tử bar/space đã được định nghĩa.	ISO/IEC 15417	§4.3.1
Các ký hiệu Data Matrix dùng phương pháp sửa lỗi Reed-Solomon.	ISO/IEC 16022	§7.6.1
Dữ liệu QR Code được chia thành các khối sửa lỗi.	ISO/IEC 18004	§7.5.2

NextPDF triển khai các kiểu mã hóa symbology được trích dẫn, nhưng không tuyên bố có chứng nhận chính thức theo các chuẩn mã vạch. Các tài liệu trong corpus về symbology mã vạch bị giới hạn giấy phép ở Tier C. Các trích dẫn chỉ dùng con trỏ clause-id và reference_id, và không tái tạo văn bản của chuẩn.