Barcode — Riferimento approfondito

In sintesi

La superficie di codici a barre di NextPDF Pro aggiunge simbologie 2D specialistiche e di supply chain sopra il modulo barcode di Core. Include sei encoder 2D risolti tramite registro (Micro QR, DotCode, Han Xin Code, JabCode, rMQR, GS1 DataBar), un encoder di componente 2D GS1 Composite (CC-C), l’encoder 1D USPS Intelligent Mail e un parser di Application Identifier GS1 più un validatore di supply chain. La codifica è deterministica: lo stesso payload e le stesse opzioni producono sempre una matrice di moduli identica. Questa pagina definisce l’API pubblica, il contratto di comportamento, le modalità di fallimento e le prove di conformità per ciascuna simbologia.

Disponibilità e licenza

Questa capability è inclusa in NextPDF Pro (nextpdf/pro) e si attiva con un envelope di licenza di livello Pro. Un deployment privo di tale entitlement non carica le classi della capability. Confronta le edizioni e ottieni una licenza.

composer require nextpdf/pro:^3

Ogni simbologia vincola il proprio nome di capability nell’envelope di licenza: barcode.microqr, barcode.dotcode, barcode.hanxin, barcode.jabcode, barcode.rmqr, barcode.gs1databar e barcode.gs1-composite-cc-c. Quando una capability non è licenziata, il registro non risolve quell’encoder. La codifica a simbolo completo di GS1 Composite CC-A e CC-B non è supportata (vedere la tabella dello stato di supporto), quindi non viene registrata alcuna chiave barcode.gs1-composite-cc-a o barcode.gs1-composite-cc-b.

Superficie API pubblica

Le chiavi del registro provengono dai valori dei case di NextPDF\Barcode\Barcode2DType di Core più la chiave letterale gs1-composite-cc-c. Per gli encoder risolti tramite registro, la chiave del registro è il contratto stabile, non il FQCN dell’encoder.

Simbolo	Parametri	Comportamento predefinito	Restituisce	Genera o fallisce con	Note
BarcodeProServiceProvider::register()	BarcodeEncoderRegistry $registry	Collega tutte e sette le chiavi di registro di Pro	void	—	Statico; idempotente — una seconda chiamata sostituisce il primo binding
MicroQrEncoder::encode()	$data; opzioni ecLevel ('L', 'M', 'Q'; default 'L'), version (1–4 o null), mask (0–3 o null)	Seleziona automaticamente la versione M1–M4 più piccola che si adatta	Barcode2DData	InvalidArgumentException	'H' non supportato viene forzato SILENZIOSAMENTE a 'L' (i chiamanti che necessitano di una selezione EC fail-closed devono preconvalidare); M1 ignora ecLevel
DotCodeEncoder::encode()	$data; opzioni gs1 (bool, default false), columns (int), rows (int), ratio (float, default 1.5)	Dimensionamento automatico della griglia con rapporto larghezza:altezza 1.5	Barcode2DData	InvalidArgumentException	Le dimensioni della griglia possono essere forzate per asse
HanXinEncoder::encode()	$data; opzioni ecLevel (0–3, default 1), version (1–84, default auto)	Versione più piccola che si adatta	Barcode2DData	InvalidArgumentException	Modalità di testo GB 2312 Region 1/2 secondo ISO/IEC 20830
JabCodeEncoder::encode()	$data; opzioni colors (4, 8, 16, 32, 64, 128, 256; default 8), eccLevel (0–10, default 3), symbolNumber (1–61, default 1), symbolVersions, symbolPositions, symbolEccLevels	Singolo simbolo a 8 colori	BarcodeColorData	InvalidArgumentException, JabCodeEncodingException	Matrice di moduli policromatica con palette
RmqrEncoder::encode()	$data; opzioni ecLevel (RmqrConstants::EC_M default, o EC_H), version (per es. 'R7x43', default auto)	La più piccola tra le 32 versioni ISO/IEC 23941 che si adatta	Barcode2DData	InvalidArgumentException	Rifiuta i payload che superano la capacità; non tronca mai
Gs1DataBarEncoder::encode()	$data; opzioni variant (Gs1DataBarVariant, default OMNIDIRECTIONAL), linkage (bool, default false), height (int, default minimo della variante; per riga per Expanded Stacked), segmentsPerRow (int, default 4; solo Expanded Stacked)	Codifica un input GTIN (famiglia §5/§6) o una stringa di elementi GS1 AI (famiglia §7)	Barcode2DData	InvalidArgumentException; InvalidSymbolStructureException	Tutte e sette le varianti dell’Annex J di ISO/IEC 24724 vengono codificate
Gs1DataBarVariant	—	isImplemented() restituisce true per tutti e sette i case	enum (7 case)	—	minimumHeightX() e defaultHeightX() secondo l’Annex J
ImbEncoder::encode()	string $code (20, 25, 29 o 31 cifre)	65 barre a quattro stati	BarcodeData	InvalidArgumentException	Interfaccia di encoder 1D; non è una chiave di registro 2D
ImbEncoder::encodeToString()	string $code	Stati delle barre come stringa T/A/D/F	string	InvalidArgumentException	Per verifiche rispetto ai vettori di riferimento USPS
Gs1DataParser::parse()	string $data	Rileva automaticamente gli URI Digital Link, altrimenti il formato (AI)value	Gs1ParsedData	InvalidArgumentException	Implementa il contratto Gs1DataParserInterface di Core
Gs1DataParser::parseDigitalLink()	string $uri	Analizza un URI GS1 Digital Link	Gs1ParsedData	InvalidArgumentException	—
Gs1DataParser::encodeForCode128() / ::encodeForQrCode() / ::encodeForDataMatrix()	object $parsed	Sequenza di byte del carrier con la convenzione FNC1 di quel carrier	string	—	Si aspetta un’istanza Gs1ParsedData
Gs1DataParser::validateAI()	string $ai, string $value	Verifica strutturale di un valore AI	bool	—	—
Gs1Validator::validate()	string $barcodeData, Gs1SupplyChainProfile $profile (default NONE)	Percorso rapido statico su run()	Gs1ValidationResult	—	I fallimenti di parsing diventano findings, non eccezioni
Gs1Validator::run()	come validate()	Parsing, cifre di controllo, date, regole cross-AI, profilo	Gs1ValidationResult	—	Percorso di istanza; il costruttore accetta un parser iniettato
Gs1SupplyChainProfile	—	NONE salta le regole di profilo	enum (5 case)	—	RETAIL, FOOD, PHARMA, LOGISTICS, NONE; requiredAIs(), recommendedAIs(), primaryIdentifiers()
Gs1ValidationResult	—	Findings partizionati per severità in fase di costruzione	classe readonly	—	isValid, findings, errors, warnings, infos, parsedData; passes(), fails(), totalFindings()
Gs1ValidationFinding / Gs1FindingSeverity	—	severity, ruleId, message, ai e suggestion opzionali	classe readonly / enum	—	Severità: Error, Warning, Info
CompositeComponentA::codewordsFor()	string $data	Encodation a stringa binaria general-purpose §5, conversione base-928, self-check di round-trip	list<int> (ciascuno 0–927)	InvalidArgumentException	Alimenta linkFor() o un renderer di carrier CC-A esterno
CompositeComponentA::encode()	ignorato	Rifiuta il rendering a simbolo completo di CC-A	—	UnsupportedBarcodeFeature (sempre)	Fail-closed; vedere Casi limite
CompositeComponentB::encode()	ignorato	Rifiuta la codifica 2D di CC-B	—	UnsupportedBarcodeFeature (sempre)	linkFor() resta disponibile (CCSI 901)
CompositeComponentC::encode()	$data; opzioni inoltrate al carrier PDF417; carrierType (default GS1_128)	Carrier PDF417 completo con il codeword CCSI 920 in testa	Barcode2DData	BarcodeException; CompositeLinkageException	È ammissibile solo il carrier GS1_128
CompositeComponent{A,B,C}::linkFor()	string $carrierId, array $codewords, CompositeCarrierType $carrierType	Abbina i codeword del componente a un carrier 1D	CompositeLinkage	CompositeLinkageException	Impone l’ammissibilità e la capacità del carrier
CompositeVariant / CompositeCarrierType	—	CC_A, CC_B, CC_C; GS1_DATABAR, GS1_128	enum	—	maxCodewords(), ccsi(), allowedCarriers(), usesFullPdf417()

Firme dei punti di ingresso

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

Contratto di comportamento

Risoluzione del registro

La factory del registro predefinito di Core pre-collega gli encoder di Pro come voci lazy soggette a licenza di capability. BarcodeProServiceProvider::register() è il fallback supportato per le applicazioni che compongono un registro senza valori predefiniti, per esempio le integrazioni di framework con il proprio container. Ogni encoder converte un payload stringa e le opzioni per ciascuna simbologia in un oggetto dati di codice a barre che il renderer di pagina trasforma in operatori di contenuto PDF.

Parsing e convalida GS1

Gs1DataParser accetta stringhe AI leggibili dall’uomo ((01)09521234543213(17)260131) e URI GS1 Digital Link. Produce sequenze di byte codificate per i carrier GS1-128, QR Code e Data Matrix, applicando la convenzione FNC1 e di separatore di gruppo di ciascun carrier. Gs1Validator esegue una pipeline in cinque passi: parsing, cifre di controllo (GTIN, SSCC), logica delle date, regole cross-AI e AI obbligatori del profilo di settore. Un fallimento di parsing produce un risultato non valido che trasporta i findings; non genera eccezioni. I findings sono partizionati per severità in errori, avvisi e informazioni.

Dispatch delle varianti GS1 DataBar

Gs1DataBarEncoder::encode() gestisce tutte e sette le varianti dell’Annex J di ISO/IEC 24724:2011 attraverso un unico contratto di opzioni. Omnidirectional, Truncated, Stacked e Stacked Omnidirectional condividono l’algebra della larghezza degli elementi §5 con un carattere di controllo mod-79. Limited usa la propria algebra dei caratteri di simbolo §6 con un carattere di controllo mod-89. Expanded ed Expanded Stacked usano l’algebra (17,4) §7: la macchina a stati di compattazione a tre modalità (numerica, alfanumerica e ISO/IEC 646) del §7.2.5.5 più un carattere di controllo mod-211 (§7.2.6). La famiglia §5/§6 accetta un GTIN-14 a 14 cifre con cifra di controllo mod-10 o un’identificazione di articolo a 13 cifre. La famiglia §7 accetta una stringa grezza di elementi GS1 AI (cifre, lettere, il sottoinsieme di punteggiatura ISO/IEC 646, FNC1 come byte 0x1D). L’opzione linkage imposta il flag di linkage del componente 2D per l’uso come componente lineare di un simbolo GS1 Composite.

Componenti GS1 Composite

CC-C produce un componente esteso 2D completo sull’intero carrier PDF417, iniettando il codeword CCSI obbligatorio 920 come primo data codeword (ISO/IEC 24723:2010 §5.4). CC-A genera data codeword base-928 conformi tramite codewordsFor(), con un self-check di round-trip codifica-decodifica fail-closed, ma rifiuta il rendering a simbolo completo. CC-B rifiuta del tutto la codifica 2D. linkFor() abbina i codeword del componente a un carrier 1D come valore CompositeLinkage, imponendo l’ammissibilità e la capacità del carrier.

Casi limite e modalità di fallimento

• Ogni encoder rifiuta un payload vuoto con InvalidArgumentException.
• Micro QR: richiedere il livello di correzione degli errori H non supportato lo forza SILENZIOSAMENTE a L anziché fallire (preconvalidare le opzioni se si richiede una selezione EC fail-closed), perché ISO/IEC 18004 definisce solo L, M e Q per i simboli Micro QR.
• rMQR: il livello di correzione degli errori deve essere M o H; un payload che supera la capacità delle 32 versioni viene rifiutato, mai troncato.
• JabCode: un numero di colori al di fuori dell’insieme di potenze di due supportato, un livello ECC al di fuori di 0–10 o un numero di simboli al di fuori di 1–61 viene rifiutato; i fallimenti di codifica a valle generano JabCodeEncodingException.
• GS1 DataBar: la famiglia §5/§6 convalida la cifra di controllo mod-10 del GTIN e Limited limita la cifra indicatore a 0 o 1. La famiglia §7 rifiuta i caratteri non codificabili e i separatori FNC1 finali o doppi. Expanded Stacked rifiuta un numero dispari di caratteri di simbolo per riga e le altezze per riga inferiori al minimo di 34X. I self-check della struttura interna falliscono con InvalidSymbolStructureException anziché emettere un simbolo malformato.
• GS1 Composite: encode() di CC-A e CC-B genera sempre UnsupportedBarcodeFeature (fail closed). CC-C genera BarcodeException in caso di dati vuoti o di overflow della capacità PDF417 (più di 925 codeword) e CompositeLinkageException per un carrier non ammissibile.
• La convalida GS1 segnala la struttura AI malformata e le cifre di controllo errate prima della codifica; una stringa di supply chain non valida non produce mai un simbolo conforme scansionabile.
• IMB accetta solo input a 20, 25, 29 o 31 cifre.
• La codifica dei codici a barre non esegue alcuna crittografia. Non esiste alcun comportamento specifico per la modalità FIPS; gli encoder vengono eseguiti in modo identico indipendentemente dal profilo FIPS.

Conformità

NextPDF implementa queste simbologie rispetto agli standard pubblicati citati di seguito e fissa le reference-trace nella propria suite di test. Le affermazioni in questa pagina sono dichiarazioni di capability: il supporto non è conformità e la conformità non è certificazione. NextPDF non detiene alcuna certificazione di simbologia. Le àncore di clausola sono parafrasate dal codice sorgente del prodotto e dalle sue fixture di conformità; il corpus del compliance engine non copre gli standard delle simbologie di codici a barre, quindi le àncore di seguito sono fondate sul prodotto e prive di identificatori di riferimento.

Superficie	Standard	Àncora di clausola (parafrasata)
Algebra della larghezza degli elementi GS1 DataBar	ISO/IEC 24724:2011	§5.2 struttura del carattere di simbolo; Annex F.1 esempio applicato (Omnidirectional); Annex F.2 (Limited); Annex F.3 (Expanded)
Layout stacked GS1 DataBar	ISO/IEC 24724:2011	§5.4 Stacked; §5.5 Stacked Omnidirectional; §7.2.8 partizione delle righe e separatori Expanded Stacked
Encodation GS1 DataBar Expanded	ISO/IEC 24724:2011	§7.2.5.5 macchina a stati di compattazione a tre modalità; §7.2.6 carattere di controllo mod-211
Linkage GS1 Composite e CC-C	ISO/IEC 24723:2010	§5.4 semantica del codeword CCSI; §5.1 ammissibilità del carrier
Codeword GS1 Composite CC-A	ISO/IEC 24723:2010	§5 encodation a stringa binaria general-purpose con conversione base-928
Struttura del simbolo rMQR	ISO/IEC 23941:2022	§6.3.2 Table 1 dimensioni delle versioni; §7.8.2 maschera fissa; Annex C / Annex I riferimento delle informazioni di formato
Micro QR	ISO/IEC 18004	Capacità Micro QR M1–M4 e informazioni di formato
Han Xin Code	ISO/IEC 20830:2021	Struttura del simbolo; pattern di finder e alignment; modalità GB 2312 Region 1/2; ECC Reed–Solomon; mascheramento
JabCode	ISO/IEC 23634	Struttura di simbolo, colore ed ECC
Simbologia postale	USPS-B-3200	Struttura dei campi dell’Intelligent Mail Barcode

Stato di supporto per ciascuna simbologia

Una variante è Verificata quando una fixture sotto pro/tests/** la esercita, preferibilmente una reference-trace ancorata a un esempio applicato pubblicato. Una variante inclusa priva di una fixture dedicata resta Dichiarata. Una variante priva di encoder è Non supportata.

Simbologia / variante	Stato	Prova (percorso di test)	Note
Micro QR (M1–M4)	Verificata	pro/tests/Unit/Barcode/MicroQrEncoderTest.php	A livello di unit; una fixture di reference-trace su un esempio applicato è un backfill tracciato
DotCode	Verificata	pro/tests/Unit/Barcode/DotCodeEncoderTest.php; DotCodeGfArithmeticTest.php	Aritmetica del campo di Galois coperta; nessun round-trip con decoder di terze parti
Han Xin Code	Verificata	pro/tests/Unit/Barcode/HanXinEncoderTest.php; HanXinRsEncodingTest.php	Percorso di codifica Reed–Solomon esercitato esplicitamente
JabCode (1–61 simboli, 4–256 colori, ECC 0–10)	Verificata	pro/tests/Unit/Barcode/JabCode/JabCodeEncoderTest.php (+ 11 suite di componenti nella stessa directory)	Cascata multi-simbolo e intervallo ECC esercitati; nessun round-trip con decoder di terze parti
USPS Intelligent Mail Barcode	Verificata	pro/tests/Unit/Barcode/ImbEncoderTest.php; ImbRoutingCodeTest.php	Convalida del routing-code e della lunghezza a 20/25/29/31 cifre esercitata
rMQR — tutte le 32 versioni ISO/IEC 23941	Verificata	pro/tests/Conformance/Barcode/Rmqr/AnnexValidatedSizesTest.php; RmqrAnnexCFormatInfoTest.php; pro/tests/Unit/Barcode/Rmqr/RmqrEncoderTest.php	Coppie versione/EC verificate rispetto a ISO/IEC 23941 Table 1; valori di riferimento delle informazioni di formato dell’Annex C / Annex I
GS1 DataBar — Omnidirectional / Truncated	Verificata	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarReferenceTest.php	Byte-uguale all’esempio applicato dell’Annex F.1; Truncated condivide la codifica ad altezza ridotta
GS1 DataBar — Stacked / Stacked Omnidirectional	Verificata	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarStackedReferenceTest.php	Suddivisione in righe derivata dalla trace dell’Annex F.1; costruzione dei separatori secondo §5.4 e §5.5
GS1 DataBar — Limited	Verificata	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarLimitedReferenceTest.php; pro/tests/Unit/Barcode/Gs1DataBar/Gs1DataBarLimitedEncoderTest.php	Byte-uguale all’esempio applicato dell’Annex F.2 (item 00098765432105)
GS1 DataBar — Expanded	Verificata	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarExpandedReferenceTest.php; pro/tests/Integration/Barcode/Gs1DataBarExpandedTwoDecoderTest.php	Byte-uguale all’esempio applicato dell’Annex F.3 ((10)12A); round-trip con decoder indipendenti rispetto a zxing-cpp e ZBar
GS1 DataBar — Expanded Stacked	Verificata	pro/tests/Unit/Barcode/Gs1DataBar/Gs1DataBarExpandedEncoderTest.php (casi stacked); il round-trip di integrazione sopra	Stessa pipeline di dati di Expanded a riga singola; partizione delle righe e separatori §7.2.8 asseriti
GS1 Composite — CC-C (carrier PDF417)	Verificata	pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentCTest.php; CompositeRoundtripTest.php; CompositeLinkageTest.php	Codeword CCSI 920 e interazione dei flag di linkage coperti
GS1 Composite — CC-A	Parziale	pro/tests/Unit/Barcode/Gs1Composite/CompositeComponentACodewordTest.php; pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentATest.php	Generazione dei codeword Verificata (base-928, self-check di round-trip); rendering a simbolo completo non supportato — encode() fallisce fail-closed
GS1 Composite — CC-B	Non supportata	pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentBTest.php (asserisce il rifiuto fail-closed)	Nessuna codifica 2D; l’helper di linkage (CCSI 901) resta disponibile
GS1 AI parser	Verificata	pro/tests/Unit/Barcode/Gs1DataParserTest.php; Gs1DataParserFnc1Test.php	Entrambi i formati di input e tutti e tre gli output di sequenza di byte dei carrier esercitati
GS1 supply-chain validator	Verificata	pro/tests/Unit/Barcode/Gs1ValidatorTest.php; Gs1ValidatorCrossAiTest.php; pro/tests/Unit/Barcode/Gs1/Gs1ValidatorDateValidationEdgeCaseTest.php	Cifre di controllo, combinazioni obbligatorie cross-AI e logica delle date esercitate

Note di sviluppo

• Le àncore di prova in questa pagina sono percorsi di test sotto pro/tests/**; il repository non include alcuna directory examples/ per questo modulo.
• I sette nomi di capability elencati sotto Disponibilità e licenza sono le chiavi che il service provider collega. L’encoder IMB è costruito direttamente e non porta alcuna chiave di registro.
• CC-A emette solo il metodo di encodation general-purpose; i metodi compressi specifici per applicazione sono un residuo di densità documentato, non una lacuna di correttezza.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile dall’esterno e la superficie API pubblica supportata. I percorsi di namespace interni, le classi helper, le tabelle di meccanismi, i nomi di file dei runbook e i prefissi dei ticket sono fuori ambito.

Vedere anche

• Panoramica della capability barcode (NextPDF Pro)
• Chart — Riferimento approfondito
• Modulo barcode di Core