GS1-Composite-Barcodes erzeugen (CC-C-Träger)

Auf einen Blick

Per Opt-in aktivierbare Vorschau-Fähigkeit — standardmäßig AUS. Die GS1-Composite-Unterstützung ist eine experimentelle, per Opt-in aktivierbare Funktion. Das einzige ausgelieferte Composite ist CC-C (der vollständige PDF417-Träger): Core registriert die barcode.gs1-composite-cc-c-Fähigkeit und das Premium-Paket (nextpdf/pro) gated den Encoder dahinter. Mit Core allein ist die Fähigkeit registriert, ihr Status ist jedoch Unavailable, sodass nichts ausgegeben wird. CC-A und CC-B sind noch nicht verfügbar: Eine Anforderung, eines davon zu encodieren, schlägt fail-closed mit einer typisierten Ausnahme (UnsupportedBarcodeFeature) fehl. Dies ist eine dokumentierte Umfangsgrenze, kein Defekt.

Ein GS1-Composite-Symbol koppelt eine lineare Komponente (den primären Artikelbezeichner) mit einer 2D-Composite-Komponente (erweiterte Daten wie Charge oder Verfallsdatum). Dieses Rezept zeigt, wie die Composite-Fähigkeit registriert und aufgelöst wird, was Core bereitstellt, was Premium hinzufügt und genau wo die Unterstützung endet.

Installation

composer require nextpdf/core:^3

Der CC-C-Composite-Encoder erfordert das Premium-Paket:

composer require nextpdf/pro

Konzeptioneller Überblick

NextPDF löst eine Symbologie über die Capability-Registry auf, genauso wie das Barcode-Modul jeden Encoder auflöst. Dort ist eine GS1-Composite-Fähigkeit registriert:

• barcode.gs1-composite-cc-c ist in CapabilityRegistry in Core unter der Produktstufe Pro registriert. Es ist der vollständige PDF417-Träger (ISO/IEC 15438) für die CC-C-Composite-Komponente. Der Pro-Encoder leitet die Nutzlast durch den kanonischen Core-PDF417-Encoder. Die Fähigkeit ist immer registriert, aber nur Available, wenn Premium installiert ist — mit Core allein ist ihr Status Unavailable, sodass sie registriert, aber inert ist (per Opt-in, standardmäßig AUS).

Es ist keine CC-A- oder CC-B-Fähigkeit registriert. Eine konforme CC-A/CC-B-2D-Komponente erfordert die ISO/IEC-24723-Clause-5-Base-928-High-Level-Encodation plus einen komponentenspezifischen Träger, und dieses Release implementiert diesen Pfad nicht, sodass das Bewerben einer CC-A/CC-B-Fähigkeit einen Encoder benennen würde, der kein decodierbares Symbol ausgeben kann.

Fail-closed-Grenze — was noch nicht verfügbar ist

CC-A und CC-B werden absichtlich nicht als nutzbare Symbologien ausgeliefert:

• CC-A — ein Low-Level-Base-928-Radix-Primitive (Base928Converter, nur Codewörter) und ein Clause-5-Binärstring-Builder existieren intern, aber die vollständige ISO/IEC-24723-Clause-5-CC-A-High-Level-Encodation und der CC-A-spezifische Träger sind nicht implementiert, sodass kein nutzbares CC-A-Symbol erzeugt wird. CompositeComponentA::encode() wirft immer die typisierte UnsupportedBarcodeFeature-Ausnahme.
• CC-B — die Composite-Komponente mittlerer Kapazität ist ebenfalls nicht implementiert; CompositeComponentB::encode() wirft immer UnsupportedBarcodeFeature.

Diese schlagen fail-closed fehl: Eine Anforderung, eines davon zu encodieren, löst eine typisierte Ausnahme aus, statt ein partielles oder falsches Symbol auszugeben. Dies ist eine bewusste Umfangsgrenze, kein Defekt.

Der ausgelieferte CC-C-Pfad folgt einer Codeword-Golden-Disziplin: Seine erzeugten Codewörter werden gegen ein Golden gepinnt und mit einem unabhängigen Decoder gegengeprüft, sodass ein CC-C-Codewort-Stream verifiziert und nicht bloß erzeugt wird. Es wird keine Ende-zu-Ende-Zertifizierung gegen den GS1-Composite-Standard beansprucht.

API-Oberfläche

GS1-Composite-Symbole werden über die Capability-Registry aufgelöst statt über eine neue Top-Level-Fassadenmethode:

• NextPDF\Support\CapabilityRegistry — die Suche, die meldet, ob barcode.gs1-composite-cc-c in der aktuellen Edition Available ist. Verwenden Sie get('barcode.gs1-composite-cc-c')->status für die Verfügbarkeitsentscheidung; has() meldet nur, dass die Fähigkeit registriert ist (auch auf Core-only- Installationen wahr), und ist daher nicht das Verfügbarkeits-Gate.
• Der CC-C-Composite-Encoder wird von nextpdf/pro geliefert und hinter demselben Encoder-Vertrag registriert, den die Seite Contracts / Barcode dokumentiert.
• Es gibt keinen CC-A- oder CC-B-Encoder zum Aufrufen. Die CC-A/CC-B-Komponentenklassen schlagen bei encode() fail-closed fehl.

Führen Sie composer docs:generate-api-php -- --module=Barcode für die generierte Encoder-Tabelle aus.

Codebeispiel — Schnellstart

Prüfen Sie, dass die CC-C-Träger-Fähigkeit verfügbar ist, bevor Sie sich auf sie verlassen. Mit Core allein ist sie registriert, aber Unavailable; mit installiertem Premium ist sie Available. Gaten Sie auf den Status, nicht auf has() — has() ist auch auf einer Core-only-Installation wahr, weil die Fähigkeit immer registriert ist.

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

Codebeispiel — Produktion

Gaten Sie auf den Status der Fähigkeit und behandeln Sie die nicht verfügbaren Komponenten explizit. Ein originalgetreues CC-C-Symbol oder eine klare Verweigerung — niemals ein falsches Composite.

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

Randfälle & Fallstricke

• CC-C benötigt Premium, um verfügbar zu sein, und ist standardmäßig AUS. Core registriert die Fähigkeit unter der Pro-Stufe; der Encoder dahinter wird in nextpdf/pro ausgeliefert. Auf einer Core-only-Installation ist die Fähigkeit registriert, ihr Status ist jedoch Unavailable. Gaten Sie auf get(...)->status, nicht auf has() — has() ist auch auf Core-only wahr, weil der Eintrag immer registriert ist.
• Es gibt keinen nutzbaren CC-A-Encoder. Ein Low-Level-Base-928-Radix-Primitive existiert intern, aber die vollständige ISO/IEC-24723-Clause-5-CC-A-High-Level-Encodation und der CC-A-spezifische Träger sind nicht implementiert, sodass kein CC-A-Symbol erzeugt wird.
• CC-A und CC-B schlagen fail-closed fehl. Ihr encode() wirft immer die typisierte UnsupportedBarcodeFeature-Ausnahme, statt ein partielles Symbol auszugeben. Dies ist eine dokumentierte Umfangsgrenze, absichtlich.
• GS1-Application-Identifiers gelten weiterhin. Die lineare Komponente trägt GS1-strukturierte Daten mit dem FNC1-Präfix, wie in 1D- und 2D-Barcodes erzeugen.
• Begrenzen Sie die Nutzlast. Eine größere Composite-Nutzlast ergibt ein dichteres Symbol. Begrenzen Sie die Nutzlastlänge vor dem Encodieren.

Performance

Die Codewort-Erzeugung ist linear in der Nutzlastlänge; die Trägerausgabe ist linear in der Matrixfläche. Es gibt keinen Rasterisierungsschritt — jedes Modul ist ein Pfadoperator — sodass der Speicher unabhängig von der Symbolgröße flach bleibt. Das Rezept bleibt innerhalb des 1500-ms-/64-MB-Budgets.

Sicherheitshinweise

Ein Composite-Symbol trägt die Nutzlast, die Sie übergeben; behandeln Sie den Wert auf der verbrauchenden Seite als nicht vertrauenswürdig. Die Encoder encodieren Bytes und authentifizieren sie nicht. Begrenzen Sie die Nutzlastlänge vor dem Encodieren, um Symbolgröße und Arbeit im Budget zu halten.

Konformität

Aussage	Standard	Klausel
Die ausgelieferte CC-C-Composite-Komponente nutzt einen PDF417-Träger.	ISO/IEC 15438 (PDF417)	§5
Die Base-928-High-Level-Encodation von CC-A ist die Clause-5-Methode, die dieses Release nicht implementiert.	ISO/IEC 24723 (GS1 Composite)	§5

Dies ist eine experimentelle, per Opt-in aktivierbare Vorschau-Implementierung. Core registriert die barcode.gs1-composite-cc-c-Fähigkeit unter der Pro-Stufe; das Premium-Paket gated den CC-C-Encoder, der auf einer Core-only-Installation standardmäßig AUS ist (Status Unavailable). CC-A und CC-B sind noch nicht verfügbar — ihr encode() schlägt fail-closed mit der typisierten UnsupportedBarcodeFeature-Ausnahme fehl. Die ausgelieferten CC-C-Codewörter werden gegen ein Golden gepinnt und mit einem unabhängigen Decoder gegengeprüft. Es wird keine GA, keine Konformität und keine Ende-zu-Ende-Zertifizierung gegen den GS1-Composite-Standard beansprucht, und es wird kein Standardtext wiedergegeben.

Siehe auch

• Barcode-Modul
• 1D- und 2D-Barcodes erzeugen
• Contracts / Barcode