Contracts / Barcode

Tổng quan nhanh

Miền barcode định nghĩa bốn contract: bộ mã hóa một chiều (1D), bộ mã hóa hai chiều (2D), bộ mã hóa chung có thể khám phá qua registry và parser dữ liệu GS1. Kết hợp lại, chúng định nghĩa hình dạng mà các dịch vụ barcode phải đáp ứng. Các triển khai symbology đăng ký theo các contract này.

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 để bộ ghi Portable Document Format (PDF) vẽ ra. NextPDF tách các contract bộ mã hóa theo số chiều. Barcode1DEncoderInterface xử lý các symbology tuyến tính, bao gồm Code 128 và EAN-13, rồi trả về value object BarcodeData. Barcode2DEncoderInterface xử lý các symbology ma trận, bao gồm Quick Response (QR) Code và Data Matrix. Nó trả về value object Barcode2DData với bản đồ tùy chọn dành cho các thiết lập riêng theo symbology, chẳng hạn như mức sửa lỗi.

BarcodeEncoderInterface là contract service-provider chung. Bất kỳ bộ mã hóa 2D nào có thể khám phá qua BarcodeEncoderRegistry đều triển khai nó. Contract trả về hoặc ma trận Barcode2DData đơn sắc hoặc ma trận BarcodeColorData màu, nhờ vậy bộ mã hóa đã đăng ký có thể tạo symbol màu mà không cần interface riêng. Các bộ mã hóa được kỳ vọng là stateless ngoài cấu hình tại thời điểm khởi tạo. Registry trả về một thực thể dùng chung cho mỗi kiểu đã đăng ký, vì vậy bất kỳ trạng thái theo từng lần gọi nào cũng là lỗi.

Gs1DataParserInterface là contract dữ liệu có cấu trúc. Nó phân tích chuỗi phần tử GS1 thành đối tượng có kiểu, rồi mã hóa lại đối tượng đó cho carrier QR Code, Data Matrix hoặc Code 128. Điều này giữ cho ngữ pháp GS1 tách khỏi symbology. Parser xác thực các Application Identifier một lần. Các phương thức riêng theo carrier định dạng cùng cấu trúc đã phân tích cho từng đích. Bốn contract này là stable. BarcodeEncoderInterface ổn định kể từ 3.0.0; các contract còn lại kể từ 1.0.0. Các phương thức mới chỉ xuất hiện cùng với các triển khai mặc định.

Bề mặt API

Kiểu	Loại	Thành viên chính	Độ ổn định	Kể từ
Barcode1DEncoderInterface	interface	encode(string): BarcodeData	stable	1.0.0
Barcode2DEncoderInterface	interface	encode(string, array): Barcode2DData	stable	1.0.0
BarcodeEncoderInterface	interface	encode(string, array): Barcode2DData|BarcodeColorData	stable	3.0.0
Gs1DataParserInterface	interface	parse(), encodeForQrCode(), encodeForDataMatrix(), encodeForCode128()	stable	1.0.0

Trên các contract 2D, mảng $options là riêng theo symbology, chẳng hạn như mức sửa lỗi cho QR Code. Contract không ràng buộc các khóa trong mảng này. Mỗi bộ mã hóa đã đăng ký tự ghi lại bộ tùy chọn riêng của mình.

Mẫu mã — khởi đầu nhanh

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->setTitle('Barcode Examples');
$doc->addPage();

$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, 'QR Code (URL):', newLine: true);
$doc->write2DBarcode('https://nextpdf.dev', Barcode2DType::QRCode, x: 15, y: null, w: 40, h: 40);

$doc->save(__DIR__ . '/output/10-barcodes.pdf');

write1DBarcode() và write2DBarcode() phân giải bộ mã hóa thông qua registry. Mã ứng dụng của bạn hiếm khi chạm trực tiếp vào các contract. Bạn nêu tên symbology, rồi registry cung cấp bộ mã hóa.

Mẫu mã — sản xuất

examples/contracts/barcode-production.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Contracts\Barcode2DEncoderInterface;
use NextPDF\Contracts\Gs1DataParserInterface;
use NextPDF\Exception\BarcodeException;
use Psr\Log\LoggerInterface;

final readonly class Gs1LabelService
{
    public function __construct(
        private Gs1DataParserInterface $parser,
        private Barcode2DEncoderInterface $dataMatrix,
        private LoggerInterface $logger,
    ) {}

    /**
     * Parse a GS1 element string and encode it as a Data Matrix.
     *
     * @param string $elementString A GS1 element string with Application Identifiers.
     */
    public function encodeLabel(string $elementString): \NextPDF\Barcode\Barcode2DData
    {
        try {
            $parsed = $this->parser->parse($elementString);
            $payload = $this->parser->encodeForDataMatrix($parsed);

            return $this->dataMatrix->encode($payload, ['errorCorrection' => 'high']);
        } catch (BarcodeException $e) {
            $this->logger->error('GS1 label encoding failed', [
                'error' => $e->getMessage(),
            ]);

            throw $e;
        }
    }
}

Dịch vụ phụ thuộc vào các contract parser và bộ mã hóa. Khối catch ghi log và ném lại BarcodeException cụ thể; nó không bao giờ bắt \Exception trần.

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

• Bộ mã hóa đã đăng ký được dùng chung. Trạng thái theo từng lần gọi trên một bộ mã hóa sẽ làm hỏng các lần kết xuất đồng thời. Hãy giữ cho các bộ mã hóa ở trạng thái stateless ngoài cấu hình constructor.
• BarcodeEncoderInterface::encode() có thể trả về dữ liệu màu hoặc đơn sắc. Mã sử dụng nó phải xử lý cả Barcode2DData lẫn BarcodeColorData, chứ không được giả định là đơn sắc.
• Mảng $options 2D không được contract xác thực. Hầu hết các bộ mã hóa âm thầm bỏ qua khóa không xác định. Hãy kiểm tra tên khóa với tài liệu của chính bộ mã hóa.
• Việc phân tích GS1 tuân thủ ngữ pháp nghiêm ngặt. Chuỗi phần tử có Application Identifier không xác định sẽ làm phát sinh BarcodeException thay vì tạo ra kết quả phân tích từng phần. Hãy xác thực đầu vào ở thượng nguồn.
• 1D và 2D contract không thể thay thế cho nhau. Truyền payload QR cho bộ mã hóa 1D sẽ tạo ra symbol không hợp lệ. Registry định tuyến theo kiểu symbology, vì vậy hãy ưu tiên registry hơn lời gọi contract trực tiếp.

Hiệu năng

Chi phí mã hóa tỉ lệ với độ dài payload và kích thước ma trận đích, chứ không phụ thuộc vào contract mà bạn gọi. 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 2D nặng nhất. Nó vẫn nằm thoải mái trong performance_budget là 1.500 ms thời gian thực và 64 MB đỉnh cho trang ví dụ có nhiều symbol. Ma trận được tính toán một lần và được vẽ dưới dạng các toán tử PDF. Khả năng tái lập là bitwise vì cùng payload và tùy chọn luôn tạo ra cùng ma trận module. Tra cứu registry là O(1). Thuật toán symbology đảm nhận phần việc còn lại.

Lưu ý bảo mật

Các payload barcode thường chịu ảnh hưởng của kẻ tấn công, chẳng hạn như Uniform Resource Locator (URL) được quét, số sê-ri hoặc mã theo dõi. Các contract mã hóa byte. Chúng không diễn giải byte. QR Code mã hóa URL độc hại vẫn là QR Code hợp lệ, vì vậy việc tin cậy payload là trách nhiệm của bên sử dụng, chứ không phải của bộ mã hóa. Hãy ràng buộc độ dài payload trước khi mã hóa để giới hạn kích thước ma trận và tránh tấn công từ chối dịch vụ thông qua symbol quá lớn. Parser GS1 từ chối các Application Identifier không đúng định dạng, nhờ đó loại bỏ một bề mặt tiêm. Nó không xác thực nội dung ngữ nghĩa của các trường hợp lệ. Hãy xem dữ liệu barcode đã giải mã là đầu vào không đáng tin cậy ở bất cứ nơi nào nó quay lại ứng dụng.

Tính tuân thủ

Tuyên bố	Tiêu chuẩn	Tham chiếu
Các symbol QR Code tuân theo đặc tả symbology ma trận QR Code.	ISO/IEC 18004	Symbology QR Code
Các symbol Data Matrix tuân theo đặc tả symbology Data Matrix.	ISO/IEC 16022	Symbology Data Matrix
Các symbol Code 128 tuân theo đặc tả symbology tuyến tính Code 128.	ISO/IEC 15417	Symbology Code 128
Các chuỗi phần tử GS1 được phân tích theo ngữ pháp Application Identifier của GS1.	GS1 General Specifications	Application Identifier

Các tiêu chuẩn này được tham chiếu theo số và điều khoản. Chúng không có trong kho trích dẫn có thể kiểm chứng, vì vậy không có reference_id nào được ghi lại. Engine diễn giải lại yêu cầu và trích dẫn nguồn. Hãy tham khảo các tiêu chuẩn đã công bố để biết quy tắc mã hóa có thẩm quyền.

Bối cảnh thương mại

Core định nghĩa và đóng băng các contract bộ mã hóa, đồng thời cung cấp các symbology phổ biến. Các phiên bản Pro và Enterprise đăng ký bộ mã hóa mở rộng cho các symbology barcode bổ sung dựa trên cùng BarcodeEncoderInterface, nhờ vậy triển khai thương mại có thêm phạm vi mà không cần thay đổi application programming interface (API). Core phân giải các bộ mã hóa đã đăng ký thông qua BarcodeEncoderRegistry. Bề mặt contract giống nhau trên mọi phiên bản.

Xem thêm

• Contracts: 41 interface công khai (SPI) — tổng quan service provider interface (SPI) và các bậc độ ổn định.
• Barcode — các triển khai symbology được đăng ký theo những contract này.
• Contracts / Document — PdfDocumentInterface vẽ ma trận đã mã hóa.
• Graphics — lớp vẽ kết xuất các module barcode.
• Exception — BarcodeException được ném ra khi đầu vào GS1 không đúng định dạng.