Generare codici a barre 1D e 2D in un PDF

In breve

Questa ricetta mostra come disegnare codici a barre 1D e 2D direttamente su una pagina PDF. Il trait Core HasBarcodes mette a disposizione write1DBarcode() e write2DBarcode(). Entrambi disegnano il simbolo come operatori nativi di tracciato PDF sulla pagina corrente, quindi l’output è contenuto vettoriale semplice e deterministico. La ricetta segue examples/10-barcodes.php.

Installazione

composer require nextpdf/core:^3

Non è necessaria alcuna estensione aggiuntiva. Gli encoder dei codici a barre sono scritti in puro PHP e i simboli vengono disegnati con l’operatore PDF standard per i rettangoli (ISO 32000-2 §8.5).

Panoramica concettuale

Un codice a barre viene disegnato, non incorporato come immagine. Il payload è il dato da codificare, ad esempio un numero di prodotto o un indirizzo web.

write1DBarcode() codifica il payload in un pattern bar/space per il BarcodeType scelto, quindi emette una sequenza di rettangoli riempiti. write2DBarcode() costruisce una matrice di moduli per il Barcode2DType scelto ed emette un rettangolo riempito per ogni modulo scuro. Data Matrix e QR Code usano la correzione degli errori Reed-Solomon, quindi uno scanner può recuperare i dati anche se una parte del simbolo è danneggiata.

Ogni modulo è un tracciato deterministico re … f senza alcuna sorgente di entropia, quindi il contenuto stesso del codice a barre è pienamente riproducibile. Il profilo di riproducibilità è structural perché il documento circostante contiene ancora atomi legati al salvataggio: il /ID del trailer e i timestamp /CreationDate e /ModDate. L’harness confronta la struttura normalizzata da qpdf dopo la rimozione di tali atomi.

Superficie dell’API

NextPDF\Core\Concerns\HasBarcodes (integrato in 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

Per simbologia si intende uno standard di codici a barre che definisce come i dati vengono trasformati in barre o moduli. BarcodeType elenca le simbologie 1D (C128, EAN13, UPCA, I25, CODABAR, ISBN, GS1_128, …) e Barcode2DType elenca le simbologie 2D (QRCode, DataMatrix, PDF417, HanXin, MicroQR, …).

Esempio di codice — Avvio rapido

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

Esempio di codice — Produzione

L’esempio completo eseguibile dall’harness riportato di seguito rispecchia examples/10-barcodes.php. Scrive il PDF nel percorso fornito dall’harness tramite NEXTPDF_COOKBOOK_OUTPUT e usa un file locale quando viene eseguito manualmente. L’harness di riproducibilità può quindi eseguirlo due volte e verificare l’identità strutturale. La struttura viene normalizzata da qpdf, con la rimozione degli atomi di salvataggio /ID e dei timestamp.

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

Output previsto:

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

Casi limite e insidie

La validità del payload è specifica della simbologia. EAN13 prevede 12 o 13 cifre. Un payload non valido genera un’eccezione prima che venga scritto qualsiasi contenuto. UPCA, ISBN e ISSN hanno regole proprie per lunghezza e cifra di controllo.
x/y sono facoltativi. Quando si omettono, il codice a barre viene posizionato in corrispondenza della posizione corrente del cursore. Passare coordinate esplicite per un layout prevedibile.
w = 0 dimensiona automaticamente. Una larghezza pari a zero consente all’encoder di scegliere una larghezza di modulo naturale. Passare una larghezza positiva per adattare il codice a barre a un riquadro fisso.
Livello di correzione degli errori 2D. write2DBarcode() usa per impostazione predefinita ecLevel: 'L', il livello più basso. Aumentarlo ('M', 'Q', 'H') per i QR Code che devono resistere ai danni di stampa. I livelli più alti ingrandiscono la matrice.
Identificatori applicativi GS1. Passare gs1: true a write2DBarcode(), oppure usare BarcodeType::GS1_128, per dati strutturati GS1 con il prefisso FNC1.
Una pagina viene creata implicitamente. Quando si chiama un metodo per i codici a barre prima di addPage(), NextPDF aggiunge prima una pagina. È comodo, ma conviene chiamare addPage() in modo esplicito quando la geometria della pagina è rilevante.

Prestazioni

La codifica è O(lunghezza del payload) per i 1D e O(area della matrice) per i 2D, ed entrambe sono dell’ordine dei microsecondi. Ogni modulo è un singolo operatore di tracciato re … f, quindi un QR Code denso aggiunge pochi kilobyte al flusso di contenuto. Non è prevista alcuna fase di rasterizzazione, quindi la memoria rimane costante indipendentemente dalle dimensioni del simbolo. La ricetta resta ampiamente entro il budget di 1500 ms / 64 MB.

Note sulla sicurezza

Un codice a barre trasporta qualsiasi payload venga passato, quindi è bene trattare un valore di codice a barre come qualsiasi altro input non attendibile sul lato di consumo. La libreria non firma né autentica il payload. Un simbolo 2D non è una forma di cifratura: chiunque disponga di uno scanner può leggerlo.

Conformità

Dichiarazione	Specifica	Clausola
I moduli dei codici a barre vengono disegnati con l’operatore di costruzione del tracciato del rettangolo.	ISO 32000-2	§8.5
I caratteri simbolo Code 128 usano la struttura definita degli elementi bar/space.	ISO/IEC 15417	§4.3.1
I simboli Data Matrix impiegano la correzione degli errori Reed-Solomon.	ISO/IEC 16022	§7.6.1
I dati del QR Code vengono suddivisi in blocchi di correzione degli errori.	ISO/IEC 18004	§7.5.2

NextPDF implementa le codifiche delle simbologie citate, ma non dichiara alcuna certificazione formale rispetto agli standard dei codici a barre. I documenti del corpus delle simbologie dei codici a barre sono limitati dalla licenza al Tier C. Le citazioni sono solo puntatori clause-id e reference_id e non viene riprodotto alcun testo degli standard.