Générer des codes-barres GS1 Composite (porteur CC-C)

En bref

Capacité de prévisualisation opt-in — désactivée par défaut. La prise en charge de GS1 Composite est une fonctionnalité expérimentale et opt-in. Le seul composite livré est CC-C (le porteur PDF417 complet) : Core enregistre la capacité barcode.gs1-composite-cc-c et le paquet Premium (nextpdf/pro) verrouille l’encodeur derrière elle. Avec Core seul, la capacité est enregistrée mais son statut est Unavailable, de sorte que rien n’est émis. CC-A et CC-B ne sont pas encore disponibles : une demande d’encodage de l’un ou l’autre échoue en mode fail-closed avec une exception typée (UnsupportedBarcodeFeature). C’est une frontière de périmètre documentée, pas un défaut.

Un symbole GS1 Composite associe un composant linéaire (l’identifiant d’article principal) à un composant composite 2D (données étendues telles qu’un lot ou une date d’expiration). Cette recette montre comment la capacité composite est enregistrée et résolue, ce que fournit Core, ce qu’ajoute Premium, et exactement où la prise en charge s’arrête.

Installation

composer require nextpdf/core:^3

L’encodeur composite CC-C nécessite le paquet Premium :

composer require nextpdf/pro

Aperçu conceptuel

NextPDF résout une symbologie via le registre de capacités, de la même manière que le Module Code-barres résout n’importe quel encodeur. Une seule capacité GS1 Composite y est enregistrée :

• barcode.gs1-composite-cc-c est enregistrée dans CapabilityRegistry dans Core, sous le palier produit Pro. C’est le porteur PDF417 complet (ISO/IEC 15438) pour le composant composite CC-C. L’encodeur Pro achemine la charge utile à travers l’encodeur PDF417 core canonique. La capacité est toujours enregistrée mais Available uniquement lorsque Premium est installé — avec Core seul, son statut est Unavailable, donc elle est enregistrée mais inerte (opt-in, désactivée par défaut).

Aucune capacité CC-A ou CC-B n’est enregistrée. Un composant 2D CC-A/CC-B conforme requiert l’encodation de haut niveau base-928 de la Clause 5 d’ISO/IEC 24723 plus un porteur spécifique au composant, et cette version n’implémente pas ce chemin ; annoncer une capacité CC-A/CC-B nommerait donc un encodeur incapable d’émettre un symbole décodable.

Frontière fail-closed — ce qui n’est pas encore disponible

CC-A et CC-B ne sont intentionnellement pas livrés comme symbologies utilisables :

• CC-A — une primitive radix base-928 de bas niveau (Base928Converter, codewords uniquement) et un constructeur de chaîne binaire de la Clause 5 existent en interne, mais l’encodation de haut niveau CC-A complète de la Clause 5 d’ISO/IEC 24723 et le porteur spécifique à CC-A ne sont pas implémentés, de sorte qu’aucun symbole CC-A utilisable n’est produit. CompositeComponentA::encode() lève toujours l’exception typée UnsupportedBarcodeFeature.
• CC-B — le composant composite à capacité moyenne n’est de même pas implémenté ; CompositeComponentB::encode() lève toujours UnsupportedBarcodeFeature.

Ceux-ci échouent en mode fail-closed : une demande d’encodage de l’un ou l’autre lève une exception typée plutôt que d’émettre un symbole partiel ou incorrect. C’est une ligne de périmètre délibérée, pas un défaut.

Le chemin CC-C livré suit une discipline de golden de codewords : ses codewords générés sont figés par rapport à un golden et vérifiés par recoupement avec un décodeur indépendant, de sorte qu’un flux de codewords CC-C est vérifié, pas seulement produit. Aucune certification de bout en bout par rapport à la norme GS1 Composite n’est revendiquée.

Surface d’API

Les symboles GS1 Composite se résolvent via le registre de capacités plutôt que par une nouvelle méthode de façade de premier niveau :

• NextPDF\Support\CapabilityRegistry — la recherche qui indique si barcode.gs1-composite-cc-c est Available dans l’édition actuelle. Utilisez get('barcode.gs1-composite-cc-c')->status pour la décision de disponibilité ; has() rapporte seulement que la capacité est enregistrée (vrai même sur les installations Core seul), ce n’est donc pas le verrou de disponibilité.
• L’encodeur composite CC-C est fourni par nextpdf/pro et enregistré derrière le même contrat d’encodeur que documente la page Contrats / Code-barres.
• Il n’y a aucun encodeur CC-A ou CC-B à appeler. Les classes de composant CC-A/CC-B échouent en mode fail-closed sur encode().

Exécutez composer docs:generate-api-php -- --module=Barcode pour la table d’encodeurs générée.

Exemple de code — Démarrage rapide

Vérifiez que la capacité du porteur CC-C est disponible avant d’en dépendre. Avec Core seul, elle est enregistrée mais Unavailable ; avec Premium installé, elle est Available. Verrouillez sur le statut, pas sur has() — has() est vrai aussi sur une installation Core seul, car la capacité est toujours enregistrée.

<?php

declare(strict_types=1);

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

use NextPDF\Support\CapabilityRegistry;
use NextPDF\Support\CapabilityStatus;

$registry = CapabilityRegistry::getInstance();

$capability = $registry->get('barcode.gs1-composite-cc-c');

if ($capability->status === CapabilityStatus::Available) {
    echo "CC-C composite carrier is available (Premium present)\n";
} else {
    echo "CC-C composite carrier needs nextpdf/pro\n";
}

Exemple de code — Production

Verrouillez sur le statut de la capacité, et traitez explicitement les composants indisponibles. Un symbole CC-C fidèle ou un refus clair — jamais un composite incorrect.

<?php

declare(strict_types=1);

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

use NextPDF\Support\CapabilityRegistry;
use NextPDF\Support\CapabilityStatus;

final readonly class CompositeLabelService
{
    public function __construct(private CapabilityRegistry $registry) {}

    /**
     * Assert that the only shipped GS1 Composite (CC-C) is available before use.
     *
     * The capability is opt-in and default-OFF: on a Core-only install it is
     * registered but its status is Unavailable, so check the status — not has().
     */
    public function assertCompositeAvailable(): void
    {
        $status = $this->registry->get('barcode.gs1-composite-cc-c')->status;

        if ($status !== CapabilityStatus::Available) {
            // Core-only install. The CC-C encoder needs Premium. Fail fast with
            // a clear upgrade message rather than emitting a degraded symbol.
            throw new \RuntimeException(
                'GS1 Composite CC-C requires nextpdf/pro.',
            );
        }
    }

    // CC-A and CC-B are NOT yet available. Their component classes fail closed:
    // calling encode() always throws NextPDF\Pro\Barcode\Gs1Composite\
    // UnsupportedBarcodeFeature. There is no runnable CC-A/CC-B encode path —
    // CC-C is the only shipped GS1 Composite symbology. Do not call encode() on
    // CC-A/CC-B expecting a symbol.
    public function note(): string
    {
        return 'CC-A and CC-B are not available; use CC-C.';
    }
}

Cas limites et pièges

• CC-C a besoin de Premium pour être disponible, et il est désactivé par défaut. Core enregistre la capacité sous le palier Pro ; l’encodeur derrière elle est livré dans nextpdf/pro. Sur une installation Core seul, la capacité est enregistrée mais son statut est Unavailable. Verrouillez sur get(...)->status, pas sur has() — has() est vrai même sur Core seul car l’entrée est toujours enregistrée.
• Il n’y a aucun encodeur CC-A utilisable. Une primitive radix base-928 de bas niveau existe en interne, mais l’encodation de haut niveau CC-A complète de la Clause 5 d’ISO/IEC 24723 et le porteur spécifique à CC-A ne sont pas implémentés, de sorte qu’aucun symbole CC-A n’est produit.
• CC-A et CC-B échouent en mode fail-closed. Leur encode() lève toujours l’exception typée UnsupportedBarcodeFeature plutôt que d’émettre un symbole partiel. C’est une frontière de périmètre documentée, à dessein.
• Les identifiants d’application GS1 s’appliquent toujours. Le composant linéaire porte des données structurées GS1 avec le préfixe FNC1, comme dans Générer des codes-barres 1D et 2D.
• Bornez la charge utile. Une charge utile composite plus grande produit un symbole plus dense. Bornez la longueur de la charge utile avant l’encodage.

Performance

La génération de codewords est linéaire en longueur de charge utile ; l’émission du porteur est linéaire en surface de matrice. Il n’y a aucune étape de rastérisation — chaque module est un opérateur de chemin — de sorte que la mémoire reste plate quelle que soit la taille du symbole. La recette reste à l’intérieur du budget de 1500 ms / 64 Mo.

Notes de sécurité

Un symbole composite porte la charge utile que vous lui passez ; traitez la valeur comme non fiable côté consommateur. Les encodeurs encodent des octets et ne les authentifient pas. Bornez la longueur de la charge utile avant l’encodage pour maintenir la taille du symbole et le travail dans le budget.

Conformité

Énoncé	Spécification	Clause
Le composant composite CC-C livré utilise un porteur PDF417.	ISO/IEC 15438 (PDF417)	§5
L’encodation de haut niveau base-928 de CC-A est la méthode de la Clause 5 que cette version n’implémente pas.	ISO/IEC 24723 (GS1 Composite)	§5

Il s’agit d’une implémentation de prévisualisation expérimentale et opt-in. Core enregistre la capacité barcode.gs1-composite-cc-c sous le palier Pro ; le paquet Premium verrouille l’encodeur CC-C, qui est désactivé par défaut sur une installation Core seul (statut Unavailable). CC-A et CC-B ne sont pas encore disponibles — leur encode() échoue en mode fail-closed avec l’exception typée UnsupportedBarcodeFeature. Les codewords CC-C livrés sont figés par rapport à un golden et vérifiés par recoupement avec un décodeur indépendant. Aucune GA, conformité ou certification de bout en bout par rapport à la norme GS1 Composite n’est revendiquée, et aucun texte de norme n’est reproduit.

Voir aussi

• Module Code-barres
• Générer des codes-barres 1D et 2D
• Contrats / Code-barres