Générer des codes-barres 1D et 2D dans un PDF

En bref

Cette recette dessine des codes-barres 1D et 2D directement sur une page PDF. Le trait HasBarcodes du cœur expose write1DBarcode() et write2DBarcode(). Les deux dessinent le symbole avec des opérateurs de tracé PDF natifs sur la page courante, ce qui produit un contenu vectoriel simple et déterministe. La recette suit examples/10-barcodes.php.

Installation

composer require nextpdf/core:^3

Tu n’as besoin d’aucune extension supplémentaire. Les encodeurs de codes-barres sont en PHP pur, et les symboles sont dessinés avec l’opérateur de rectangle PDF standard (ISO 32000-2 §8.5).

Vue d’ensemble conceptuelle

Un code-barres est dessiné, et non intégré sous forme d’image. La charge utile correspond aux données que tu encodes, comme un numéro de produit ou une adresse Web.

write1DBarcode() encode la charge utile sous forme de motif bar/space pour le BarcodeType choisi, puis émet une séquence de rectangles remplis. write2DBarcode() construit une matrice de modules pour le Barcode2DType choisi et émet un rectangle rempli pour chaque module sombre. Data Matrix et QR Code utilisent la correction d’erreurs Reed-Solomon, ce qui permet à un scanner de récupérer les données même si une partie du symbole est endommagée.

Chaque module correspond à un tracé re … f déterministe, sans source d’entropie, ce qui rend le contenu du code-barres lui-même entièrement reproductible. Le profil de reproductibilité est structural, car le document environnant contient toujours des éléments propres à chaque enregistrement : le /ID du trailer et les horodatages /CreationDate et /ModDate. Le harnais compare la structure normalisée par qpdf une fois ces éléments retirés.

Surface de l’API

NextPDF\Core\Concerns\HasBarcodes (intégré dans 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

Une symbologie est un standard de code-barres qui définit comment les données sont transformées en barres ou en modules. BarcodeType liste les symbologies 1D (C128, EAN13, UPCA, I25, CODABAR, ISBN, GS1_128, …), et Barcode2DType liste les symbologies 2D (QRCode, DataMatrix, PDF417, HanXin, MicroQR, …).

Exemple de code — Démarrage rapide

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

Exemple de code — Production

L’exemple complet ci-dessous, que le harnais peut exécuter, reflète examples/10-barcodes.php. Il écrit le PDF vers le chemin fourni par le harnais via NEXTPDF_COOKBOOK_OUTPUT, et utilise un fichier local par défaut quand tu l’exécutes manuellement. Le harnais de reproductibilité peut alors l’exécuter deux fois et vérifier l’identité structurelle. La structure est normalisée par qpdf, une fois retirés les éléments /ID et d’horodatage propres à chaque enregistrement.

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

Sortie attendue :

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

Cas limites & pièges

La validité de la charge utile dépend de la symbologie. EAN13 attend 12 ou 13 chiffres. Une charge utile invalide déclenche une exception avant toute écriture de contenu. UPCA, ISBN et ISSN ont leurs propres règles de longueur et de chiffre de contrôle.
x/y sont optionnels. Si tu les omets, le code-barres est placé à la position courante du curseur. Passe des coordonnées explicites pour obtenir une mise en page prévisible.
w = 0 dimensionne automatiquement. Une largeur nulle laisse l’encodeur choisir une largeur de module naturelle. Passe une largeur positive pour tenir dans une boîte fixe.
Niveau de correction d’erreurs 2D. write2DBarcode() utilise par défaut ecLevel: 'L', le niveau le plus bas. Augmente-le ('M', 'Q', 'H') pour les QR Codes qui doivent résister aux dégradations d’impression. Les niveaux plus élevés agrandissent la matrice.
Identifiants d’application GS1. Passe gs1: true à write2DBarcode(), ou utilise BarcodeType::GS1_128, pour des données structurées GS1 avec le préfixe FNC1.
Une page est créée implicitement. Si tu appelles une méthode de code-barres avant addPage(), NextPDF ajoute d’abord une page. C’est pratique, mais appelle addPage() explicitement quand la géométrie de la page compte.

Performance

L’encodage est en O(longueur de la charge utile) pour le 1D et en O(surface de la matrice) pour le 2D ; dans les deux cas, l’ordre de grandeur est la microseconde. Chaque module correspond à un seul opérateur de tracé re … f, si bien qu’un QR Code dense ajoute quelques kilo-octets au flux de contenu. Il n’y a aucune étape de rasterisation, ce qui permet à la mémoire de rester constante quelle que soit la taille du symbole. La recette reste largement dans le budget de 1500 ms / 64 Mo.

Notes de sécurité

Un code-barres contient la charge utile que tu lui passes ; traite donc sa valeur comme n’importe quelle autre entrée non fiable côté consommateur. La bibliothèque ne signe ni n’authentifie la charge utile. Un symbole 2D n’est pas un chiffrement : toute personne munie d’un scanner peut le lire.

Conformité

Énoncé	Spécification	Clause
Les modules de code-barres sont dessinés avec l’opérateur de construction de tracé de rectangle.	ISO 32000-2	§8.5
Les caractères du symbole Code 128 utilisent la structure d’éléments bar/space définie.	ISO/IEC 15417	§4.3.1
Les symboles Data Matrix emploient la correction d’erreurs Reed-Solomon.	ISO/IEC 16022	§7.6.1
Les données du QR Code sont réparties en blocs de correction d’erreurs.	ISO/IEC 18004	§7.5.2

NextPDF implémente les encodages des symbologies citées, mais n’affirme aucune certification formelle vis-à-vis des standards de codes-barres. Les documents du corpus de symbologies de codes-barres sont plafonnés par licence au niveau Tier C. Les citations sont uniquement des pointeurs clause-id et reference_id, et aucun texte de standard n’est reproduit.