Codes-barres — référence approfondie

En bref

La surface codes-barres de NextPDF Pro ajoute des symbologies 2D spécialisées et de chaîne logistique par-dessus le module barcode de Core. Elle fournit six encodeurs 2D résolus par le registre (Micro QR, DotCode, Han Xin Code, JabCode, rMQR, GS1 DataBar), un encodeur de composant 2D GS1 Composite (CC-C), l’encodeur 1D USPS Intelligent Mail, ainsi qu’un analyseur d’Application Identifier GS1 et un validateur de chaîne logistique. L’encodage est déterministe : la même charge utile et les mêmes options produisent toujours une matrice de modules identique. Cette page énonce l’API publique, le contrat de comportement, les modes de défaillance et les preuves de conformité par symbologie.

Disponibilité et licence

Cette capacité est fournie dans NextPDF Pro (nextpdf/pro) et s’active avec une enveloppe de licence de niveau Pro. Un déploiement dépourvu de ce droit ne charge pas les classes de la capacité. Comparer les éditions et obtenir une licence.

composer require nextpdf/pro:^3

Chaque symbologie lie son propre nom de capacité dans l’enveloppe de licence : barcode.microqr, barcode.dotcode, barcode.hanxin, barcode.jabcode, barcode.rmqr, barcode.gs1databar et barcode.gs1-composite-cc-c. Lorsqu’une capacité n’est pas sous licence, le registre ne résout pas cet encodeur. L’encodage de symbole complet GS1 Composite CC-A et CC-B n’est pas pris en charge (voir le tableau d’état de prise en charge) ; aucune clé barcode.gs1-composite-cc-a ni barcode.gs1-composite-cc-b n’est donc enregistrée.

Surface d’API publique

Les clés du registre proviennent des valeurs de cas NextPDF\Barcode\Barcode2DType de Core, plus la clé littérale gs1-composite-cc-c. Pour les encodeurs résolus par le registre, la clé du registre est le contrat stable, et non le FQCN de l’encodeur.

Symbole	Paramètres	Comportement par défaut	Retourne	Lève ou échoue avec	Notes
BarcodeProServiceProvider::register()	BarcodeEncoderRegistry $registry	Lie les sept clés de registre Pro	void	—	Statique ; idempotent — un second appel remplace la première liaison
MicroQrEncoder::encode()	$data ; options ecLevel ('L', 'M', 'Q' ; défaut 'L'), version (1–4 ou null), mask (0–3 ou null)	Sélectionne automatiquement la plus petite version adaptée M1–M4	Barcode2DData	InvalidArgumentException	Le 'H' non pris en charge est SILENCIEUSEMENT ramené à 'L' (les appelants exigeant une sélection EC fail-closed doivent prévalider) ; M1 ignore ecLevel
DotCodeEncoder::encode()	$data ; options gs1 (bool, défaut false), columns (int), rows (int), ratio (float, défaut 1.5)	Dimensionnement automatique de la grille au ratio largeur:hauteur 1.5	Barcode2DData	InvalidArgumentException	Les dimensions de la grille peuvent être forcées par axe
HanXinEncoder::encode()	$data ; options ecLevel (0–3, défaut 1), version (1–84, défaut auto)	Plus petite version adaptée	Barcode2DData	InvalidArgumentException	Modes texte GB 2312 Région 1/2 selon ISO/IEC 20830
JabCodeEncoder::encode()	$data ; options colors (4, 8, 16, 32, 64, 128, 256 ; défaut 8), eccLevel (0–10, défaut 3), symbolNumber (1–61, défaut 1), symbolVersions, symbolPositions, symbolEccLevels	Symbole unique à 8 couleurs	BarcodeColorData	InvalidArgumentException, JabCodeEncodingException	Matrice de modules polychrome avec palette
RmqrEncoder::encode()	$data ; options ecLevel (RmqrConstants::EC_M défaut, ou EC_H), version (p. ex. 'R7x43', défaut auto)	Plus petite des 32 versions ISO/IEC 23941 adaptée	Barcode2DData	InvalidArgumentException	Rejette les charges utiles dépassant la capacité ; ne tronque jamais
Gs1DataBarEncoder::encode()	$data ; options variant (Gs1DataBarVariant, défaut OMNIDIRECTIONAL), linkage (bool, défaut false), height (int, défaut minimum du variant ; par rangée pour Expanded Stacked), segmentsPerRow (int, défaut 4 ; Expanded Stacked uniquement)	Encode une entrée GTIN (famille §5/§6) ou une chaîne d’éléments AI GS1 (famille §7)	Barcode2DData	InvalidArgumentException ; InvalidSymbolStructureException	Les sept variants ISO/IEC 24724 Annexe J s’encodent
Gs1DataBarVariant	—	isImplemented() retourne true pour les sept cas	enum (7 cas)	—	minimumHeightX() et defaultHeightX() selon l’Annexe J
ImbEncoder::encode()	string $code (20, 25, 29 ou 31 chiffres)	65 barres à quatre états	BarcodeData	InvalidArgumentException	Interface d’encodeur 1D ; pas une clé de registre 2D
ImbEncoder::encodeToString()	string $code	États des barres sous forme de chaîne T/A/D/F	string	InvalidArgumentException	Pour la vérification contre les vecteurs de référence USPS
Gs1DataParser::parse()	string $data	Détecte automatiquement les URI Digital Link, sinon le format (AI)value	Gs1ParsedData	InvalidArgumentException	Implémente le contrat Gs1DataParserInterface de Core
Gs1DataParser::parseDigitalLink()	string $uri	Analyse une URI GS1 Digital Link	Gs1ParsedData	InvalidArgumentException	—
Gs1DataParser::encodeForCode128() / ::encodeForQrCode() / ::encodeForDataMatrix()	object $parsed	Séquence d’octets de porteur avec la convention FNC1 de ce porteur	string	—	Attend une instance Gs1ParsedData
Gs1DataParser::validateAI()	string $ai, string $value	Contrôle structurel d’une valeur d’AI	bool	—	—
Gs1Validator::validate()	string $barcodeData, Gs1SupplyChainProfile $profile (défaut NONE)	Chemin rapide statique par-dessus run()	Gs1ValidationResult	—	Les échecs d’analyse deviennent des constats, pas des exceptions
Gs1Validator::run()	comme validate()	Analyse, chiffres de contrôle, dates, règles inter-AI, profil	Gs1ValidationResult	—	Chemin d’instance ; le constructeur accepte un analyseur injecté
Gs1SupplyChainProfile	—	NONE ignore les règles de profil	enum (5 cas)	—	RETAIL, FOOD, PHARMA, LOGISTICS, NONE ; requiredAIs(), recommendedAIs(), primaryIdentifiers()
Gs1ValidationResult	—	Constats partitionnés par sévérité à la construction	readonly class	—	isValid, findings, errors, warnings, infos, parsedData ; passes(), fails(), totalFindings()
Gs1ValidationFinding / Gs1FindingSeverity	—	severity, ruleId, message, ai et suggestion optionnels	readonly class / enum	—	Sévérités : Error, Warning, Info
CompositeComponentA::codewordsFor()	string $data	Encodation de chaîne binaire à usage général §5, conversion base-928, auto-contrôle par aller-retour	list<int> (chacun 0–927)	InvalidArgumentException	Alimente linkFor() ou un moteur de rendu de porteur CC-A externe
CompositeComponentA::encode()	ignoré	Refuse le rendu de symbole complet CC-A	—	UnsupportedBarcodeFeature (toujours)	Fail-closed ; voir Cas limites
CompositeComponentB::encode()	ignoré	Refuse l’encodage 2D CC-B	—	UnsupportedBarcodeFeature (toujours)	linkFor() reste disponible (CCSI 901)
CompositeComponentC::encode()	$data ; options transmises au porteur PDF417 ; carrierType (défaut GS1_128)	Porteur PDF417 complet avec le mot de code CCSI 920 en tête	Barcode2DData	BarcodeException ; CompositeLinkageException	Seul le porteur GS1_128 est admissible
CompositeComponent{A,B,C}::linkFor()	string $carrierId, array $codewords, CompositeCarrierType $carrierType	Apparie les mots de code du composant avec un porteur 1D	CompositeLinkage	CompositeLinkageException	Impose l’admissibilité et la capacité du porteur
CompositeVariant / CompositeCarrierType	—	CC_A, CC_B, CC_C ; GS1_DATABAR, GS1_128	enums	—	maxCodewords(), ccsi(), allowedCarriers(), usesFullPdf417()

Signatures des points d’entrée

public static function register(BarcodeEncoderRegistry $registry): void

public function encode(string $data, array $options = []): Barcode2DData

public static function validate(
    string $barcodeData,
    Gs1SupplyChainProfile $profile = Gs1SupplyChainProfile::NONE,
): Gs1ValidationResult

public function run(
    string $barcodeData,
    Gs1SupplyChainProfile $profile = Gs1SupplyChainProfile::NONE,
): Gs1ValidationResult

public function parse(string $data): Gs1ParsedData
public function parseDigitalLink(string $uri): Gs1ParsedData
public function encodeForCode128(object $parsed): string
public function encodeForQrCode(object $parsed): string
public function encodeForDataMatrix(object $parsed): string
public function validateAI(string $ai, string $value): bool

public function codewordsFor(string $data): array

Contrat de comportement

Résolution par le registre

La fabrique de registre par défaut de Core pré-lie les encodeurs Pro comme des entrées paresseuses, sous licence de capacité. BarcodeProServiceProvider::register() est le repli pris en charge pour les applications qui composent un registre sans valeurs par défaut, par exemple les intégrations de framework avec leur propre conteneur. Chaque encodeur convertit une charge utile de chaîne et des options par symbologie en un objet de données de code-barres que le moteur de rendu de page transforme en opérateurs de contenu PDF.

Analyse et validation GS1

Gs1DataParser accepte les chaînes d’AI lisibles ((01)09521234543213(17)260131) et les URI GS1 Digital Link. Il produit des séquences d’octets encodées pour les porteurs GS1-128, QR Code et Data Matrix, en appliquant la convention FNC1 et le séparateur de groupe de chaque porteur. Gs1Validator exécute un pipeline en cinq étapes : analyse, chiffres de contrôle (GTIN, SSCC), logique de dates, règles inter-AI et AI obligatoires du profil industriel. Un échec d’analyse produit un résultat invalide portant des constats ; il ne lève pas d’exception. Les constats se partitionnent par sévérité en erreurs, avertissements et infos.

Répartition des variants GS1 DataBar

Gs1DataBarEncoder::encode() répartit les sept variants ISO/IEC 24724:2011 Annexe J via un seul contrat d’options. Omnidirectional, Truncated, Stacked et Stacked Omnidirectional partagent l’algèbre de largeur d’élément du §5 avec un caractère de contrôle mod-79. Limited utilise sa propre algèbre de caractère de symbole du §6 avec un caractère de contrôle mod-89. Expanded et Expanded Stacked utilisent l’algèbre (17,4) du §7 : la machine à états de compaction à trois modes numérique, alphanumérique et ISO/IEC 646 du §7.2.5.5, plus un caractère de contrôle mod-211 (§7.2.6). La famille §5/§6 prend un GTIN-14 de 14 chiffres avec chiffre de contrôle mod-10 ou une identification d’article de 13 chiffres. La famille §7 prend une chaîne d’éléments AI GS1 brute (chiffres, lettres, le sous-ensemble de ponctuation ISO/IEC 646, FNC1 comme octet 0x1D). L’option linkage positionne le drapeau de liaison du composant 2D pour une utilisation comme composant linéaire d’un symbole GS1 Composite.

Composants GS1 Composite

CC-C produit un composant étendu 2D complet sur le porteur PDF417 entier, en injectant le mot de code CCSI obligatoire 920 comme premier mot de code de données (ISO/IEC 24723:2010 §5.4). CC-A génère des mots de code de données base-928 conformes via codewordsFor(), avec un auto-contrôle fail-closed par aller-retour encode-décode, mais refuse le rendu de symbole complet. CC-B refuse entièrement l’encodage 2D. linkFor() apparie les mots de code du composant avec un porteur 1D sous forme de valeur CompositeLinkage, en imposant l’admissibilité et la capacité du porteur.

Cas limites et modes de défaillance

• Chaque encodeur rejette une charge utile vide avec InvalidArgumentException.
• Micro QR : demander le niveau de correction d’erreur H non pris en charge le ramène SILENCIEUSEMENT à L au lieu d’échouer (prévalide les options si tu exiges une sélection EC fail-closed), car ISO/IEC 18004 ne définit que L, M et Q pour les symboles Micro QR.
• rMQR : le niveau de correction d’erreur doit être M ou H ; une charge utile dépassant la capacité des 32 versions est rejetée, jamais tronquée.
• JabCode : un nombre de couleurs hors de l’ensemble de puissances de deux pris en charge, un niveau ECC hors de 0–10, ou un nombre de symboles hors de 1–61 est rejeté ; les échecs d’encodage en aval lèvent JabCodeEncodingException.
• GS1 DataBar : la famille §5/§6 valide le chiffre de contrôle mod-10 du GTIN, et Limited restreint le chiffre indicateur à 0 ou 1. La famille §7 rejette les caractères non encodables et les séparateurs FNC1 en fin ou dupliqués. Expanded Stacked rejette un nombre impair de caractères de symbole par rangée et des hauteurs par rangée inférieures au minimum 34X. Les auto-contrôles de structure interne échouent avec InvalidSymbolStructureException plutôt que d’émettre un symbole malformé.
• GS1 Composite : encode() de CC-A et CC-B lève toujours UnsupportedBarcodeFeature (fail closed). CC-C lève BarcodeException sur des données vides ou un dépassement de capacité PDF417 (plus de 925 mots de code), et CompositeLinkageException pour un porteur non admissible.
• La validation GS1 signale une structure d’AI malformée et de mauvais chiffres de contrôle avant l’encodage ; une chaîne de chaîne logistique invalide ne produit jamais de symbole conforme scannable.
• IMB n’accepte que des entrées de 20, 25, 29 ou 31 chiffres.
• L’encodage de codes-barres n’effectue aucune cryptographie. Il n’y a pas de comportement spécifique au mode FIPS ; les encodeurs s’exécutent de manière identique quel que soit le profil FIPS.

Conformité

NextPDF implémente ces symbologies au regard des standards publiés cités ci-dessous et fige des traces de référence dans sa suite de tests. Les déclarations de cette page sont des affirmations de capacité : la prise en charge n’est pas la conformité, et la conformité n’est pas la certification. NextPDF ne détient aucune certification de symbologie. Les ancres de clause sont paraphrasées à partir du code source du produit et de ses fixtures de conformité ; le corpus du compliance-engine ne couvre pas les standards de symbologie de codes-barres, de sorte que les ancres ci-dessous sont ancrées dans le produit sans identifiants de référence.

Surface	Standard	Ancre de clause (paraphrasée)
Algèbre de largeur d’élément GS1 DataBar	ISO/IEC 24724:2011	§5.2 structure des caractères de symbole ; Annexe F.1 exemple travaillé (Omnidirectional) ; Annexe F.2 (Limited) ; Annexe F.3 (Expanded)
Dispositions empilées GS1 DataBar	ISO/IEC 24724:2011	§5.4 Stacked ; §5.5 Stacked Omnidirectional ; §7.2.8 partition des rangées et séparateurs d’Expanded Stacked
Encodation GS1 DataBar Expanded	ISO/IEC 24724:2011	§7.2.5.5 machine à états de compaction à trois modes ; §7.2.6 caractère de contrôle mod-211
Liaison GS1 Composite et CC-C	ISO/IEC 24723:2010	§5.4 sémantique du mot de code CCSI ; §5.1 admissibilité du porteur
Mots de code GS1 Composite CC-A	ISO/IEC 24723:2010	§5 encodation de chaîne binaire à usage général avec conversion base-928
Structure de symbole rMQR	ISO/IEC 23941:2022	§6.3.2 Table 1 dimensions des versions ; §7.8.2 masque fixe ; Annexe C / Annexe I référence d’information de format
Micro QR	ISO/IEC 18004	Capacité Micro QR M1–M4 et information de format
Han Xin Code	ISO/IEC 20830:2021	Structure de symbole ; motifs de repérage et d’alignement ; modes GB 2312 Région 1/2 ; ECC Reed–Solomon ; masquage
JabCode	ISO/IEC 23634	Structure de symbole, couleur et ECC
Symbologie postale	USPS-B-3200	Structure de champ Intelligent Mail Barcode

État de prise en charge par symbologie

Un variant est Verified lorsqu’une fixture sous pro/tests/** l’exerce, de préférence une trace de référence figée sur un exemple travaillé publié. Un variant livré sans fixture dédiée reste Claimed. Un variant sans encodeur est Not supported.

Symbologie / variant	État	Preuve (chemin de test)	Notes
Micro QR (M1–M4)	Verified	pro/tests/Unit/Barcode/MicroQrEncoderTest.php	Niveau unitaire ; une fixture de trace de référence d’exemple travaillé est un complément suivi
DotCode	Verified	pro/tests/Unit/Barcode/DotCodeEncoderTest.php ; DotCodeGfArithmeticTest.php	Arithmétique de corps de Galois couverte ; pas d’aller-retour avec un décodeur tiers
Han Xin Code	Verified	pro/tests/Unit/Barcode/HanXinEncoderTest.php ; HanXinRsEncodingTest.php	Chemin d’encodage Reed–Solomon explicitement exercé
JabCode (1–61 symboles, 4–256 couleurs, ECC 0–10)	Verified	pro/tests/Unit/Barcode/JabCode/JabCodeEncoderTest.php (+ 11 suites de composants dans le même répertoire)	Cascade multi-symboles et plage ECC exercées ; pas d’aller-retour avec un décodeur tiers
USPS Intelligent Mail Barcode	Verified	pro/tests/Unit/Barcode/ImbEncoderTest.php ; ImbRoutingCodeTest.php	Code de routage et validation de longueur 20/25/29/31 chiffres exercés
rMQR — les 32 versions ISO/IEC 23941	Verified	pro/tests/Conformance/Barcode/Rmqr/AnnexValidatedSizesTest.php ; RmqrAnnexCFormatInfoTest.php ; pro/tests/Unit/Barcode/Rmqr/RmqrEncoderTest.php	Paires version et EC vérifiées contre ISO/IEC 23941 Table 1 ; valeurs de référence d’information de format Annexe C / Annexe I
GS1 DataBar — Omnidirectional / Truncated	Verified	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarReferenceTest.php	Octet-identique à l’exemple travaillé de l’Annexe F.1 ; Truncated partage l’encodage à hauteur réduite
GS1 DataBar — Stacked / Stacked Omnidirectional	Verified	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarStackedReferenceTest.php	Division des rangées dérivée de la trace de l’Annexe F.1 ; construction des séparateurs selon §5.4 et §5.5
GS1 DataBar — Limited	Verified	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarLimitedReferenceTest.php ; pro/tests/Unit/Barcode/Gs1DataBar/Gs1DataBarLimitedEncoderTest.php	Octet-identique à l’exemple travaillé de l’Annexe F.2 (article 00098765432105)
GS1 DataBar — Expanded	Verified	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarExpandedReferenceTest.php ; pro/tests/Integration/Barcode/Gs1DataBarExpandedTwoDecoderTest.php	Octet-identique à l’exemple travaillé de l’Annexe F.3 ((10)12A) ; aller-retour avec décodeur indépendant contre zxing-cpp et ZBar
GS1 DataBar — Expanded Stacked	Verified	pro/tests/Unit/Barcode/Gs1DataBar/Gs1DataBarExpandedEncoderTest.php (cas empilés) ; l’aller-retour d’intégration ci-dessus	Même pipeline de données qu’Expanded en une rangée ; partition des rangées et séparateurs du §7.2.8 vérifiés
GS1 Composite — CC-C (porteur PDF417)	Verified	pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentCTest.php ; CompositeRoundtripTest.php ; CompositeLinkageTest.php	Interaction entre le mot de code CCSI 920 et le drapeau de liaison couverte
GS1 Composite — CC-A	Partial	pro/tests/Unit/Barcode/Gs1Composite/CompositeComponentACodewordTest.php ; pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentATest.php	Génération de mots de code Verified (base-928, auto-contrôle par aller-retour) ; rendu de symbole complet non pris en charge — encode() échoue fail-closed
GS1 Composite — CC-B	Not supported	pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentBTest.php (vérifie le rejet fail-closed)	Pas d’encodage 2D ; l’assistant de liaison (CCSI 901) reste disponible
Analyseur d’AI GS1	Verified	pro/tests/Unit/Barcode/Gs1DataParserTest.php ; Gs1DataParserFnc1Test.php	Les deux formats d’entrée et les trois sorties de séquence d’octets de porteur exercés
Validateur de chaîne logistique GS1	Verified	pro/tests/Unit/Barcode/Gs1ValidatorTest.php ; Gs1ValidatorCrossAiTest.php ; pro/tests/Unit/Barcode/Gs1/Gs1ValidatorDateValidationEdgeCaseTest.php	Chiffres de contrôle, combinaisons obligatoires inter-AI et logique de dates exercés

Notes de développement

• Les ancres de preuve sur cette page sont des chemins de test sous pro/tests/** ; le dépôt ne fournit aucun répertoire examples/ pour ce module.
• Les sept noms de capacité listés sous Disponibilité et licence sont les clés que lie le service provider. L’encodeur IMB est construit directement et ne porte aucune clé de registre.
• CC-A n’émet que la méthode d’encodation à usage général ; les méthodes compressées spécifiques à l’application sont un reliquat de densité documenté, pas une lacune de correction.

Limite de publication

Cette page ne documente que 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 d’assistance, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de tickets sont hors périmètre.

Voir aussi

• Vue d’ensemble de la capacité codes-barres (NextPDF Pro)
• Référence approfondie des graphiques
• Module barcode de Core