Barcode: encoder simbologi 1D dan 2D

Sekilas pandang

Modul Barcode menyediakan lapisan implementasi untuk simbologi. Modul ini mengodekan simbologi linear (Code 128, EAN, UPC, Interleaved 2 of 5, Codabar, kode pos) dan simbologi matriks (QR Code, Data Matrix, PDF417). Modul ini menghitung koreksi galat dan mendaftarkan setiap encoder di balik kontrak barcode, sehingga penulis dokumen dapat menggambar hasilnya. Definisi kontraknya berada di halaman terpisah. Lihat catatan di bawah.

Satu halaman kanonis per topik. Antarmuka yang dipenuhi oleh sebuah encoder (Barcode1DEncoderInterface, Barcode2DEncoderInterface, BarcodeEncoderInterface, Gs1DataParserInterface) didokumentasikan di Contracts / Barcode. Halaman ini mendokumentasikan encoder konkret yang mengimplementasikan kontrak-kontrak tersebut. Kedua halaman ini saling melengkapi, bukan duplikat. Baca halaman kontrak untuk service provider interface (SPI). Baca halaman ini untuk rincian simbologinya.

Instalasi

composer require nextpdf/core:^3

Gambaran konseptual

Sebuah encoder barcode mengubah string payload menjadi matriks modul dua dimensi (2D) atau urutan batang satu dimensi (1D), yang kemudian digambar oleh penulis sebagai grafik Portable Document Format (PDF). Modul ini menyediakan encoder konkretnya.

Barcode1D adalah mesin linearnya. BarcodeType mencantumkan simbologi linear yang didukung: Code 39 (dengan dan tanpa checksum), Code 93, keluarga Code 128, EAN-8/EAN-13, UPC-A/UPC-E, Interleaved dan Standard 2 of 5, Codabar, Code 11, POSTNET, PLANET, Intelligent Mail (IMB), dan MSI. generate() mengembalikan objek nilai BarcodeData yang menjelaskan pola batang.

Encoder 2D, QrEncoder, DataMatrixEncoder, dan Pdf417Encoder, mengimplementasikan BarcodeEncoderInterface dan mengembalikan matriks Barcode2DData. Barcode2DType mencantumkan simbologi matriks yang dikenali mesin, termasuk QR Code, Data Matrix, dan PDF417. Simbologi tambahan seperti Micro QR, rMQR, GS1 DataBar, dan Han Xin disebutkan untuk perutean registry. Kumpulan encoder yang mendukung setiap simbologi bergantung pada edisi. Koreksi galat matriks dihitung pada sebuah Galois field. GaloisField dan GaloisFieldPrime menyediakan aritmetika Reed-Solomon yang dipakai bersama oleh encoder QR, Data Matrix, dan PDF417.

BarcodeEncoderRegistry adalah titik pencarian encoder. Registry ini mengimplementasikan PHP Standards Recommendation 11 (PSR-11) ContainerInterface, menyediakan registrasi standar melalui createDefault(), dan menyelesaikan simbologi ke encoder-nya dengan resolve(). Kode aplikasi jarang perlu mengakses sebuah encoder secara langsung. Fasad tingkat tinggi Document::write1DBarcode() / write2DBarcode() menyebutkan sebuah simbologi dan registry menyediakan encoder-nya. Mesin 1D diberi penanda @since 1.0.0. Encoder 2D diberi penanda @since 1.3.0. Registry diberi penanda @since 3.0.0.

Permukaan API

Kelas	Anggota utama	Peran
`Barcode1D`	`generate(string $code, BarcodeType $type): BarcodeData`	Encoder simbologi linear (`@since 1.0.0`)
`QrEncoder`	`encode(string $data, array $options = []): Barcode2DData`	Encoder QR Code (`@since 1.3.0`)
`DataMatrixEncoder`	`encode(string $data, array $options = []): Barcode2DData`	Encoder Data Matrix (`@since 1.3.0`)
`Pdf417Encoder`	`encode(string $data, array $options = []): Barcode2DData`	Encoder PDF417 (`@since 1.3.0`)
`BarcodeEncoderRegistry`	`createDefault()`, `register()`, `resolve()`, `has()`, `get()`, `registered()`	Registry encoder PSR-11 (`@since 3.0.0`)
`BarcodeType` / `Barcode2DType`	case enum	Enumerasi simbologi yang didukung
`GaloisField` / `GaloisFieldPrime`	aritmetika finite-field	Koreksi galat Reed-Solomon

Jalankan composer docs:generate-api-php -- --module=Barcode untuk menghasilkan tabel PHPDoc lengkap.

Contoh kode — Mulai cepat

Sumber: examples/10-barcodes.php. Fasad menggunakan registry untuk menyelesaikan encoder bagi simbologi yang diminta.

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

Contoh kode — Produksi

Selesaikan sebuah encoder 2D langsung melalui registry dan batasi payload sebelum pengodean.

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

Kasus tepi & jebakan

Payload linear yang melanggar set karakter atau aturan check-digit pada sebuah simbologi memunculkan BarcodeException. EAN/UPC menghitung dan menambahkan check digit. Jangan menambahkannya terlebih dahulu.
Array $options 2D bersifat khusus untuk tiap simbologi, seperti tingkat koreksi galat untuk QR. Sebagian besar encoder mengabaikan kunci yang tidak dikenal. Verifikasi setiap kunci terhadap dokumentasi encoder terkait.
Barcode2DType menyebutkan lebih banyak simbologi daripada encoder yang disertakan oleh edisi core. BarcodeEncoderRegistry::resolve() memunculkan kesalahan untuk simbologi yang tidak terdaftar, bukan mengembalikan sebuah placeholder.
Encoder yang terdaftar adalah instance bersama. Pastikan encoder tetap stateless di luar konfigurasi konstruktor. State per panggilan merusak proses render yang berjalan bersamaan.
Payload yang terlalu panjang menghasilkan matriks yang lebih rapat dan lebih besar. Batasi panjang payload sebelum pengodean untuk menghindari denial of service melalui ukuran simbol.

Performa

Biaya pengodean berskala dengan panjang payload dan ukuran matriks, bukan dengan pencarian registry yang bersifat O(1). Payload Code 128 yang pendek dikodekan dalam hitungan mikrodetik. QR Code yang rapat dengan koreksi galat tinggi adalah kasus terberat. Halaman contoh multi-simbol tetap berada dalam anggaran wall 1500 ms / puncak 64 MB. Profil reproduktibilitasnya adalah bitwise. Payload dan opsi yang sama selalu menghasilkan matriks modul yang sama serta byte hasil penggambaran yang sama.

Catatan keamanan

Payload barcode sering berasal dari sumber yang tidak tepercaya: uniform resource locator (URL) hasil pemindaian, nomor seri, atau kode pelacakan. Encoder mengodekan byte. Encoder tidak menafsirkannya. QR Code yang mengodekan URL berbahaya tetaplah QR Code yang valid, sehingga konsumen bertanggung jawab untuk menilai kepercayaan payload. Batasi panjang payload sebelum pengodean untuk menjaga ukuran matriks, beban kerja, dan ukuran keluaran tetap dalam anggaran. Perlakukan setiap data yang didekode dari sebuah barcode di tempat lain sebagai input tidak tepercaya ketika data tersebut kembali masuk ke aplikasi. Lihat model ancaman mesin di /modules/core/security/.

Kesesuaian

Klaim	Standar	Referensi
Simbol QR Code mengikuti spesifikasi simbologi matriks QR Code.	ISO/IEC 18004	Simbologi QR Code
Simbol Data Matrix mengikuti spesifikasi simbologi Data Matrix.	ISO/IEC 16022	Simbologi Data Matrix
Simbol PDF417 mengikuti spesifikasi simbologi PDF417.	ISO/IEC 15438	Simbologi PDF417
Simbol Code 128 mengikuti spesifikasi simbologi linear Code 128.	ISO/IEC 15417	Simbologi Code 128
Simbol EAN/UPC mengikuti spesifikasi simbologi EAN/UPC.	ISO/IEC 15420	Simbologi EAN/UPC

Standar simbologi ini tidak terdapat dalam korpus sitasi yang dapat diverifikasi, sehingga tidak ada reference_id yang dicatat. Halaman ini memparafrasakan persyaratannya dan mengutip sumbernya berdasarkan nomor dan klausa. Rujuk standar yang dipublikasikan untuk aturan pengodean yang otoritatif. Encoder diuji oleh tests/Unit/Barcode/. Kebenaran terhadap spesifikasi simbologi menjadi tanggung jawab rangkaian uji, bukan pernyataan kesesuaian PDF ujung ke ujung.

Lihat juga

Contracts / Barcode — interface encoder yang diimplementasikan oleh kelas-kelas ini (SPI).
Modul Graphics — lapisan penggambaran untuk menggambar matriks terkode.
Modul Document — fasad tingkat tinggi write1DBarcode() / write2DBarcode().
Ikhtisar kesesuaian
Model keamanan mesin