Barcode

In breve

NextPDF Pro aggiunge simbologie di codici a barre 2D specializzate e per la catena di approvvigionamento sopra le simbologie lineari e QR dell’edizione open source. Ogni simbologia viene renderizzata direttamente su una superficie di pagina PDF come content stream deterministico.

Disponibilità e licenza

Questa funzionalità è distribuita 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 funzionalità. Confronta le edizioni e ottieni una licenza.

Installazione

composer require nextpdf/pro:^3

Gli encoder Pro si registrano da sé tramite il registry standard degli encoder di codici a barre. Le applicazioni che costruiscono il proprio registry possono registrare nuovamente gli encoder Pro esplicitamente tramite il service provider pubblicato.

Panoramica concettuale

L’edizione open source copre le simbologie lineari e QR di uso quotidiano. NextPDF Pro estende lo stesso registry con simbologie specializzate per la vendita al dettaglio, la logistica, la posta e l’uso industriale ad alta densità:

• Micro QR Code — la variante QR compatta per piccoli spazi di etichetta.
• DotCode — una simbologia a matrice di punti progettata per la marcatura industriale ad alta velocità.
• Han Xin Code — una simbologia 2D con capacità nativa di testo CJK a set ampio, secondo ISO/IEC 20830.
• JabCode — una simbologia 2D policroma con cascata multi-simbolo.
• rMQR — la variante Micro QR rettangolare per etichette strette e larghe.
• GS1 DataBar — la famiglia di simbologie GS1 per la vendita al dettaglio e i coupon.
• GS1 Composite (CC-C) — una base 1D collegata più un componente di estensione 2D PDF417 ad alta densità che trasporta dati GS1 Application Identifier. (La codifica del componente esteso 2D CC-A e CC-B non è supportata in questa release; vedere la matrice di supporto.)

Ogni encoder produce un oggetto dati del codice a barre che il renderer di pagina converte in operatori di contenuto PDF. La codifica è deterministica: lo stesso input e le stesse opzioni producono sempre lo stesso pattern di moduli, il che mantiene riproducibili i documenti firmati e archiviati.

Il riferimento approfondito ai codici a barre contiene una matrice di supporto per singola simbologia con evidenze. Per ogni simbologia e variante, la matrice registra uno di tre stati: una fixture di conformità nel repository la esercita (Verified), la superficie di implementazione la asserisce senza una fixture dedicata (Claimed), oppure ricade fuori ambito (Not supported). NextPDF riporta la matrice in modo onesto: una variante che distribuisce un encoder ma è priva di una fixture di reference-trace resta Claimed con una nota di backfill anziché essere sovrastimata.

Perché funziona così

Ogni encoder Pro è una funzione pura: lo stesso payload e le stesse opzioni producono sempre la stessa matrice di moduli, senza stato nascosto né casualità con seed. Quel determinismo è la decisione portante. Consente a un codice a barre di attraversare in round-trip un documento firmato o archiviato senza perturbare il byte stream, così un nuovo rendering non invalida mai una firma. Rende inoltre la conformità verificabile: la matrice di supporto ancora ogni simbologia a un reference trace memorizzato, controllato bit per bit rispetto a un golden file. Estendere il BarcodeEncoderRegistry di Core anziché forkarlo mantiene queste garanzie identiche tra l’edizione open e quella Pro.

Contesto di progettazione: The same bytes every time: reproducible PDFs.

Superficie API

composer require nextpdf/pro:^3

La superficie pubblica dei codici a barre Pro è composta da:

• Un punto di ingresso statico di service provider che registra gli encoder 2D Pro in un registry di encoder di codici a barre (MicroQR, DotCode, HanXin, JabCode, RMQR, GS1DataBar e la chiave del componente GS1 Composite CC-C gs1-composite-cc-c). La codifica del componente esteso 2D GS1 Composite CC-A e CC-B non è supportata in questa release e non è registrata.
• Un parser GS1 Application Identifier che accetta sia stringhe AI leggibili dall’uomo sia URI GS1 Digital Link e produce sequenze di byte codificate per i carrier GS1-128, QR Code e Data Matrix.
• Un validatore della catena di approvvigionamento GS1 che verifica le cifre di controllo, la struttura degli AI, la logica delle date e le combinazioni di AI obbligatori del profilo di settore.

La tabella completa generata delle firme di metodo viene renderizzata nel riferimento approfondito ai codici a barre.

Esempio di codice — Avvio rapido

use NextPDF\Barcode\BarcodeEncoderRegistry;
use NextPDF\Pro\Barcode\BarcodeProServiceProvider;

$registry = new BarcodeEncoderRegistry();
BarcodeProServiceProvider::register($registry);
// $registry now resolves the Pro specialty symbologies.

Esempio di codice — Produzione

use NextPDF\Pro\Barcode\Gs1\Gs1Validator;
use NextPDF\Pro\Barcode\Gs1\Gs1SupplyChainProfile;

$result = Gs1Validator::validate(
    '(01)09521234543213(17)260131(10)ABC123',
    Gs1SupplyChainProfile::NONE,
);

if (! $result->isValid) {
    // Surface findings to your observability pipeline before encoding.
    foreach ($result->findings as $finding) {
        $logger->warning('GS1 validation finding', [
            'rule' => $finding->ruleId,
            'detail' => $finding->message,
        ]);
    }
}

Casi limite e insidie

• Il registry predefinito pre-associa le voci dell’encoder Pro in modo pigro (lazy) e le gestisce tramite il registry delle capacità. Una chiamata esplicita BarcodeProServiceProvider::register() è il fallback supportato quando un’applicazione compone il proprio registry senza default.
• La ri-registrazione è idempotente: una seconda chiamata register() sostituisce la prima associazione anziché sollevare.
• La copertura delle varianti GS1 DataBar è parziale per progettazione. Omnidirectional, Truncated, Stacked, Stacked Omnidirectional e Limited sono verificate tramite riferimento; Expanded ed Expanded Stacked sono fuori ambito in questa release. Vedere la matrice di supporto.
• rMQR accetta ogni versione ISO 23941 tramite la suite di conformità validata dall’Annex. I metadati di tracciamento dell’ambito che precedono la successiva espansione dell’intervallo di dimensioni potrebbero sottostimare questo; la matrice di supporto registra la realtà verificata nel codice.

Prestazioni

Il costo di codifica scala con la lunghezza del payload e la dimensione del simbolo di destinazione. Ogni simbologia dispone il proprio simbolo in un singolo passaggio senza riflow. Le cascate multi-simbolo JabCode scalano con il conteggio dei simboli (1–61). La codifica mantiene la matrice dei moduli in memoria; la versione del simbolo più grande selezionata limita il costo.

Note di sicurezza

Gli encoder di codici a barre non eseguono il contenuto del payload; lo codificano come dati. La convalida GS1 rifiuta le strutture AI malformate e le cifre di controllo non valide prima della codifica, il che impedisce che una stringa di catena di approvvigionamento malformata produca un simbolo scansionabile ma non conforme. Gli encoder non registrano di per sé alcun payload; le applicazioni devono ripulire i payload sensibili dai propri log.

Conformità

Ogni simbologia segue il proprio standard pubblicato rilevante (ISO/IEC 24724 per GS1 DataBar, ISO/IEC 24723 per GS1 Composite, ISO/IEC 23941 per rMQR, ISO/IEC 18004 Annex per Micro QR, ISO/IEC 20830 per Han Xin Code, ISO/IEC 23634 per JabCode, USPS-B-3200 per la simbologia postale). La mappatura di conformità a livello di clausola con identificatori di citazione viene renderizzata nel riferimento approfondito ai codici a barre.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile esternamente e la superficie API pubblica supportata. Percorsi di namespace interni, classi helper, tabelle di meccanismi, nomi di file di runbook e prefissi di ticket sono fuori ambito.

Vedere anche

• Modulo barcode di Core
• Chart — NextPDF Pro
• Riferimento approfondito ai codici a barre