stabilità: Sperimentale

Generare codici a barre GS1 Composite (carrier CC-C)

In sintesi

Capacità di anteprima opt-in — disattivata per impostazione predefinita. Il supporto GS1 Composite è una funzionalità sperimentale e opt-in. L’unico composito rilasciato è CC-C (il carrier PDF417 completo): Core registra la capacità barcode.gs1-composite-cc-c e il pacchetto Premium (nextpdf/pro) gestisce l’encoder dietro di essa. Con il solo Core, la capacità è registrata ma il suo stato è Unavailable, perciò non viene emesso nulla. CC-A e CC-B non sono ancora disponibili: una richiesta di codificare l’uno o l’altro fallisce in modo fail-closed con un’eccezione tipizzata (UnsupportedBarcodeFeature). Questo è un confine di ambito documentato, non un difetto.

Un simbolo GS1 Composite accoppia un componente lineare (l’identificatore primario dell’articolo) con un componente composito 2D (dati estesi come un lotto o una scadenza). Questa ricetta mostra come la capacità composita è registrata e risolta, cosa fornisce Core, cosa aggiunge Premium ed esattamente dove si ferma il supporto.

Installazione

composer require nextpdf/core:^3

L’encoder composito CC-C richiede il pacchetto Premium:

composer require nextpdf/pro

Panoramica concettuale

NextPDF risolve una simbologia attraverso il registro delle capacità, allo stesso modo in cui il Modulo Barcode risolve qualsiasi encoder. Una capacità GS1 Composite è registrata lì:

barcode.gs1-composite-cc-c è registrata in CapabilityRegistry in Core, sotto il tier di prodotto Pro. È il carrier PDF417 completo (ISO/IEC 15438) per il componente composito CC-C. L’encoder Pro instrada il payload attraverso l’encoder PDF417 canonico di core. La capacità è sempre registrata ma Available solo quando Premium è installato — con il solo Core il suo stato è Unavailable, perciò è registrata ma inerte (opt-in, disattivata per impostazione predefinita).

Nessuna capacità CC-A o CC-B è registrata. Un componente 2D CC-A/CC-B conforme richiede l’encodation di alto livello base-928 della Clausola 5 di ISO/IEC 24723 più un carrier specifico per il componente, e questo rilascio non implementa quel percorso, perciò pubblicizzare una capacità CC-A/CC-B nominerebbe un encoder che non può emettere un simbolo decodificabile.

Confine fail-closed — cosa non è ancora disponibile

CC-A e CC-B non sono intenzionalmente rilasciati come simbologie utilizzabili:

CC-A — esistono internamente una primitiva radix base-928 di basso livello (Base928Converter, solo codeword) e un costruttore di stringhe binarie della Clausola 5, ma l’encodation di alto livello CC-A completa della Clausola 5 di ISO/IEC 24723 e il carrier specifico per CC-A non sono implementati, perciò non viene prodotto alcun simbolo CC-A utilizzabile. CompositeComponentA::encode() solleva sempre l’eccezione tipizzata UnsupportedBarcodeFeature.
CC-B — il componente composito a media capacità non è parimenti implementato; CompositeComponentB::encode() solleva sempre UnsupportedBarcodeFeature.

Questi falliscono in modo fail-closed: una richiesta di codificare l’uno o l’altro solleva un’eccezione tipizzata invece di emettere un simbolo parziale o errato. Questa è una deliberata linea di ambito, non un difetto.

Il percorso CC-C rilasciato segue una disciplina codeword-golden: le sue codeword generate sono fissate rispetto a un golden e controllate in modo incrociato con un decoder indipendente, perciò un flusso di codeword CC-C è verificato, non semplicemente prodotto. Non si rivendica alcuna certificazione end-to-end rispetto allo standard GS1 Composite.

Superficie API

I simboli GS1 Composite si risolvono attraverso il registro delle capacità invece che tramite un nuovo metodo di facciata di primo livello:

NextPDF\Support\CapabilityRegistry — la ricerca che segnala se barcode.gs1-composite-cc-c è Available nell’edizione corrente. Usa get('barcode.gs1-composite-cc-c')->status per la decisione di disponibilità; has() segnala soltanto che la capacità è registrata (true anche su installazioni solo Core), perciò non è il gate di disponibilità.
L’encoder composito CC-C è fornito da nextpdf/pro e registrato dietro lo stesso contratto di encoder documentato dalla pagina Contracts / Barcode.
Non c’è alcun encoder CC-A o CC-B da chiamare. Le classi dei componenti CC-A/CC-B falliscono in modo fail-closed su encode().

Esegui composer docs:generate-api-php -- --module=Barcode per la tabella degli encoder generata.

Esempio di codice — Avvio rapido

Verifica che la capacità del carrier CC-C sia disponibile prima di dipenderne. Con il solo Core è registrata ma Unavailable; con Premium installato è Available. Vincola alla status, non a has() — has() è true anche su un’installazione solo Core, perché la capacità è sempre registrata.

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

Esempio di codice — Produzione

Vincola allo stato della capacità e tratta esplicitamente i componenti non disponibili. Un simbolo CC-C fedele o un rifiuto chiaro — mai un composito errato.

<?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.';
    }
}

Casi limite e insidie

CC-C necessita di Premium per essere disponibile ed è disattivato per impostazione predefinita. Core registra la capacità sotto il tier Pro; l’encoder dietro di essa è incluso in nextpdf/pro. Su un’installazione solo Core la capacità è registrata ma il suo stato è Unavailable. Vincola a get(...)->status, non a has() — has() è true anche su installazioni solo Core perché la voce è sempre registrata.
Non esiste un encoder CC-A utilizzabile. Una primitiva radix base-928 di basso livello esiste internamente, ma l’encodation di alto livello CC-A completa della Clausola 5 di ISO/IEC 24723 e il carrier specifico per CC-A non sono implementati, perciò non viene prodotto alcun simbolo CC-A.
CC-A e CC-B falliscono in modo fail-closed. Il loro encode() solleva sempre l’eccezione tipizzata UnsupportedBarcodeFeature invece di emettere un simbolo parziale. Questo è un confine di ambito documentato, di proposito.
Gli application identifier GS1 si applicano comunque. Il componente lineare porta dati strutturati GS1 con il prefisso FNC1, come in Generare codici a barre 1D e 2D.
Limita il payload. Un payload composito più grande produce un simbolo più denso. Limita la lunghezza del payload prima della codifica.

Prestazioni

La generazione delle codeword è lineare nella lunghezza del payload; l’emissione del carrier è lineare nell’area della matrice. Non c’è alcun passaggio di rasterizzazione — ogni modulo è un operatore di path — perciò la memoria resta piatta indipendentemente dalla dimensione del simbolo. La ricetta resta entro il budget di 1500 ms / 64 MB.

Note sulla sicurezza

Un simbolo composito porta qualsiasi payload tu gli passi; tratta il valore come non attendibile sul lato consumante. Gli encoder codificano byte e non li autenticano. Limita la lunghezza del payload prima della codifica per mantenere la dimensione del simbolo e il lavoro entro il budget.

Conformità

Affermazione	Standard	Clausola
Il componente composito CC-C rilasciato usa un carrier PDF417.	ISO/IEC 15438 (PDF417)	§5
L’encodation di alto livello base-928 di CC-A è il metodo della Clausola 5 che questo rilascio non implementa.	ISO/IEC 24723 (GS1 Composite)	§5

Questa è un’implementazione di anteprima sperimentale e opt-in. Core registra la capacità barcode.gs1-composite-cc-c sotto il tier Pro; il pacchetto Premium gestisce l’encoder CC-C, che è disattivato per impostazione predefinita su un’installazione solo Core (stato Unavailable). CC-A e CC-B non sono ancora disponibili — il loro encode() fallisce in modo fail-closed con l’eccezione tipizzata UnsupportedBarcodeFeature. Le codeword CC-C rilasciate sono fissate rispetto a un golden e controllate in modo incrociato con un decoder indipendente. Non si rivendica alcun GA, conformità o certificazione end-to-end rispetto allo standard GS1 Composite, e nessun testo normativo è riprodotto.