Contratti / Codice a barre

In breve

Il dominio dei codici a barre comprende quattro contratti: un encoder 1D, un encoder 2D, un encoder generico individuabile tramite registry e un parser di dati GS1. Definiscono la forma che un encoder deve rispettare. Le implementazioni delle simbologie vengono registrate su questi contratti.

Installazione

composer require nextpdf/core:^3

Panoramica concettuale

Un encoder di codici a barre trasforma una stringa di payload in una matrice di moduli che il writer PDF disegna. NextPDF suddivide il contratto in base alla dimensionalità. Barcode1DEncoderInterface codifica le simbologie lineari — Code 128, EAN-13 e simili — e restituisce un value object BarcodeData. Barcode2DEncoderInterface codifica le simbologie a matrice — QR Code e Data Matrix. Restituisce un value object Barcode2DData con una mappa di opzioni per i parametri specifici della simbologia, come il livello di correzione degli errori.

BarcodeEncoderInterface è il contratto service-provider generico. Lo implementa qualsiasi encoder 2D individuabile tramite BarcodeEncoderRegistry. Il contratto restituisce una matrice Barcode2DData monocromatica oppure una matrice a colori BarcodeColorData, consentendo a un encoder registrato di produrre un simbolo colorato senza un’interfaccia separata. Si presuppone che gli encoder siano privi di stato, fatta eccezione per la configurazione applicata al momento della costruzione. Il registry fornisce un’unica istanza condivisa per ogni tipo registrato, quindi qualsiasi stato per singola chiamata costituirebbe un difetto.

Gs1DataParserInterface è il contratto per i dati strutturati. Analizza una stringa di elementi GS1 in un oggetto tipizzato, quindi ricodifica tale oggetto per un supporto QR Code, Data Matrix o Code 128. In questo modo la grammatica GS1 resta separata dalla simbologia. Il parser convalida gli Application Identifier una sola volta. I metodi specifici per ciascun supporto formattano la stessa struttura analizzata per ogni target. I quattro contratti sono stable. BarcodeEncoderInterface è stable dalla versione 3.0.0; gli altri dalla 1.0.0. I nuovi metodi vengono introdotti soltanto con implementazioni predefinite.

Superficie API

Tipo	Genere	Membri principali	Stabilità	Da
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

L’array $options nei contratti 2D è specifico della simbologia (ad esempio, un livello di correzione degli errori per QR Code). Il contratto non ne vincola le chiavi. Ogni encoder registrato documenta il proprio set di opzioni.

Esempio di codice — Avvio rapido

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() e write2DBarcode() risolvono un encoder tramite il registry. Il codice applicativo accede raramente ai contratti in modo diretto. Specificare una simbologia e lasciare che il registry fornisca l’encoder.

Esempio di codice — Produzione

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

Il servizio dipende dai contratti del parser e dell’encoder. Il blocco catch registra e rilancia la specifica BarcodeException, mai una \Exception generica.

Casi limite e insidie

• Un encoder registrato è condiviso. Memorizzare su un encoder uno stato per singola chiamata compromette i rendering concorrenti. Mantenere gli encoder privi di stato, fatta eccezione per la configurazione del costruttore.
• BarcodeEncoderInterface::encode() può restituire dati a colori o monocromatici. Il codice chiamante deve gestire sia Barcode2DData sia BarcodeColorData, senza presumere che siano monocromatici.
• L’array $options 2D non viene convalidato dal contratto. Una chiave sconosciuta viene ignorata in modo silenzioso dalla maggior parte degli encoder. Verificare il nome della chiave rispetto alla documentazione dell’encoder stesso.
• L’analisi GS1 applica una grammatica rigorosa. Una stringa di elementi con un Application Identifier sconosciuto solleva una BarcodeException anziché produrre un’analisi parziale. Convalidare l’input a monte.
• I contratti 1D e 2D non sono intercambiabili. Un payload QR passato a un encoder 1D produce un simbolo non valido. Il registry instrada in base al tipo di simbologia, quindi è preferibile usare il registry invece di chiamare direttamente il contratto.

Prestazioni

Il costo della codifica varia in funzione della lunghezza del payload e della dimensione della matrice di destinazione, non del contratto. Un payload Code 128 breve viene codificato in microsecondi. Un QR Code denso con correzione degli errori elevata è il caso 2D più impegnativo. Rientra comunque ampiamente nel performance_budget di 1500 ms di tempo reale e 64 MB di picco per la pagina di esempio con più simboli. La matrice viene calcolata una sola volta e disegnata come operatori PDF. La riproducibilità è bitwise perché lo stesso payload e le stesse opzioni producono sempre la stessa matrice di moduli. La ricerca nel registry è O(1). Il carico di lavoro è costituito dall’algoritmo della simbologia.

Note sulla sicurezza

I payload dei codici a barre sono spesso influenzati da utenti malintenzionati: un URL scansionato, un numero di serie, un codice di tracciamento. I contratti codificano byte. Non li interpretano. Un QR Code che codifica un URL ostile è un QR Code valido, quindi l’attendibilità del payload è responsabilità del consumatore, non dell’encoder. Limitare la lunghezza del payload prima della codifica per circoscrivere la dimensione della matrice ed evitare un denial-of-service tramite un simbolo sovradimensionato. Il parser GS1 rifiuta gli Application Identifier malformati, eliminando una superficie di injection. Non verifica il contenuto semantico dei campi validi. Trattare i dati del codice a barre decodificati come input non attendibile ovunque rientrino nell’applicazione.

Conformità

Dichiarazione	Standard	Riferimento
I simboli QR Code seguono la specifica della simbologia a matrice QR Code.	ISO/IEC 18004	Simbologia QR Code
I simboli Data Matrix seguono la specifica della simbologia Data Matrix.	ISO/IEC 16022	Simbologia Data Matrix
I simboli Code 128 seguono la specifica della simbologia lineare Code 128.	ISO/IEC 15417	Simbologia Code 128
Le stringhe di elementi GS1 vengono analizzate secondo la grammatica degli Application Identifier GS1.	GS1 General Specifications	Application Identifier

Questi standard sono citati per numero e clausola. Non sono presenti nel corpus di citazioni verificabili, quindi non viene registrato alcun reference_id. Il motore parafrasa il requisito e cita la fonte. Per le regole di codifica autorevoli, consultare gli standard pubblicati.

Contesto commerciale

Core definisce e congela i contratti degli encoder e include le simbologie comuni. Le edizioni Pro ed Enterprise registrano un set esteso di encoder per simbologie di codici a barre aggiuntive a fronte della stessa BarcodeEncoderInterface, consentendo a un deployment commerciale di ottenere una copertura di simbologie più ampia senza modifiche all’API. Core risolve gli encoder registrati tramite BarcodeEncoderRegistry. La superficie del contratto è identica in tutte le edizioni.

Vedere anche

• Contracts: 41 interfacce pubbliche (SPI) — panoramica dell’SPI e livelli di stabilità.
• Barcode — implementazioni delle simbologie registrate a fronte di questi contratti.
• Contracts / Document — PdfDocumentInterface che disegna la matrice codificata.
• Graphics — il livello di disegno che esegue il rendering dei moduli del codice a barre.
• Exception — BarcodeException sollevata in caso di input GS1 malformato.