Barcode: Bộ mã hóa ký hiệu 1D và 2D

Tổng quan nhanh

Module Barcode cung cấp lớp triển khai cho các ký hiệu. Module này mã hóa các ký hiệu tuyến tính (Code 128, EAN, UPC, Interleaved 2 of 5, Codabar, mã bưu chính) và các ký hiệu ma trận (QR Code, Data Matrix, PDF417). Module tính toán sửa lỗi và đăng ký từng bộ mã hóa dưới các contract barcode, để bộ ghi tài liệu có thể vẽ kết quả. Các định nghĩa contract nằm ở một trang riêng. Xem ghi chú bên dưới.

Mỗi mối quan tâm có một trang chuẩn duy nhất. Các interface mà một bộ mã hóa đáp ứng (Barcode1DEncoderInterface, Barcode2DEncoderInterface, BarcodeEncoderInterface, Gs1DataParserInterface) được ghi tài liệu tại Contracts / Barcode. Trang này ghi tài liệu các bộ mã hóa cụ thể triển khai những contract đó. Hai trang này bổ sung cho nhau, không trùng lặp. Đọc trang contract để biết về interface nhà cung cấp dịch vụ (SPI). Đọc trang này để tìm hiểu các ký hiệu.

Cài đặt

composer require nextpdf/core:^3

Tổng quan khái niệm

Một bộ mã hóa barcode chuyển chuỗi payload thành ma trận module hai chiều (2D) hoặc chuỗi vạch một chiều (1D) để bộ ghi vẽ thành đồ họa Portable Document Format (PDF). Module này cung cấp các bộ mã hóa cụ thể.

Barcode1D là engine tuyến tính. BarcodeType liệt kê các ký hiệu tuyến tính được hỗ trợ: Code 39 (có và không có checksum), Code 93, họ Code 128, EAN-8/EAN-13, UPC-A/UPC-E, Interleaved và Standard 2 of 5, Codabar, Code 11, POSTNET, PLANET, Intelligent Mail (IMB) và MSI. generate() trả về value object BarcodeData mô tả mẫu vạch.

Các bộ mã hóa 2D, QrEncoder, DataMatrixEncoder và Pdf417Encoder, triển khai BarcodeEncoderInterface và trả về ma trận Barcode2DData. Barcode2DType liệt kê các ký hiệu ma trận mà engine nhận diện, bao gồm QR Code, Data Matrix và PDF417. Các ký hiệu bổ sung như Micro QR, rMQR, GS1 DataBar và Han Xin được liệt kê để định tuyến trong registry. Tập hợp bộ mã hóa đằng sau mỗi ký hiệu phụ thuộc vào phiên bản. Sửa lỗi ma trận được tính toán trên trường Galois. GaloisField và GaloisFieldPrime cung cấp phép toán Reed-Solomon dùng chung cho các bộ mã hóa QR, Data Matrix và PDF417.

BarcodeEncoderRegistry là bộ tra cứu. Nó triển khai PHP Standards Recommendation 11 (PSR-11) ContainerInterface, cung cấp đăng ký mặc định thông qua createDefault(), và phân giải một ký hiệu thành bộ mã hóa tương ứng bằng resolve(). Mã ứng dụng hiếm khi truy cập trực tiếp vào một bộ mã hóa. Facade cấp cao Document::write1DBarcode() / write2DBarcode() chỉ định ký hiệu, còn registry cung cấp bộ mã hóa. Engine 1D là @since 1.0.0. Các bộ mã hóa 2D là @since 1.3.0. Registry là @since 3.0.0.

Bề mặt API

Class	Thành viên chính	Vai trò
Barcode1D	generate(string $code, BarcodeType $type): BarcodeData	Bộ mã hóa ký hiệu tuyến tính (@since 1.0.0)
QrEncoder	encode(string $data, array $options = []): Barcode2DData	Bộ mã hóa QR Code (@since 1.3.0)
DataMatrixEncoder	encode(string $data, array $options = []): Barcode2DData	Bộ mã hóa Data Matrix (@since 1.3.0)
Pdf417Encoder	encode(string $data, array $options = []): Barcode2DData	Bộ mã hóa PDF417 (@since 1.3.0)
BarcodeEncoderRegistry	createDefault(), register(), resolve(), has(), get(), registered()	Registry bộ mã hóa PSR-11 (@since 3.0.0)
BarcodeType / Barcode2DType	các case của enum	Các enum ký hiệu được hỗ trợ
GaloisField / GaloisFieldPrime	phép toán trường hữu hạn	Sửa lỗi Reed-Solomon

Chạy composer docs:generate-api-php -- --module=Barcode để tạo bảng PHPDoc đầy đủ.

Mã mẫu — bắt đầu nhanh

Nguồn: examples/10-barcodes.php. Facade phân giải bộ mã hóa cho ký hiệu được yêu cầu qua registry.

<?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');

Mã mẫu — production

Phân giải trực tiếp bộ mã hóa 2D qua registry, đồng thời giới hạn payload trước khi mã hóa.

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

Trường hợp đặc biệt và lưu ý

• Payload tuyến tính vi phạm tập ký tự hoặc quy tắc chữ số kiểm tra của một ký hiệu sẽ ném ra BarcodeException. EAN/UPC tự tính toán và thêm chữ số kiểm tra. Đừng thêm sẵn chữ số đó từ trước.
• Mảng $options 2D phụ thuộc vào từng ký hiệu, chẳng hạn như mức sửa lỗi cho QR. Hầu hết các bộ mã hóa bỏ qua các khóa không xác định. Hãy kiểm tra từng khóa theo tài liệu của chính bộ mã hóa.
• Barcode2DType liệt kê nhiều ký hiệu hơn số bộ mã hóa đi kèm trong phiên bản core. BarcodeEncoderRegistry::resolve() ném lỗi đối với ký hiệu chưa được đăng ký, thay vì trả về một placeholder.
• Các bộ mã hóa đã đăng ký là những instance dùng chung. Hãy giữ chúng không lưu trạng thái ngoài cấu hình trong constructor. Trạng thái theo từng lần gọi sẽ làm hỏng các lần kết xuất đồng thời.
• Payload quá dài tạo ra ma trận dày đặc hơn và lớn hơn. Hãy giới hạn độ dài payload trước khi mã hóa để tránh tấn công từ chối dịch vụ thông qua kích thước ký hiệu.

Hiệu năng

Chi phí mã hóa tỉ lệ theo độ dài payload và kích thước ma trận, không phụ thuộc vào việc tra cứu registry, vốn là O(1). Payload Code 128 ngắn được mã hóa trong vài micro giây. QR Code dày đặc với mức sửa lỗi cao là trường hợp nặng nhất. Trang ví dụ nhiều ký hiệu nằm trong giới hạn ngân sách 1500 ms wall / 64 MB peak. Hồ sơ khả năng tái lập là bitwise. Cùng một payload và options luôn tạo ra cùng một ma trận module và cùng các byte được vẽ.

Ghi chú bảo mật

Payload của barcode thường đến từ các nguồn không đáng tin cậy: một uniform resource locator (URL) đã quét, một số sê-ri, hoặc một mã theo dõi. Các bộ mã hóa chỉ mã hóa byte. Chúng không diễn giải các byte đó. QR Code mã hóa một URL độc hại vẫn là QR Code hợp lệ, nên bên tiêu thụ chịu trách nhiệm về độ tin cậy của payload. Hãy giới hạn độ dài payload trước khi mã hóa để giữ kích thước ma trận, khối lượng tính toán và kích thước đầu ra trong giới hạn ngân sách. Hãy xem mọi dữ liệu được giải mã từ một barcode ở nơi khác là đầu vào không đáng tin cậy khi dữ liệu đó quay lại ứng dụng. Xem mô hình mối đe dọa của engine tại /modules/core/security/.

Tuân thủ

Tuyên bố	Tiêu chuẩn	Tham chiếu
Các ký hiệu QR Code tuân theo đặc tả ký hiệu ma trận QR Code.	ISO/IEC 18004	Ký hiệu QR Code
Các ký hiệu Data Matrix tuân theo đặc tả ký hiệu Data Matrix.	ISO/IEC 16022	Ký hiệu Data Matrix
Các ký hiệu PDF417 tuân theo đặc tả ký hiệu PDF417.	ISO/IEC 15438	Ký hiệu PDF417
Các ký hiệu Code 128 tuân theo đặc tả ký hiệu tuyến tính Code 128.	ISO/IEC 15417	Ký hiệu Code 128
Các ký hiệu EAN/UPC tuân theo đặc tả ký hiệu EAN/UPC.	ISO/IEC 15420	Ký hiệu EAN/UPC

Các tiêu chuẩn ký hiệu này không có trong kho trích dẫn có thể kiểm chứng, nên không có reference_id nào được ghi lại. Trang này diễn giải lại yêu cầu và trích dẫn nguồn theo số hiệu và điều khoản. Hãy tham khảo các tiêu chuẩn đã công bố để biết các quy tắc mã hóa chính thức. Các bộ mã hóa được kiểm thử bằng tests/Unit/Barcode/. Tính đúng đắn so với các đặc tả ký hiệu là trách nhiệm của bộ kiểm thử, không phải tuyên bố về sự tuân thủ PDF đầu cuối.

Xem thêm

• Contracts / Barcode — các interface bộ mã hóa mà những class này triển khai (SPI).
• Module Graphics — lớp vẽ dùng để vẽ ma trận đã mã hóa.
• Module Document — facade cấp cao write1DBarcode() / write2DBarcode().
• Tổng quan tuân thủ
• Mô hình bảo mật của engine