Code-barres : encodeurs de symbologies 1D et 2D

En bref

Le module Barcode constitue la couche d’implémentation des symbologies. Il encode les symbologies linéaires (Code 128, EAN, UPC, Interleaved 2 of 5, Codabar, codes postaux) ainsi que les symbologies matricielles (QR Code, Data Matrix, PDF417). Il calcule la correction d’erreur associée. Il enregistre chaque encodeur derrière les contrats de code-barres afin que le rédacteur de document puisse en dessiner le résultat. Les définitions des contrats sont documentées sur une page distincte. Voir la note ci-dessous.

Une page canonique par préoccupation. Les interfaces auxquelles un encodeur se conforme (Barcode1DEncoderInterface, Barcode2DEncoderInterface, BarcodeEncoderInterface, Gs1DataParserInterface) sont documentées sur Contrats / Barcode. Cette page documente les encodeurs concrets qui implémentent ces contrats. Les deux pages sont complémentaires, pas des doublons. Lis la page des contrats pour la SPI, et cette page pour les symbologies.

Installation

composer require nextpdf/core:^3

Aperçu conceptuel

Un encodeur de code-barres transforme une chaîne de charge utile en une matrice de modules (2D) ou en une séquence de barres (1D), que le rédacteur dessine sous forme de graphiques PDF. Ce module fournit les encodeurs concrets.

Barcode1D est le moteur linéaire. BarcodeType énumère les symbologies linéaires prises en charge — Code 39 (avec et sans somme de contrôle), Code 93, la famille Code 128, EAN-8/EAN-13, UPC-A/UPC-E, Interleaved et Standard 2 of 5, Codabar, Code 11, POSTNET, PLANET, Intelligent Mail (IMB) et MSI. generate() renvoie un objet-valeur BarcodeData décrivant le motif de barres.

Les encodeurs 2D — QrEncoder, DataMatrixEncoder, Pdf417Encoder — implémentent BarcodeEncoderInterface et renvoient une matrice Barcode2DData. Barcode2DType énumère les symbologies matricielles reconnues par le moteur, dont QR Code, Data Matrix et PDF417. D’autres symbologies, telles que Micro QR, rMQR, GS1 DataBar et Han Xin, sont énumérées pour le routage du registre. Le jeu d’encodeurs qui les prend en charge dépend de l’édition. La correction d’erreur matricielle est calculée sur un corps de Galois. GaloisField et GaloisFieldPrime fournissent l’arithmétique Reed-Solomon que partagent les encodeurs QR, Data Matrix et PDF417.

BarcodeEncoderRegistry est le mécanisme de résolution. Il implémente ContainerInterface PSR-11, fournit une configuration par défaut via createDefault() et résout une symbologie vers son encodeur avec resolve(). Le code applicatif accède rarement à un encodeur directement. La façade de haut niveau Document::write1DBarcode() / write2DBarcode() désigne une symbologie, et le registre fournit l’encodeur. Le moteur 1D est @since 1.0.0. Les encodeurs 2D sont @since 1.3.0. Le registre est @since 3.0.0.

Surface d’API

Classe	Membres clés	Rôle
Barcode1D	generate(string $code, BarcodeType $type): BarcodeData	Encodeur de symbologie linéaire (@since 1.0.0)
QrEncoder	encode(string $data, array $options = []): Barcode2DData	Encodeur QR Code (@since 1.3.0)
DataMatrixEncoder	encode(string $data, array $options = []): Barcode2DData	Encodeur Data Matrix (@since 1.3.0)
Pdf417Encoder	encode(string $data, array $options = []): Barcode2DData	Encodeur PDF417 (@since 1.3.0)
BarcodeEncoderRegistry	createDefault(), register(), resolve(), has(), get(), registered()	Registre d’encodeurs PSR-11 (@since 3.0.0)
BarcodeType / Barcode2DType	cas d’enum	Énumérations des symbologies prises en charge
GaloisField / GaloisFieldPrime	arithmétique en corps fini	correction d’erreur Reed-Solomon

Exécute composer docs:generate-api-php -- --module=Barcode pour la table PHPDoc complète.

Exemple de code — Démarrage rapide

Source : examples/10-barcodes.php. La façade résout un encodeur via le registre à partir de la symbologie.

<?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->addPage();

$doc->write1DBarcode('4006381333931', BarcodeType::EAN13, x: 15, y: null, w: 60, h: 20);
$doc->write2DBarcode('https://nextpdf.dev', Barcode2DType::QRCode, x: 15, y: 40, w: 40, h: 40);

$doc->save(__DIR__ . '/output/10-barcodes.pdf');

Exemple de code — Production

Résous un encodeur 2D directement via le registre et borne la charge utile avant l’encodage.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Barcode\Barcode2DType;
use NextPDF\Barcode\BarcodeEncoderRegistry;
use NextPDF\Exception\BarcodeException;
use Psr\Log\LoggerInterface;

final readonly class TrackingCodeService
{
    private const int MAX_PAYLOAD = 512;

    public function __construct(
        private BarcodeEncoderRegistry $registry,
        private LoggerInterface $logger,
    ) {}

    /** @return \NextPDF\Barcode\Barcode2DData */
    public function encode(string $trackingId): \NextPDF\Barcode\Barcode2DData
    {
        if (strlen($trackingId) > self::MAX_PAYLOAD) {
            throw new \LengthException('Tracking payload exceeds the encode bound.');
        }

        try {
            $encoder = $this->registry->resolve(Barcode2DType::QRCode->value);

            return $encoder->encode($trackingId, ['errorCorrection' => 'high']);
        } catch (BarcodeException $e) {
            $this->logger->error('Barcode encode failed', ['error' => $e->getMessage()]);

            throw $e;
        }
    }
}

Cas limites & pièges

• Une charge utile linéaire qui ne respecte pas le jeu de caractères ou la règle de chiffre de contrôle d’une symbologie lève BarcodeException. EAN/UPC calculent et ajoutent le chiffre de contrôle. Ne l’ajoute pas toi-même.
• Le tableau $options 2D est spécifique à la symbologie (par exemple, un niveau de correction d’erreur pour le QR). Les clés inconnues sont ignorées par la plupart des encodeurs. Vérifie la clé dans la documentation de l’encodeur concerné.
• Barcode2DType énumère plus de symbologies que l’édition core ne fournit d’encodeurs. BarcodeEncoderRegistry::resolve() lève pour une symbologie non enregistrée plutôt que de renvoyer un substitut.
• Les encodeurs enregistrés sont des instances partagées. Garde-les sans état au-delà de la configuration du constructeur. Un état propre à un appel corrompt les rendus concurrents.
• Une charge utile trop longue produit une matrice plus dense et plus grande. Borne la longueur de la charge utile avant l’encodage pour éviter un déni de service par la taille du symbole.

Performance

Le coût d’encodage évolue avec la longueur de la charge utile et la taille de la matrice, pas avec la résolution dans le registre, qui est en O(1). Une courte charge utile Code 128 s’encode en microsecondes. Un QR Code dense avec une correction d’erreur élevée est le cas le plus coûteux. Il reste dans le budget de 1500 ms de temps écoulé / 64 Mo de pic pour la page d’exemple multi-symboles. Le profil de reproductibilité est bitwise. La même charge utile et les mêmes options produisent toujours la même matrice de modules et les mêmes octets produits.

Notes de sécurité

Les charges utiles de code-barres sont fréquemment influencées par un attaquant — une URL scannée, un numéro de série, un code de suivi. Les encodeurs encodent des octets. Ils ne les interprètent pas. Un QR Code qui encode une URL hostile est un QR Code valide ; la confiance accordée à la charge utile relève donc de la responsabilité du consommateur. Borne la longueur de la charge utile avant l’encodage pour que la taille de la matrice — et donc le travail effectué et la taille de sortie — reste dans un budget. Traite toute donnée décodée ailleurs à partir d’un code-barres comme une entrée non fiable lorsqu’elle réintègre l’application. Consulte le modèle de menaces du moteur dans /modules/core/security/.

Conformité

Affirmation	Norme	Référence
Les symboles QR Code suivent la spécification de la symbologie matricielle QR Code.	ISO/IEC 18004	Symbologie QR Code
Les symboles Data Matrix suivent la spécification de la symbologie Data Matrix.	ISO/IEC 16022	Symbologie Data Matrix
Les symboles PDF417 suivent la spécification de la symbologie PDF417.	ISO/IEC 15438	Symbologie PDF417
Les symboles Code 128 suivent la spécification de la symbologie linéaire Code 128.	ISO/IEC 15417	Symbologie Code 128
Les symboles EAN/UPC suivent la spécification de la symbologie EAN/UPC.	ISO/IEC 15420	Symbologie EAN/UPC

Ces normes de symbologie ne sont pas présentes dans le corpus de citations vérifiables, donc aucun reference_id n’est enregistré. Le moteur paraphrase l’exigence et cite la source par numéro et clause. Consulte les normes publiées pour les règles d’encodage faisant autorité. Les encodeurs sont éprouvés par tests/Unit/Barcode/. La correction par rapport aux spécifications de symbologie est de la responsabilité de la suite de tests, pas une affirmation de conformité PDF de bout en bout.

Voir aussi

• Contrats / Barcode — les interfaces d’encodeur que ces classes implémentent (la SPI).
• Module Graphics — la couche de dessin qui peint la matrice encodée.
• Module Document — la façade de haut niveau write1DBarcode() / write2DBarcode().
• Vue d’ensemble de la conformité
• Modèle de sécurité du moteur