Contrats / Code-barres

En un coup d’œil

Le domaine des codes-barres regroupe quatre contrats : un encodeur 1D, un encodeur 2D, un encodeur générique découvrable via le registre et un parseur de données GS1. Ils définissent la forme qu’un encodeur doit respecter. Les implémentations de symbologies s’enregistrent en s’appuyant sur ces contrats.

Installation

composer require nextpdf/core:^3

Vue d’ensemble conceptuelle

Un encodeur de code-barres transforme une charge utile (chaîne de caractères) en une matrice de modules que le moteur d’écriture PDF peint. NextPDF sépare les contrats selon la dimension. Barcode1DEncoderInterface encode les symbologies linéaires — Code 128, EAN-13 et similaires — et renvoie un objet valeur BarcodeData. Barcode2DEncoderInterface encode les symbologies matricielles — QR Code, Data Matrix. Il renvoie un objet valeur Barcode2DData avec un tableau d’options pour les paramètres propres à chaque symbologie, comme le niveau de correction d’erreur.

BarcodeEncoderInterface est le contrat générique de fournisseur de service. Tout encodeur 2D découvrable via BarcodeEncoderRegistry l’implémente. Il renvoie soit une matrice monochrome Barcode2DData, soit une matrice couleur BarcodeColorData, ce qui permet à un encodeur enregistré de produire un symbole couleur sans interface distincte. Les encodeurs doivent rester sans état au-delà de la configuration fixée à la construction. Le registre fournit une seule instance partagée par type enregistré ; tout état propre à un appel constituerait donc un défaut.

Gs1DataParserInterface est le contrat de données structurées. Il analyse une chaîne d’éléments GS1 vers un objet typé, puis ré-encode cet objet pour une cible QR Code, Data Matrix ou Code 128. Cela sépare la grammaire GS1 de la symbologie. Le parseur valide les Application Identifiers une seule fois. Les méthodes propres à chaque support mettent en forme la même structure analysée pour chaque cible. Les quatre contrats ont la stabilité stable. BarcodeEncoderInterface est stable depuis la version 3.0.0 ; les autres depuis la version 1.0.0. Toute nouvelle méthode n’est ajoutée qu’avec des implémentations par défaut.

Surface de l’API

Type	Nature	Membres clés	Stabilité	Depuis
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

Le tableau $options des contrats 2D est propre à chaque symbologie (par exemple, un niveau de correction d’erreur pour QR Code). Le contrat n’impose aucune contrainte sur ses clés. Chaque encodeur enregistré documente son propre jeu d’options.

Exemple de code — Démarrage rapide

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() et write2DBarcode() résolvent un encodeur via le registre. Le code applicatif manipule rarement les contrats directement. Il nomme une symbologie ; le registre fournit l’encodeur.

Exemple de code — Production

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

Le service dépend des contrats de parseur et d’encodeur. Le bloc catch journalise l’erreur et relance la BarcodeException spécifique, jamais une \Exception brute.

Cas limites et pièges

• Un encodeur enregistré est partagé. Stocker dans un encodeur un état propre à un appel corrompt les rendus concurrents. Garde les encodeurs sans état au-delà de la configuration du constructeur.
• BarcodeEncoderInterface::encode() peut renvoyer des données couleur ou monochromes. Le code consommateur doit gérer à la fois Barcode2DData et BarcodeColorData, sans présumer qu’elles sont monochromes.
• Le tableau $options 2D n’est pas validé par le contrat. Une clé inconnue est ignorée silencieusement par la plupart des encodeurs. Vérifie le nom de la clé dans la documentation propre à l’encodeur.
• L’analyse GS1 applique strictement la grammaire. Une chaîne d’éléments comportant un Application Identifier inconnu lève une BarcodeException plutôt que de produire une analyse partielle. Valide l’entrée en amont.
• Les contrats 1D et 2D ne sont pas interchangeables. Une charge utile QR passée à un encodeur 1D produit un symbole invalide. Le registre route selon le type de symbologie ; préfère donc le registre à un appel direct du contrat.

Performance

Le coût d’encodage augmente avec la longueur de la charge utile et la taille de la matrice cible, pas avec le contrat. Une courte charge utile Code 128 s’encode en microsecondes. Un QR Code dense avec une correction d’erreur élevée est le cas 2D le plus lourd. Il reste largement dans le performance_budget de 1500 ms de temps réel et 64 Mo de pic mémoire pour la page d’exemple multi-symboles. La matrice est calculée une seule fois, puis peinte sous forme d’opérateurs PDF. La reproductibilité est bitwise car la même charge utile et les mêmes options donnent toujours la même matrice de modules. La recherche dans le registre s’effectue en O(1). La charge de travail vient de l’algorithme de symbologie.

Notes de sécurité

Les charges utiles de codes-barres sont fréquemment influencées par un attaquant — une URL scannée, un numéro de série, un code de suivi. Les contrats encodent des octets. Ils ne les interprètent pas. Un QR Code qui encode une URL hostile reste un QR Code valide ; la confiance accordée à la charge utile relève donc du consommateur, pas de l’encodeur. Limite la longueur de la charge utile avant l’encodage pour borner la taille de la matrice et éviter un déni de service par un symbole surdimensionné. Le parseur GS1 rejette les Application Identifiers malformés, ce qui supprime une surface d’injection. Il ne vérifie pas le contenu sémantique des champs valides. Traite les données de code-barres décodées comme une entrée non fiable partout où elles réentrent dans l’application.

Conformité

Affirmation	Norme	Référence
Les symboles QR Code suivent la spécification de symbologie matricielle QR Code.	ISO/IEC 18004	Symbologie QR Code
Les symboles Data Matrix suivent la spécification de symbologie Data Matrix.	ISO/IEC 16022	Symbologie Data Matrix
Les symboles Code 128 suivent la spécification de symbologie linéaire Code 128.	ISO/IEC 15417	Symbologie Code 128
Les chaînes d’éléments GS1 sont analysées selon la grammaire des Application Identifiers GS1.	GS1 General Specifications	Application Identifiers

Ces normes sont référencées par numéro et par clause. Elles ne sont pas présentes dans le corpus de citations vérifiables ; aucun reference_id n’est donc enregistré. Le moteur paraphrase l’exigence et cite la source. Consulte les normes publiées pour connaître les règles d’encodage faisant autorité.

Contexte commercial

Core définit et fige les contrats d’encodeur et fournit les symbologies courantes. Les éditions Pro et Enterprise enregistrent un jeu étendu d’encodeurs pour des symbologies de codes-barres supplémentaires via le même BarcodeEncoderInterface, de sorte qu’un déploiement commercial gagne en couverture de symbologies sans changement d’API. Core résout les encodeurs enregistrés via BarcodeEncoderRegistry. La surface du contrat est identique d’une édition à l’autre.

Voir aussi

• Contrats : 41 interfaces publiques (SPI) — la vue d’ensemble de la SPI et les niveaux de stabilité.
• Code-barres — les implémentations de symbologies enregistrées pour ces contrats.
• Contrats / Document — PdfDocumentInterface qui peint la matrice encodée.
• Graphismes — la couche de dessin qui rend les modules du code-barres.
• Exception — BarcodeException levée en cas d’entrée GS1 malformée.