GS1 Composite-barcodes genereren (CC-C-drager)

In een oogopslag

Opt-in previewvermogen — standaard UIT. GS1 Composite-ondersteuning is een experimentele, opt-in-functie. De enige geleverde composite is CC-C (de volledige PDF417-drager): Core registreert het barcode.gs1-composite-cc-c-vermogen en het Premium-pakket (nextpdf/pro) gatet de encoder daarachter. Met alleen Core is het vermogen geregistreerd maar is de status Unavailable, dus er wordt niets uitgezonden. CC-A en CC-B zijn nog niet beschikbaar: een verzoek om een van beide te encoderen faalt gesloten met een getypeerde exception (UnsupportedBarcodeFeature). Dit is een gedocumenteerde scope-grens, geen defect.

Een GS1 Composite-symbool koppelt een lineaire component (de primaire itemidentificatie) aan een 2D-compositecomponent (uitgebreide gegevens zoals een batch of vervaldatum). Dit recept laat zien hoe het composite-vermogen wordt geregistreerd en opgelost, wat Core levert, wat Premium toevoegt, en precies waar de ondersteuning stopt.

Installeren

composer require nextpdf/core:^3

De CC-C-composite-encoder vereist het Premium-pakket:

composer require nextpdf/pro

Conceptueel overzicht

NextPDF lost een symbologie op via de capability registry, op dezelfde manier waarop de Barcode-module elke encoder oplost. Eén GS1 Composite-vermogen is daar geregistreerd:

• barcode.gs1-composite-cc-c is geregistreerd in CapabilityRegistry in Core, onder de Pro-producttier. Het is de volledige PDF417-drager (ISO/IEC 15438) voor de CC-C-compositecomponent. De Pro-encoder routeert de payload via de canonieke core-PDF417-encoder. Het vermogen is altijd geregistreerd maar alleen Available wanneer Premium is geïnstalleerd — met alleen Core is de status Unavailable, dus is het geregistreerd maar inert (opt-in, standaard UIT).

Er is geen CC-A- of CC-B-vermogen geregistreerd. Een conforme CC-A/CC-B 2D-component vereist ISO/IEC 24723 Clause 5 base-928 high-level encodation plus een componentspecifieke drager, en deze release implementeert dat pad niet, dus het adverteren van een CC-A/CC-B-vermogen zou een encoder benoemen die geen decodeerbaar symbool kan uitzenden.

Fail-closed-grens — wat nog niet beschikbaar is

CC-A en CC-B worden opzettelijk niet geleverd als bruikbare symbologieën:

• CC-A — een low-level base-928 radixprimitief (Base928Converter, alleen codewords) en een Clause-5 binary-string-builder bestaan intern, maar de volledige ISO/IEC 24723 Clause 5 CC-A high-level encodation en de CC-A-specifieke drager zijn niet geïmplementeerd, dus er wordt geen bruikbaar CC-A-symbool geproduceerd. CompositeComponentA::encode() werpt altijd de getypeerde UnsupportedBarcodeFeature-exception.
• CC-B — de compositecomponent met gemiddelde capaciteit is eveneens niet geïmplementeerd; CompositeComponentB::encode() werpt altijd UnsupportedBarcodeFeature.

Deze falen gesloten: een verzoek om een van beide te encoderen werpt een getypeerde exception in plaats van een gedeeltelijk of verkeerd symbool uit te zenden. Dit is een bewuste scope-lijn, geen defect.

Het geleverde CC-C-pad volgt een codeword-golden-discipline: de gegenereerde codewords worden vastgezet tegen een golden en kruisgecontroleerd met een onafhankelijke decoder, zodat een CC-C-codewordstroom geverifieerd is, niet slechts geproduceerd. Er wordt geen end-to-end-certificering tegen de GS1 Composite-standaard geclaimd.

API-oppervlak

GS1 Composite-symbolen worden opgelost via de capability registry in plaats van een nieuwe top-level-façademethode:

• NextPDF\Support\CapabilityRegistry — de opzoeking die meldt of barcode.gs1-composite-cc-c Available is in de huidige editie. Gebruik get('barcode.gs1-composite-cc-c')->status voor de beschikbaarheidsbeslissing; has() meldt alleen dat het vermogen geregistreerd is (waar zelfs op Core-only installaties), dus het is niet de beschikbaarheidsgate.
• De CC-C-composite-encoder wordt geleverd door nextpdf/pro en geregistreerd achter hetzelfde encodercontract dat de Contracts / Barcode-pagina documenteert.
• Er is geen CC-A- of CC-B-encoder om aan te roepen. De CC-A/CC-B-componentklassen falen gesloten op encode().

Voer composer docs:generate-api-php -- --module=Barcode uit voor de gegenereerde encodertabel.

Codevoorbeeld — Snelle start

Controleer dat het CC-C-dragervermogen beschikbaar is voordat je ervan afhankelijk bent. Met alleen Core is het geregistreerd maar Unavailable; met Premium geïnstalleerd is het Available. Gate op de status, niet op has() — has() is ook waar op een Core-only-installatie, omdat het vermogen altijd geregistreerd is.

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

Codevoorbeeld — Productie

Gate op de vermogensstatus, en behandel de niet-beschikbare componenten expliciet. Een getrouw CC-C-symbool of een duidelijke weigering — nooit een verkeerde 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.';
    }
}

Randgevallen en valkuilen

• CC-C heeft Premium nodig om beschikbaar te zijn, en het is standaard UIT. Core registreert het vermogen onder de Pro-tier; de encoder daarachter wordt geleverd in nextpdf/pro. Op een Core-only-installatie is het vermogen geregistreerd maar is de status Unavailable. Gate op get(...)->status, niet op has() — has() is zelfs op Core-only waar omdat de entry altijd geregistreerd is.
• Er is geen bruikbare CC-A-encoder. Een low-level base-928 radixprimitief bestaat intern, maar de volledige ISO/IEC 24723 Clause 5 CC-A high-level encodation en CC-A-specifieke drager zijn niet geïmplementeerd, dus er wordt geen CC-A-symbool geproduceerd.
• CC-A en CC-B falen gesloten. Hun encode() werpt altijd de getypeerde UnsupportedBarcodeFeature-exception in plaats van een gedeeltelijk symbool uit te zenden. Dit is een gedocumenteerde scope-grens, met opzet.
• GS1 application identifiers gelden nog steeds. De lineaire component draagt GS1-gestructureerde gegevens met het FNC1-prefix, zoals in 1D- en 2D-barcodes genereren.
• Begrens de payload. Een grotere composite-payload levert een dichter symbool op. Begrens de payloadlengte vóór het encoderen.

Prestaties

Codewordgeneratie is lineair in de payloadlengte; drageruitzending is lineair in het matrixoppervlak. Er is geen rasterisatiestap — elke module is een padoperator — dus het geheugen blijft vlak ongeacht de symboolgrootte. Het recept blijft binnen het budget van 1500 ms / 64 MB.

Beveiligingsnotities

Een composite-symbool draagt welke payload je ook doorgeeft; behandel de waarde als niet-vertrouwd aan de consumerende kant. De encoders encoderen bytes en authenticeren ze niet. Begrens de payloadlengte vóór het encoderen om de symboolgrootte en het werk binnen budget te houden.

Conformiteit

Statement	Spec	Clause
De geleverde CC-C-compositecomponent gebruikt een PDF417-drager.	ISO/IEC 15438 (PDF417)	§5
CC-A’s base-928 high-level encodation is de Clause 5-methode die deze release niet implementeert.	ISO/IEC 24723 (GS1 Composite)	§5

Dit is een experimentele, opt-in previewimplementatie. Core registreert het barcode.gs1-composite-cc-c-vermogen onder de Pro-tier; het Premium-pakket gatet de CC-C-encoder, die standaard UIT is op een Core-only-installatie (status Unavailable). CC-A en CC-B zijn nog niet beschikbaar — hun encode() faalt gesloten met de getypeerde UnsupportedBarcodeFeature-exception. De geleverde CC-C-codewords worden vastgezet tegen een golden en kruisgecontroleerd met een onafhankelijke decoder. Er wordt geen GA, conformiteit of end-to-end-certificering tegen de GS1 Composite-standaard geclaimd, en er wordt geen standaardtekst gereproduceerd.

Zie ook

• Barcode-module
• 1D- en 2D-barcodes genereren
• Contracts / Barcode