Barcode — Referensi Mendalam

Sekilas

Permukaan barcode NextPDF Pro menambahkan simbologi 2D khusus dan rantai pasok di atas modul barcode Core. Ia mengirimkan enam encoder 2D yang diselesaikan-registry (Micro QR, DotCode, Han Xin Code, JabCode, rMQR, GS1 DataBar), satu encoder komponen 2D GS1 Composite (CC-C), encoder 1D USPS Intelligent Mail, serta parser GS1 Application Identifier plus validator rantai pasok. Encoding bersifat deterministik: payload dan opsi yang sama selalu menghasilkan matriks modul yang identik. Halaman ini menyatakan API publik, kontrak perilaku, mode kegagalan, dan bukti konformansi per-simbologi.

Ketersediaan & lisensi

Kapabilitas ini dikirimkan dalam NextPDF Pro (nextpdf/pro) dan diaktifkan dengan envelope lisensi tier-Pro. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

composer require nextpdf/pro:^3

Setiap simbologi mengikat nama kapabilitasnya sendiri dalam envelope lisensi: barcode.microqr, barcode.dotcode, barcode.hanxin, barcode.jabcode, barcode.rmqr, barcode.gs1databar, dan barcode.gs1-composite-cc-c. Ketika sebuah kapabilitas tidak berlisensi, registry tidak menyelesaikan encoder tersebut. Encoding simbol-penuh GS1 Composite CC-A dan CC-B tidak didukung (lihat tabel status dukungan), sehingga tidak ada kunci barcode.gs1-composite-cc-a atau barcode.gs1-composite-cc-b yang didaftarkan.

Permukaan API publik

Kunci registry berasal dari nilai case Core NextPDF\Barcode\Barcode2DType plus kunci literal gs1-composite-cc-c. Untuk encoder yang diselesaikan-registry, kunci registry adalah kontrak yang stabil, bukan FQCN encoder.

Simbol	Parameter	Perilaku baku	Mengembalikan	Melempar atau gagal dengan	Catatan
BarcodeProServiceProvider::register()	BarcodeEncoderRegistry $registry	Mengikat ketujuh kunci registry Pro	void	—	Statik; idempoten — panggilan kedua menggantikan pengikatan pertama
MicroQrEncoder::encode()	$data; opsi ecLevel ('L', 'M', 'Q'; baku 'L'), version (1–4 atau null), mask (0–3 atau null)	Otomatis memilih versi terkecil yang muat M1–M4	Barcode2DData	InvalidArgumentException	'H' yang tidak didukung DIAM-DIAM dipaksa menjadi 'L' (pemanggil yang butuh pemilihan EC gagal-tertutup harus pra-validasi); M1 mengabaikan ecLevel
DotCodeEncoder::encode()	$data; opsi gs1 (bool, baku false), columns (int), rows (int), ratio (float, baku 1.5)	Penentuan ukuran grid otomatis pada rasio lebar:tinggi 1.5	Barcode2DData	InvalidArgumentException	Dimensi grid dapat dipaksakan per sumbu
HanXinEncoder::encode()	$data; opsi ecLevel (0–3, baku 1), version (1–84, baku otomatis)	Versi terkecil yang muat	Barcode2DData	InvalidArgumentException	Mode teks GB 2312 Region 1/2 sesuai ISO/IEC 20830
JabCodeEncoder::encode()	$data; opsi colors (4, 8, 16, 32, 64, 128, 256; baku 8), eccLevel (0–10, baku 3), symbolNumber (1–61, baku 1), symbolVersions, symbolPositions, symbolEccLevels	Simbol 8-warna tunggal	BarcodeColorData	InvalidArgumentException, JabCodeEncodingException	Matriks modul polikrom dengan palette
RmqrEncoder::encode()	$data; opsi ecLevel (RmqrConstants::EC_M baku, atau EC_H), version (mis. 'R7x43', baku otomatis)	Yang terkecil muat dari 32 versi ISO/IEC 23941	Barcode2DData	InvalidArgumentException	Menolak payload yang melebihi kapasitas; tidak pernah memotong
Gs1DataBarEncoder::encode()	$data; opsi variant (Gs1DataBarVariant, baku OMNIDIRECTIONAL), linkage (bool, baku false), height (int, baku minimum varian; per-baris untuk Expanded Stacked), segmentsPerRow (int, baku 4; hanya Expanded Stacked)	Meng-encode input GTIN (keluarga §5/§6) atau string elemen GS1 AI (keluarga §7)	Barcode2DData	InvalidArgumentException; InvalidSymbolStructureException	Ketujuh varian ISO/IEC 24724 Annex J dapat di-encode
Gs1DataBarVariant	—	isImplemented() mengembalikan true untuk ketujuh case	enum (7 case)	—	minimumHeightX() dan defaultHeightX() sesuai Annex J
ImbEncoder::encode()	string $code (20, 25, 29, atau 31 digit)	65 bar empat-status	BarcodeData	InvalidArgumentException	Antarmuka encoder 1D; bukan kunci registry 2D
ImbEncoder::encodeToString()	string $code	Status bar sebagai string T/A/D/F	string	InvalidArgumentException	Untuk pemeriksaan terhadap vektor acuan USPS
Gs1DataParser::parse()	string $data	Otomatis mendeteksi URI Digital Link, jika tidak format (AI)value	Gs1ParsedData	InvalidArgumentException	Mengimplementasikan kontrak Core Gs1DataParserInterface
Gs1DataParser::parseDigitalLink()	string $uri	Mengurai URI GS1 Digital Link	Gs1ParsedData	InvalidArgumentException	—
Gs1DataParser::encodeForCode128() / ::encodeForQrCode() / ::encodeForDataMatrix()	object $parsed	Urutan byte pembawa dengan konvensi FNC1 pembawa tersebut	string	—	Mengharapkan instance Gs1ParsedData
Gs1DataParser::validateAI()	string $ai, string $value	Pemeriksaan struktural satu nilai AI	bool	—	—
Gs1Validator::validate()	string $barcodeData, Gs1SupplyChainProfile $profile (baku NONE)	Jalur cepat statik atas run()	Gs1ValidationResult	—	Kegagalan penguraian menjadi temuan, bukan eksepsi
Gs1Validator::run()	seperti validate()	Urai, check digit, tanggal, aturan cross-AI, profil	Gs1ValidationResult	—	Jalur instance; konstruktor menerima parser yang diinjeksikan
Gs1SupplyChainProfile	—	NONE melewati aturan profil	enum (5 case)	—	RETAIL, FOOD, PHARMA, LOGISTICS, NONE; requiredAIs(), recommendedAIs(), primaryIdentifiers()
Gs1ValidationResult	—	Temuan dipartisi menurut severitas saat konstruksi	readonly class	—	isValid, findings, errors, warnings, infos, parsedData; passes(), fails(), totalFindings()
Gs1ValidationFinding / Gs1FindingSeverity	—	severity, ruleId, message, opsional ai dan suggestion	readonly class / enum	—	Severitas: Error, Warning, Info
CompositeComponentA::codewordsFor()	string $data	Encodation binary-string tujuan-umum §5, konversi base-928, self-check round-trip	list<int> (masing-masing 0–927)	InvalidArgumentException	Umpankan ke linkFor() atau perender pembawa CC-A eksternal
CompositeComponentA::encode()	diabaikan	Menolak perenderan simbol-penuh CC-A	—	UnsupportedBarcodeFeature (selalu)	Gagal-tertutup; lihat Kasus tepi
CompositeComponentB::encode()	diabaikan	Menolak encoding 2D CC-B	—	UnsupportedBarcodeFeature (selalu)	linkFor() tetap tersedia (CCSI 901)
CompositeComponentC::encode()	$data; opsi diteruskan ke pembawa PDF417; carrierType (baku GS1_128)	Pembawa PDF417 penuh dengan CCSI codeword 920 di depan	Barcode2DData	BarcodeException; CompositeLinkageException	Hanya pembawa GS1_128 yang diperbolehkan
CompositeComponent{A,B,C}::linkFor()	string $carrierId, array $codewords, CompositeCarrierType $carrierType	Memasangkan codeword komponen dengan pembawa 1D	CompositeLinkage	CompositeLinkageException	Menegakkan keterterimaan dan kapasitas pembawa
CompositeVariant / CompositeCarrierType	—	CC_A, CC_B, CC_C; GS1_DATABAR, GS1_128	enum	—	maxCodewords(), ccsi(), allowedCarriers(), usesFullPdf417()

Tanda tangan titik masuk

public static function register(BarcodeEncoderRegistry $registry): void

public function encode(string $data, array $options = []): Barcode2DData

public static function validate(
    string $barcodeData,
    Gs1SupplyChainProfile $profile = Gs1SupplyChainProfile::NONE,
): Gs1ValidationResult

public function run(
    string $barcodeData,
    Gs1SupplyChainProfile $profile = Gs1SupplyChainProfile::NONE,
): Gs1ValidationResult

public function parse(string $data): Gs1ParsedData
public function parseDigitalLink(string $uri): Gs1ParsedData
public function encodeForCode128(object $parsed): string
public function encodeForQrCode(object $parsed): string
public function encodeForDataMatrix(object $parsed): string
public function validateAI(string $ai, string $value): bool

public function codewordsFor(string $data): array

Kontrak perilaku

Resolusi registry

Factory registry baku Core pra-mengikat encoder Pro sebagai entri lazy yang berlisensi-kapabilitas. BarcodeProServiceProvider::register() adalah fallback yang didukung untuk aplikasi yang menyusun registry tanpa baku, misalnya integrasi framework dengan kontainer mereka sendiri. Setiap encoder mengonversi payload string dan opsi per-simbologi menjadi objek data barcode yang diubah oleh perender halaman menjadi operator konten PDF.

Penguraian dan validasi GS1

Gs1DataParser menerima string AI yang dapat dibaca manusia ((01)09521234543213(17)260131) dan URI GS1 Digital Link. Ia menghasilkan urutan byte ter-encode untuk pembawa GS1-128, QR Code, dan Data Matrix, menerapkan konvensi FNC1 dan pemisah-grup tiap pembawa. Gs1Validator menjalankan pipeline lima-langkah: urai, check digit (GTIN, SSCC), logika tanggal, aturan cross-AI, dan AI wajib profil-industri. Kegagalan penguraian menghasilkan hasil tidak valid yang membawa temuan; ia tidak melempar eksepsi. Temuan dipartisi menurut severitas menjadi error, warning, dan info.

Pemilihan varian GS1 DataBar (dispatch)

Gs1DataBarEncoder::encode() mem-dispatch ketujuh varian ISO/IEC 24724:2011 Annex J melalui satu kontrak opsi. Omnidirectional, Truncated, Stacked, dan Stacked Omnidirectional berbagi aljabar lebar-elemen §5 dengan check character mod-79. Limited memakai aljabar simbol-karakter §6 miliknya sendiri dengan check character mod-89. Expanded dan Expanded Stacked memakai aljabar (17,4) §7: mesin-status kompaksi tiga-mode numerik, alfanumerik, dan ISO/IEC 646 §7.2.5.5 plus check character mod-211 (§7.2.6). Keluarga §5/§6 menerima GTIN-14 14-digit dengan check digit mod-10 atau identifikasi item 13-digit. Keluarga §7 menerima string elemen GS1 AI mentah (digit, huruf, subset tanda baca ISO/IEC 646, FNC1 sebagai byte 0x1D). Opsi linkage mengeset flag pengaitan komponen-2D untuk digunakan sebagai komponen linear simbol GS1 Composite.

Komponen GS1 Composite

CC-C menghasilkan komponen perluasan 2D lengkap di atas pembawa PDF417 penuh, menyuntikkan CCSI codeword 920 wajib sebagai data codeword pemimpin (ISO/IEC 24723:2010 §5.4). CC-A membangkitkan data codeword base-928 yang konforman melalui codewordsFor(), dengan self-check round-trip encode-decode gagal-tertutup, tetapi menolak perenderan simbol-penuh. CC-B menolak encoding 2D sepenuhnya. linkFor() memasangkan codeword komponen dengan pembawa 1D sebagai nilai CompositeLinkage, menegakkan keterterimaan dan kapasitas pembawa.

Kasus tepi & mode kegagalan

• Setiap encoder menolak payload kosong dengan InvalidArgumentException.
• Micro QR: meminta tingkat koreksi-kesalahan H yang tidak didukung DIAM-DIAM dipaksa menjadi L alih-alih gagal (pra-validasi opsi jika Anda memerlukan pemilihan EC gagal-tertutup), karena ISO/IEC 18004 hanya mendefinisikan L, M, dan Q untuk simbol Micro QR.
• rMQR: tingkat koreksi-kesalahan harus M atau H; payload yang melebihi kapasitas 32 versi ditolak, tidak pernah dipotong.
• JabCode: jumlah warna di luar set pangkat-dua yang didukung, tingkat ECC di luar 0–10, atau jumlah simbol di luar 1–61 ditolak; kegagalan encoding di hilir memunculkan JabCodeEncodingException.
• GS1 DataBar: keluarga §5/§6 memvalidasi check digit mod-10 GTIN, dan Limited membatasi digit indikator ke 0 atau 1. Keluarga §7 menolak karakter yang tidak dapat di-encode serta pemisah FNC1 yang menggantung atau ganda. Expanded Stacked menolak jumlah simbol-karakter ganjil per baris dan tinggi per-baris di bawah minimum 34X. Self-check struktur internal gagal dengan InvalidSymbolStructureException alih-alih memancarkan simbol yang malformasi.
• GS1 Composite: encode() CC-A dan CC-B selalu melempar UnsupportedBarcodeFeature (gagal-tertutup). CC-C melempar BarcodeException pada data kosong atau limpahan kapasitas PDF417 (lebih dari 925 codeword), dan CompositeLinkageException untuk pembawa yang tidak diperbolehkan.
• Validasi GS1 menandai struktur AI yang malformasi dan check digit yang buruk sebelum encoding; string rantai pasok yang tidak valid tidak pernah menghasilkan simbol konforman yang dapat dipindai.
• IMB hanya menerima input 20, 25, 29, atau 31 digit.
• Encoding barcode tidak melakukan kriptografi. Tidak ada perilaku khusus-mode-FIPS; encoder berjalan identik terlepas dari profil FIPS.

Kesesuaian

NextPDF mengimplementasikan simbologi-simbologi ini terhadap standar yang dipublikasikan yang dikutip di bawah dan memaku reference trace dalam test suite-nya. Pernyataan di halaman ini adalah klaim kapabilitas: dukungan bukanlah konformansi, dan konformansi bukanlah sertifikasi. NextPDF tidak memegang sertifikasi simbologi apa pun. Jangkar klausa diparafrasakan dari sumber produk dan fixture konformansinya; korpus compliance-engine tidak mencakup standar simbologi barcode, sehingga jangkar di bawah berbasis-produk tanpa pengenal acuan.

Permukaan	Standar	Jangkar klausa (diparafrasakan)
Aljabar lebar-elemen GS1 DataBar	ISO/IEC 24724:2011	§5.2 struktur simbol-karakter; Annex F.1 contoh terselesaikan (Omnidirectional); Annex F.2 (Limited); Annex F.3 (Expanded)
Tata letak stacked GS1 DataBar	ISO/IEC 24724:2011	§5.4 Stacked; §5.5 Stacked Omnidirectional; §7.2.8 partisi baris dan pemisah Expanded Stacked
Encodation GS1 DataBar Expanded	ISO/IEC 24724:2011	§7.2.5.5 mesin-status kompaksi tiga-mode; §7.2.6 check character mod-211
Pengaitan GS1 Composite dan CC-C	ISO/IEC 24723:2010	§5.4 semantik CCSI codeword; §5.1 keterterimaan pembawa
Codeword CC-A GS1 Composite	ISO/IEC 24723:2010	§5 encodation binary-string tujuan-umum dengan konversi base-928
Struktur simbol rMQR	ISO/IEC 23941:2022	§6.3.2 Table 1 dimensi versi; §7.8.2 mask tetap; Annex C / Annex I acuan informasi-format
Micro QR	ISO/IEC 18004	Kapasitas dan informasi format Micro QR M1–M4
Han Xin Code	ISO/IEC 20830:2021	Struktur simbol; pola finder dan alignment; mode GB 2312 Region 1/2; ECC Reed–Solomon; masking
JabCode	ISO/IEC 23634	Struktur simbol, warna, dan ECC
Simbologi pos	USPS-B-3200	Struktur bidang Intelligent Mail Barcode

Status dukungan per-simbologi

Sebuah varian bersifat Verified ketika sebuah fixture di bawah pro/tests/** mengujinya, sebaiknya reference trace yang dipatok pada contoh terselesaikan yang dipublikasikan. Varian yang dikirimkan tanpa fixture khusus tetap Claimed. Varian tanpa encoder adalah Not supported.

Simbologi / varian	Status	Bukti (path tes)	Catatan
Micro QR (M1–M4)	Verified	pro/tests/Unit/Barcode/MicroQrEncoderTest.php	Tingkat-unit; fixture reference-trace contoh-terselesaikan adalah backfill yang dilacak
DotCode	Verified	pro/tests/Unit/Barcode/DotCodeEncoderTest.php; DotCodeGfArithmeticTest.php	Aritmetika Galois-field tercakup; tidak ada round trip dekoder vendor
Han Xin Code	Verified	pro/tests/Unit/Barcode/HanXinEncoderTest.php; HanXinRsEncodingTest.php	Jalur encoding Reed–Solomon diuji secara eksplisit
JabCode (1–61 simbol, 4–256 warna, ECC 0–10)	Verified	pro/tests/Unit/Barcode/JabCode/JabCodeEncoderTest.php (+ 11 component suite di direktori yang sama)	Kaskade multi-simbol dan rentang ECC diuji; tidak ada round trip dekoder vendor
USPS Intelligent Mail Barcode	Verified	pro/tests/Unit/Barcode/ImbEncoderTest.php; ImbRoutingCodeTest.php	Validasi routing-code dan panjang 20/25/29/31-digit diuji
rMQR — semua 32 versi ISO/IEC 23941	Verified	pro/tests/Conformance/Barcode/Rmqr/AnnexValidatedSizesTest.php; RmqrAnnexCFormatInfoTest.php; pro/tests/Unit/Barcode/Rmqr/RmqrEncoderTest.php	Pasangan versi dan EC diperiksa terhadap ISO/IEC 23941 Table 1; nilai acuan informasi-format Annex C / Annex I
GS1 DataBar — Omnidirectional / Truncated	Verified	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarReferenceTest.php	Byte-equal dengan contoh terselesaikan Annex F.1; Truncated berbagi encoding pada tinggi berkurang
GS1 DataBar — Stacked / Stacked Omnidirectional	Verified	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarStackedReferenceTest.php	Pembagian baris diturunkan dari trace Annex F.1; konstruksi pemisah sesuai §5.4 dan §5.5
GS1 DataBar — Limited	Verified	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarLimitedReferenceTest.php; pro/tests/Unit/Barcode/Gs1DataBar/Gs1DataBarLimitedEncoderTest.php	Byte-equal dengan contoh terselesaikan Annex F.2 (item 00098765432105)
GS1 DataBar — Expanded	Verified	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarExpandedReferenceTest.php; pro/tests/Integration/Barcode/Gs1DataBarExpandedTwoDecoderTest.php	Byte-equal dengan contoh terselesaikan Annex F.3 ((10)12A); round trip dekoder-independen terhadap zxing-cpp dan ZBar
GS1 DataBar — Expanded Stacked	Verified	pro/tests/Unit/Barcode/Gs1DataBar/Gs1DataBarExpandedEncoderTest.php (case stacked); round trip integrasi di atas	Pipeline data sama dengan Expanded baris-tunggal; partisi baris dan pemisah §7.2.8 ditegaskan
GS1 Composite — CC-C (pembawa PDF417)	Verified	pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentCTest.php; CompositeRoundtripTest.php; CompositeLinkageTest.php	CCSI codeword 920 dan interaksi flag-pengaitan tercakup
GS1 Composite — CC-A	Partial	pro/tests/Unit/Barcode/Gs1Composite/CompositeComponentACodewordTest.php; pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentATest.php	Pembangkitan codeword Verified (base-928, self-check round-trip); perenderan simbol-penuh tidak didukung — encode() gagal-tertutup
GS1 Composite — CC-B	Not supported	pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentBTest.php (menegaskan penolakan gagal-tertutup)	Tanpa encoding 2D; pembantu pengaitan (CCSI 901) tetap tersedia
GS1 AI parser	Verified	pro/tests/Unit/Barcode/Gs1DataParserTest.php; Gs1DataParserFnc1Test.php	Kedua format input dan ketiga keluaran urutan-byte pembawa diuji
GS1 supply-chain validator	Verified	pro/tests/Unit/Barcode/Gs1ValidatorTest.php; Gs1ValidatorCrossAiTest.php; pro/tests/Unit/Barcode/Gs1/Gs1ValidatorDateValidationEdgeCaseTest.php	Check digit, kombinasi wajib cross-AI, dan logika tanggal diuji

Catatan pengembangan

• Jangkar bukti di halaman ini adalah path tes di bawah pro/tests/**; repositori tidak mengirimkan direktori examples/ untuk modul ini.
• Tujuh nama kapabilitas yang tercantum di bawah Ketersediaan & lisensi adalah kunci yang diikat service provider. Encoder IMB dikonstruksi langsung dan tidak membawa kunci registry.
• CC-A hanya memancarkan metode encodation tujuan-umum; metode terkompresi spesifik-aplikasi adalah residual densitas yang terdokumentasi, bukan celah kebenaran.

Batas publikasi

Halaman ini hanya mendokumentasikan perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung. Path namespace internal, kelas pembantu, tabel mekanisme, nama file runbook, dan prefiks tiket berada di luar cakupan.

Lihat juga

• Ikhtisar kapabilitas barcode (NextPDF Pro)
• Referensi mendalam Chart
• Modul barcode Core