Membuat barcode 1D dan 2D di PDF

Sekilas pandang

Resep ini menunjukkan cara menggambar barcode satu dimensi (1D) dan dua dimensi (2D) langsung di halaman Portable Document Format (PDF). Trait HasBarcodes dari Core menyediakan write1DBarcode() dan write2DBarcode(). Kedua metode menggambar simbol sebagai operator path PDF native pada halaman saat ini, sehingga outputnya berupa konten vektor murni yang deterministik. Resep ini mengacu pada examples/10-barcodes.php.

Pemasangan

composer require nextpdf/core:^3

Anda tidak memerlukan ekstensi tambahan. Encoder barcode ditulis sepenuhnya dalam PHP, dan NextPDF menggambar simbol menggunakan operator rectangle PDF standar (ISO 32000-2 §8.5).

Tinjauan konseptual

Barcode digambar, bukan disematkan sebagai gambar. Payload adalah data yang Anda enkode, seperti nomor produk atau alamat web.

write1DBarcode() mengenkode payload menjadi pola bar/space untuk BarcodeType yang dipilih, lalu menghasilkan rangkaian persegi panjang terisi. write2DBarcode() membangun matriks modul untuk Barcode2DType yang dipilih dan menghasilkan satu persegi panjang terisi untuk setiap modul gelap. Data Matrix dan QR Code menggunakan koreksi galat Reed-Solomon, sehingga pemindai dapat memulihkan data meskipun sebagian simbol rusak.

Setiap modul berupa path re … f yang deterministik tanpa sumber entropi, sehingga konten barcode itu sendiri sepenuhnya dapat direproduksi. Profil reproduksibilitasnya adalah structural karena dokumen pembungkusnya masih membawa atom per-penyimpanan: trailer /ID, beserta stempel waktu /CreationDate dan /ModDate. Harness membandingkan struktur yang dinormalkan dengan qpdf setelah atom-atom tersebut dihapus.

Permukaan API

NextPDF\Core\Concerns\HasBarcodes (digabungkan ke 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

Simbologi adalah standar barcode yang menentukan cara data diubah menjadi bar atau modul. BarcodeType memuat simbologi 1D (C128, EAN13, UPCA, I25, CODABAR, ISBN, GS1_128, …), dan Barcode2DType memuat simbologi 2D (QRCode, DataMatrix, PDF417, HanXin, MicroQR, …).

Contoh kode — Memulai cepat

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

Contoh kode — Produksi

Contoh lengkap di bawah ini dapat dijalankan oleh harness dan mencerminkan examples/10-barcodes.php. Contoh ini menulis PDF ke path yang disediakan harness melalui NEXTPDF_COOKBOOK_OUTPUT, dengan fallback ke berkas lokal saat Anda menjalankannya secara manual. Harness reproduksibilitas kemudian dapat menjalankannya dua kali dan memverifikasi kesamaan struktural. Strukturnya dinormalkan dengan qpdf; atom /ID per-penyimpanan dan atom stempel waktu dihilangkan.

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

Keluaran yang diharapkan:

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

Kasus tepi & hal yang perlu diperhatikan

Validitas payload bergantung pada simbologi. EAN13 memerlukan 12 atau 13 digit. Payload yang tidak valid akan melemparkan eksepsi sebelum NextPDF menulis konten apa pun. UPCA, ISBN, dan ISSN memiliki aturan panjang dan digit pemeriksa tersendiri.
x/y bersifat opsional. Jika Anda tidak mengisinya, barcode ditempatkan pada posisi kursor saat ini. Berikan koordinat eksplisit untuk tata letak yang dapat diprediksi.
w = 0 mengatur ukuran secara otomatis. Lebar nol memungkinkan encoder memilih lebar modul alami. Berikan lebar positif agar pas dalam kotak berukuran tetap.
Tingkat koreksi galat 2D. write2DBarcode() menggunakan nilai default ecLevel: 'L', tingkat terendah. Naikkan tingkatnya ('M', 'Q', 'H') untuk QR Code yang harus tetap terbaca meski cetakan rusak. Tingkat yang lebih tinggi memperbesar matriks.
Application identifier GS1. Berikan gs1: true pada write2DBarcode(), atau gunakan BarcodeType::GS1_128, untuk data terstruktur GS1 dengan prefiks FNC1.
Halaman dibuat secara implisit. Saat Anda memanggil metode barcode sebelum addPage(), NextPDF menambahkan halaman terlebih dahulu. Ini praktis, tetapi panggil addPage() secara eksplisit bila geometri halaman penting.

Kinerja

Pengenkodean adalah O(panjang payload) untuk 1D dan O(luas matriks) untuk 2D, dan keduanya berjalan dalam orde mikrodetik. Setiap modul adalah satu operator path re … f, sehingga QR Code yang padat menambah beberapa kilobita aliran konten. Tidak ada langkah rasterisasi, sehingga penggunaan memori tetap stabil terlepas dari ukuran simbol. Resep ini tetap berada jauh di bawah anggaran 1500 ms / 64 MB.

Catatan keamanan

Barcode membawa payload apa pun yang Anda berikan, jadi perlakukan nilai barcode seperti input tidak tepercaya lainnya di sisi yang mengonsumsinya. Pustaka ini tidak menandatangani atau mengautentikasi payload. Simbol 2D bukan enkripsi: siapa pun yang memiliki pemindai dapat membacanya.

Kesesuaian

Pernyataan	Spesifikasi	Klausul
Modul barcode digambar menggunakan operator konstruksi path rectangle.	ISO 32000-2	§8.5
Karakter simbol Code 128 menggunakan struktur elemen bar/space yang telah ditetapkan.	ISO/IEC 15417	§4.3.1
Simbol Data Matrix menggunakan koreksi galat Reed-Solomon.	ISO/IEC 16022	§7.6.1
Data QR Code dipecah menjadi blok-blok koreksi galat.	ISO/IEC 18004	§7.5.2

NextPDF mengimplementasikan pengenkodean simbologi yang dirujuk, tetapi tidak mengklaim sertifikasi formal terhadap standar barcode tersebut. Lisensi dokumen korpus simbologi barcode dibatasi pada Tier C. Kutipan hanya menggunakan penunjuk clause-id dan reference_id, dan tidak ada teks standar yang direproduksi.