Kontrak / Barcode

Sekilas

Domain barcode mendefinisikan empat kontrak: encoder satu dimensi (1D), encoder dua dimensi (2D), encoder generik yang dapat ditemukan melalui registry, dan parser data GS1. Secara bersama-sama, kontrak-kontrak ini menetapkan bentuk yang harus dipenuhi layanan barcode. Implementasi symbology mendaftarkan dirinya pada kontrak-kontrak ini.

Pemasangan

composer require nextpdf/core:^3

Gambaran konseptual

Encoder barcode mengubah string payload menjadi matriks modul yang kemudian digambar oleh writer Portable Document Format (PDF). NextPDF memisahkan kontrak encoder berdasarkan dimensi. Barcode1DEncoderInterface menangani symbology linear, termasuk Code 128 dan EAN-13, dan mengembalikan objek nilai BarcodeData. Barcode2DEncoderInterface menangani symbology matriks, termasuk Quick Response (QR) Code dan Data Matrix. Kontrak ini mengembalikan objek nilai Barcode2DData dengan peta opsi untuk pengaturan khusus symbology, seperti tingkat koreksi kesalahan.

BarcodeEncoderInterface adalah kontrak penyedia layanan generik. Setiap encoder 2D yang dapat ditemukan melalui BarcodeEncoderRegistry mengimplementasikan kontrak ini. Kontrak ini mengembalikan matriks monokrom Barcode2DData atau matriks berwarna BarcodeColorData, sehingga encoder terdaftar dapat menghasilkan simbol berwarna tanpa antarmuka terpisah. Encoder diharapkan tetap stateless di luar konfigurasi saat konstruksi. Registry mengembalikan satu instans bersama untuk setiap tipe terdaftar, sehingga state per panggilan akan menjadi sumber cacat.

Gs1DataParserInterface adalah kontrak data terstruktur. Kontrak ini mem-parse string elemen GS1 menjadi objek bertipe, lalu meng-encode ulang objek tersebut untuk carrier QR Code, Data Matrix, atau Code 128. Pemisahan ini menjaga tata bahasa GS1 tetap terpisah dari symbology. Parser memvalidasi Application Identifier satu kali. Metode khusus carrier memformat struktur hasil parse yang sama untuk setiap target. Keempat kontrak tersebut stable. BarcodeEncoderInterface stabil sejak 3.0.0; yang lainnya sejak 1.0.0. Metode baru hanya disertakan bersama implementasi standar.

Permukaan API

Tipe	Jenis	Anggota utama	Stabilitas	Sejak
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

Pada kontrak 2D, array $options bersifat khusus untuk symbology, misalnya tingkat koreksi kesalahan untuk QR Code. Kontrak tidak membatasi kuncinya. Setiap encoder terdaftar mendokumentasikan kumpulan opsinya sendiri.

Contoh kode — Mulai cepat

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() dan write2DBarcode() mengambil encoder melalui registry. Kode aplikasi Anda jarang perlu menyentuh kontrak secara langsung. Anda cukup menyebutkan symbology, lalu registry menyediakan encodernya.

Contoh kode — Produksi

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

Layanan ini bergantung pada kontrak parser dan encoder. Blok catch mencatat log lalu melempar ulang BarcodeException yang spesifik; blok ini tidak pernah menangkap \Exception mentah.

Kasus tepi & jebakan

• Encoder terdaftar dipakai bersama. State per panggilan pada encoder merusak proses render yang berjalan bersamaan. Jaga encoder tetap stateless di luar konfigurasi konstruktor.
• BarcodeEncoderInterface::encode() dapat mengembalikan data berwarna atau monokrom. Kode konsumen harus menangani baik Barcode2DData maupun BarcodeColorData, bukan mengasumsikan monokrom.
• Array $options 2D tidak divalidasi oleh kontrak. Sebagian besar encoder mengabaikan kunci yang tidak dikenal tanpa peringatan. Verifikasi nama kunci terhadap dokumentasi encoder itu sendiri.
• Parsing GS1 menerapkan tata bahasa secara ketat. String elemen dengan Application Identifier yang tidak dikenal memicu BarcodeException, bukan menghasilkan parse parsial. Validasi masukan di hulu.
• Kontrak 1D dan 2D tidak dapat dipertukarkan. Meneruskan payload QR ke encoder 1D menghasilkan simbol yang tidak valid. Registry merutekan berdasarkan tipe symbology; karena itu, utamakan registry daripada panggilan kontrak langsung.

Kinerja

Biaya encoding berskala sesuai panjang payload dan ukuran matriks target, bukan kontrak yang Anda panggil. Payload Code 128 yang pendek di-encode dalam hitungan mikrodetik. QR Code yang padat dengan koreksi kesalahan tinggi menjadi kasus 2D paling berat. Kasus ini tetap jauh di dalam performance_budget sebesar 1500 ms wall dan 64 MB puncak untuk halaman contoh multi-simbol. Matriks dihitung satu kali dan digambar sebagai operator PDF. Reproduksibilitas bersifat bitwise karena payload dan opsi yang sama selalu menghasilkan matriks modul yang sama. Pencarian registry bersifat O(1); pekerjaan utama dilakukan oleh algoritme symbology.

Catatan keamanan

Payload barcode sering kali dapat dipengaruhi penyerang, seperti Uniform Resource Locator (URL) yang dipindai, nomor seri, atau kode pelacakan. Kontrak meng-encode byte; kontrak tidak menginterpretasikannya. QR Code yang meng-encode URL berbahaya tetap merupakan QR Code yang valid, sehingga kepercayaan terhadap payload menjadi tanggung jawab konsumen, bukan encoder. Batasi panjang payload sebelum encoding untuk membatasi ukuran matriks dan menghindari denial-of-service melalui simbol yang terlalu besar. Parser GS1 menolak Application Identifier yang cacat, sehingga satu permukaan injeksi dihilangkan. Parser tidak memvalidasi konten semantik dari field yang valid. Perlakukan data barcode yang ter-decode sebagai masukan tidak tepercaya di mana pun data itu masuk kembali ke aplikasi.

Konformitas

Klaim	Standar	Referensi
Simbol QR Code mengikuti spesifikasi symbology matriks QR Code.	ISO/IEC 18004	symbology QR Code
Simbol Data Matrix mengikuti spesifikasi symbology Data Matrix.	ISO/IEC 16022	symbology Data Matrix
Simbol Code 128 mengikuti spesifikasi symbology linear Code 128.	ISO/IEC 15417	symbology Code 128
String elemen GS1 di-parse sesuai dengan tata bahasa Application Identifier GS1.	GS1 General Specifications	Application Identifier

Standar-standar ini dirujuk berdasarkan nomor dan klausa. Standar tersebut tidak tersedia dalam korpus sitasi yang dapat diverifikasi, sehingga tidak ada reference_id yang dicatat. Engine memparafrasakan persyaratan tersebut dan mengutip sumbernya. Rujuk standar yang dipublikasikan untuk aturan encoding yang otoritatif.

Konteks komersial

Core mendefinisikan dan membekukan kontrak encoder, serta menyertakan symbology umum. Edisi Pro dan Enterprise mendaftarkan kumpulan encoder yang diperluas untuk symbology barcode tambahan pada BarcodeEncoderInterface yang sama, sehingga deployment komersial memperoleh cakupan lebih luas tanpa perubahan application programming interface (API). Core mengambil encoder terdaftar melalui BarcodeEncoderRegistry. Permukaan kontrak identik di seluruh edisi.

Lihat juga

• Kontrak: 41 antarmuka publik (SPI) — gambaran umum antarmuka penyedia layanan (SPI) dan tingkat stabilitas.
• Barcode — implementasi symbology yang terdaftar pada kontrak-kontrak ini.
• Kontrak / Document — PdfDocumentInterface yang menggambar matriks ter-encode.
• Graphics — lapisan penggambaran yang merender modul barcode.
• Exception — BarcodeException yang dilempar saat masukan GS1 cacat.