Pro édition

Code-barres

En bref

NextPDF Pro ajoute des symbologies de codes-barres spécialisées 2D et de chaîne d’approvisionnement par-dessus les symbologies linéaires et QR de l’édition open source. Chaque symbologie se rend directement dans une surface de page PDF sous la forme d’un flux de contenu déterministe.

Disponibilité et licence

Cette capacité est livrée dans NextPDF Pro (nextpdf/pro) et s’active avec une enveloppe de licence de niveau Pro. Un déploiement sans ce droit ne charge pas les classes de la capacité. Compare les éditions et obtiens une licence.

Installation

composer require nextpdf/pro:^3

Les encodeurs Pro s’enregistrent eux-mêmes via le registre standard d’encodeurs de codes-barres. Les applications qui construisent leur propre registre peuvent réenregistrer les encodeurs Pro explicitement via le fournisseur de service publié.

Vue d’ensemble conceptuelle

L’édition open source couvre les symbologies linéaires et QR du quotidien. NextPDF Pro étend le même registre avec des symbologies spécialisées pour la vente au détail, la logistique, le postal et l’usage industriel à haute densité :

Micro QR Code — la variante QR compacte pour le faible espace des petites étiquettes.
DotCode — une symbologie matricielle à points conçue pour le marquage industriel à haute vitesse.
Han Xin Code — une symbologie 2D dotée d’une capacité native de texte CJK à grand jeu, conformément à ISO/IEC 20830.
JabCode — une symbologie 2D polychrome avec cascade multi-symboles.
rMQR — la variante Micro QR rectangulaire pour les étiquettes étroites et larges.
GS1 DataBar — la famille de symbologies GS1 pour la vente au détail et les coupons.
GS1 Composite (CC-C) — une base 1D liée plus un composant d’extension 2D PDF417 à haute densité portant des données d’identifiant d’application (AI) GS1. (L’encodage des composants étendus 2D CC-A et CC-B n’est pas pris en charge dans cette version ; voir la matrice de prise en charge.)

Chaque encodeur produit un objet de données de code-barres que le moteur de rendu de page convertit en opérateurs de contenu PDF. L’encodage est déterministe : les mêmes entrée et options produisent toujours le même motif de modules, ce qui maintient reproductibles les documents signés et archivés.

La référence approfondie des codes-barres porte une matrice de prise en charge par symbologie avec preuves. Pour chaque symbologie et variante, la matrice enregistre l’un de trois états : une fixture de conformité présente dans le dépôt l’exerce (Verified), la surface d’implémentation l’affirme sans fixture dédiée (Claimed), ou elle sort du périmètre (Not supported). NextPDF rapporte la matrice honnêtement : une variante qui livre un encodeur mais à laquelle manque une fixture de trace de référence reste Claimed avec une note de complément (backfill) plutôt que survendue.

Pourquoi ça fonctionne ainsi

Chaque encodeur Pro est une fonction pure : les mêmes charge utile et options produisent toujours la même matrice de modules, sans état caché ni aléa initialisé par graine. Ce déterminisme est la décision porteuse. Il permet à un code-barres de faire l’aller-retour dans un document signé ou archivé sans perturber le flux d’octets, de sorte qu’un nouveau rendu n’invalide jamais une signature. Il rend aussi la conformité auditable : la matrice de prise en charge épingle chaque symbologie à une trace de référence stockée, vérifiée bit à bit face à un fichier de référence (golden file). Étendre le BarcodeEncoderRegistry du Core plutôt que d’en créer un fork maintient ces garanties identiques entre l’édition open et l’édition Pro.

Contexte de conception : Les mêmes octets à chaque fois : des PDF reproductibles.

Surface d’API

composer require nextpdf/pro:^3

La surface publique de codes-barres Pro se compose de :

Un point d’entrée statique de fournisseur de service qui enregistre les encodeurs 2D Pro dans un registre d’encodeurs de codes-barres (MicroQR, DotCode, HanXin, JabCode, RMQR, GS1DataBar et la clé de composant GS1 Composite CC-C gs1-composite-cc-c). L’encodage des composants étendus 2D GS1 Composite CC-A et CC-B n’est pas pris en charge dans cette version et n’est pas enregistré.
Un analyseur d’identifiants d’application (AI) GS1 qui accepte à la fois les chaînes AI lisibles par un humain et les URI GS1 Digital Link, et produit des séquences d’octets encodées pour les porteurs GS1-128, QR Code et Data Matrix.
Un validateur de chaîne d’approvisionnement GS1 qui vérifie les chiffres de contrôle, la structure des AI, la logique des dates et les combinaisons d’AI obligatoires par profil industriel.

Le tableau complet des signatures de méthodes généré se rend dans la référence approfondie des codes-barres.

Exemple de code — Démarrage rapide

use NextPDF\Barcode\BarcodeEncoderRegistry;
use NextPDF\Pro\Barcode\BarcodeProServiceProvider;

$registry = new BarcodeEncoderRegistry();
BarcodeProServiceProvider::register($registry);
// $registry now resolves the Pro specialty symbologies.

Exemple de code — Production

use NextPDF\Pro\Barcode\Gs1\Gs1Validator;
use NextPDF\Pro\Barcode\Gs1\Gs1SupplyChainProfile;

$result = Gs1Validator::validate(
    '(01)09521234543213(17)260131(10)ABC123',
    Gs1SupplyChainProfile::NONE,
);

if (! $result->isValid) {
    // Surface findings to your observability pipeline before encoding.
    foreach ($result->findings as $finding) {
        $logger->warning('GS1 validation finding', [
            'rule' => $finding->ruleId,
            'detail' => $finding->message,
        ]);
    }
}

Cas limites & pièges

Le registre par défaut pré-lie paresseusement les entrées d’encodeurs Pro et les verrouille via le registre de capacités. Un appel explicite à BarcodeProServiceProvider::register() est le repli pris en charge lorsqu’une application compose son propre registre sans valeurs par défaut.
Le réenregistrement est idempotent : un second appel à register() remplace la première liaison plutôt que de lever une exception.
La couverture des variantes de GS1 DataBar est partielle par conception. Omnidirectional, Truncated, Stacked, Stacked Omnidirectional et Limited sont vérifiées par référence ; Expanded et Expanded Stacked sont hors du périmètre dans cette version. Voir la matrice de prise en charge.
rMQR accepte chaque version ISO 23941 via la suite de conformité validée par annexe. Les métadonnées de suivi de périmètre antérieures à l’extension ultérieure de la plage de tailles peuvent sous-estimer cela ; la matrice de prise en charge enregistre la réalité vérifiée dans le code.

Performance

Le coût d’encodage évolue avec la longueur de la charge utile et la taille du symbole cible. Chaque symbologie dispose son symbole en une seule passe sans recomposition. Les cascades multi-symboles de JabCode évoluent avec le nombre de symboles (1–61). L’encodage maintient la matrice de modules en mémoire ; la plus grande version de symbole sélectionnée borne le coût.

Notes de sécurité

Les encodeurs de codes-barres n’exécutent pas le contenu de la charge utile ; ils l’encodent comme des données. La validation GS1 rejette les structures d’AI malformées et les chiffres de contrôle invalides avant l’encodage, ce qui empêche une chaîne de chaîne d’approvisionnement malformée de produire un symbole scannable mais non conforme. Les encodeurs ne journalisent eux-mêmes aucune charge utile ; les applications doivent caviarder les charges utiles sensibles de leurs propres journaux.

Conformité

Chaque symbologie suit sa norme publiée pertinente (ISO/IEC 24724 pour GS1 DataBar, ISO/IEC 24723 pour GS1 Composite, ISO/IEC 23941 pour rMQR, ISO/IEC 18004 Annex pour Micro QR, ISO/IEC 20830 pour Han Xin Code, ISO/IEC 23634 pour JabCode, USPS-B-3200 pour la symbologie postale). La correspondance de conformité au niveau des clauses avec les identifiants de citation se rend dans la référence approfondie des codes-barres.

Périmètre de publication

Cette page documente uniquement le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins d’espaces de noms internes, les classes utilitaires, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de tickets sortent du périmètre.