stabilność: Eksperymentalna

Generowanie kodów kreskowych GS1 Composite (nośnik CC-C)

W skrócie

Opcjonalna zdolność podglądowa — domyślnie WYŁĄCZONA. Wsparcie GS1 Composite to eksperymentalna, opcjonalna funkcja. Jedyny dostarczony kompozyt to CC-C (pełny nośnik PDF417): Core rejestruje zdolność barcode.gs1-composite-cc-c, a pakiet Premium (nextpdf/pro) bramkuje za nią koder. Z samym Core zdolność jest zarejestrowana, ale jej status to Unavailable, więc nic nie jest emitowane. CC-A i CC-B nie są jeszcze dostępne: żądanie zakodowania którejkolwiek kończy się niepowodzeniem fail-closed z typowanym wyjątkiem (UnsupportedBarcodeFeature). To udokumentowana granica zakresu, a nie wada.

Symbol GS1 Composite łączy komponent liniowy (podstawowy identyfikator pozycji) z komponentem kompozytowym 2D (dane rozszerzone, takie jak partia czy data ważności). Ten przepis pokazuje, jak zdolność kompozytowa jest rejestrowana i rozwiązywana, co dostarcza Core, co dodaje Premium i dokładnie gdzie wsparcie się kończy.

Instalacja

composer require nextpdf/core:^3

Koder kompozytowy CC-C wymaga pakietu Premium:

composer require nextpdf/pro

Przegląd koncepcyjny

NextPDF rozwiązuje symbologię przez rejestr zdolności, w taki sam sposób, w jaki moduł Barcode rozwiązuje dowolny koder. Zarejestrowana jest tam jedna zdolność GS1 Composite:

barcode.gs1-composite-cc-c jest zarejestrowana w CapabilityRegistry w Core, pod poziomem produktu Pro. To pełny nośnik PDF417 (ISO/IEC 15438) dla komponentu kompozytowego CC-C. Koder Pro kieruje ładunek przez kanoniczny koder PDF417 rdzenia. Zdolność jest zawsze zarejestrowana, ale Available tylko wtedy, gdy zainstalowane jest Premium — z samym Core jej status to Unavailable, więc jest zarejestrowana, lecz bezczynna (opcjonalna, domyślnie WYŁĄCZONA).

Nie jest rejestrowana żadna zdolność CC-A ani CC-B. Zgodny komponent 2D CC-A/CC-B wymaga wysokopoziomowego kodowania base-928 z klauzuli 5 ISO/IEC 24723 oraz nośnika właściwego dla danego komponentu, a to wydanie nie implementuje tej ścieżki, więc reklamowanie zdolności CC-A/CC-B nazwałoby koder, który nie potrafi wyemitować dekodowalnego symbolu.

Granica fail-closed — co nie jest jeszcze dostępne

CC-A i CC-B celowo nie są dostarczane jako używalne symbologie:

CC-A — niskopoziomowy prymityw radix base-928 (Base928Converter, tylko słowa kodowe) oraz konstruktor łańcucha binarnego z klauzuli 5 istnieją wewnętrznie, ale pełne wysokopoziomowe kodowanie CC-A z klauzuli 5 ISO/IEC 24723 oraz nośnik właściwy dla CC-A nie są zaimplementowane, więc nie powstaje żaden używalny symbol CC-A. CompositeComponentA::encode() zawsze zgłasza typowany wyjątek UnsupportedBarcodeFeature.
CC-B — komponent kompozytowy o średniej pojemności również nie jest zaimplementowany; CompositeComponentB::encode() zawsze zgłasza UnsupportedBarcodeFeature.

Kończą się one niepowodzeniem fail-closed: żądanie zakodowania którejkolwiek zgłasza typowany wyjątek, zamiast emitować częściowy lub błędny symbol. To celowa linia zakresu, a nie wada.

Dostarczona ścieżka CC-C podlega dyscyplinie golden słów kodowych: jej wygenerowane słowa kodowe są przypięte do wzorca golden i sprawdzane krzyżowo niezależnym dekoderem, więc strumień słów kodowych CC-C jest zweryfikowany, a nie jedynie wyprodukowany. Nie deklaruje się certyfikacji end-to-end względem normy GS1 Composite.

Powierzchnia API

Symbole GS1 Composite rozwiązują się przez rejestr zdolności, a nie przez nową metodę fasady najwyższego poziomu:

NextPDF\Support\CapabilityRegistry — wyszukanie zgłaszające, czy barcode.gs1-composite-cc-c jest Available w bieżącej edycji. Użyj get('barcode.gs1-composite-cc-c')->status dla decyzji o dostępności; has() zgłasza jedynie, że zdolność jest zarejestrowana (true nawet na instalacji tylko z Core), więc nie jest bramką dostępności.
Koder kompozytowy CC-C jest dostarczany przez nextpdf/pro i zarejestrowany za tym samym kontraktem kodera, który dokumentuje strona Kontrakty / Barcode.
Nie ma kodera CC-A ani CC-B do wywołania. Klasy komponentów CC-A/CC-B kończą się niepowodzeniem fail-closed na encode().

Uruchom composer docs:generate-api-php -- --module=Barcode, aby uzyskać wygenerowaną tabelę koderów.

Przykład kodu — szybki start

Sprawdź, czy zdolność nośnika CC-C jest dostępna, zanim na niej polegasz. Z samym Core jest zarejestrowana, ale Unavailable; z zainstalowanym Premium jest Available. Bramkuj na statusie, a nie na has() — has() jest true również na instalacji tylko z Core, ponieważ zdolność jest zawsze zarejestrowana.

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

Przykład kodu — produkcja

Bramkuj na statusie zdolności i traktuj niedostępne komponenty jawnie. Wierny symbol CC-C albo jasna odmowa — nigdy błędny kompozyt.

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

Przypadki brzegowe i pułapki

CC-C wymaga Premium, aby było dostępne, i jest domyślnie WYŁĄCZONE. Core rejestruje zdolność pod poziomem Pro; koder za nią jest dostarczany w nextpdf/pro. Na instalacji tylko z Core zdolność jest zarejestrowana, ale jej status to Unavailable. Bramkuj na get(...)->status, a nie na has() — has() jest true nawet na instalacji tylko z Core, ponieważ wpis jest zawsze zarejestrowany.
Nie ma używalnego kodera CC-A. Niskopoziomowy prymityw radix base-928 istnieje wewnętrznie, ale pełne wysokopoziomowe kodowanie CC-A z klauzuli 5 ISO/IEC 24723 oraz nośnik właściwy dla CC-A nie są zaimplementowane, więc nie powstaje żaden symbol CC-A.
CC-A i CC-B kończą się niepowodzeniem fail-closed. Ich encode() zawsze zgłasza typowany wyjątek UnsupportedBarcodeFeature, zamiast emitować częściowy symbol. To udokumentowana granica zakresu, celowo.
Identyfikatory aplikacji GS1 nadal obowiązują. Komponent liniowy niesie dane ustrukturyzowane wg GS1 z prefiksem FNC1, jak w Generowaniu kodów kreskowych 1D i 2D.
Ogranicz ładunek. Większy ładunek kompozytowy daje gęstszy symbol. Ogranicz długość ładunku przed kodowaniem.

Wydajność

Generowanie słów kodowych jest liniowe względem długości ładunku; emisja nośnika jest liniowa względem powierzchni macierzy. Nie ma kroku rasteryzacji — każdy moduł to operator ścieżki — więc pamięć pozostaje płaska niezależnie od rozmiaru symbolu. Przepis mieści się w budżecie 1500 ms / 64 MB.

Uwagi dotyczące bezpieczeństwa

Symbol kompozytowy niesie dowolny ładunek, który przekażesz; traktuj wartość jako niezaufaną po stronie konsumującej. Kodery kodują bajty i ich nie uwierzytelniają. Ogranicz długość ładunku przed kodowaniem, aby utrzymać rozmiar symbolu i pracę w budżecie.

Zgodność

Twierdzenie	Norma	Klauzula
Dostarczony komponent kompozytowy CC-C używa nośnika PDF417.	ISO/IEC 15438 (PDF417)	§5
Wysokopoziomowe kodowanie base-928 CC-A to metoda z klauzuli 5, której to wydanie nie implementuje.	ISO/IEC 24723 (GS1 Composite)	§5

To eksperymentalna, opcjonalna implementacja podglądowa. Core rejestruje zdolność barcode.gs1-composite-cc-c pod poziomem Pro; pakiet Premium bramkuje koder CC-C, który jest domyślnie WYŁĄCZONY na instalacji tylko z Core (status Unavailable). CC-A i CC-B nie są jeszcze dostępne — ich encode() kończy się niepowodzeniem fail-closed z typowanym wyjątkiem UnsupportedBarcodeFeature. Dostarczone słowa kodowe CC-C są przypięte do wzorca golden i sprawdzane krzyżowo niezależnym dekoderem. Nie deklaruje się GA, zgodności ani certyfikacji end-to-end względem normy GS1 Composite i nie odtwarza się żadnego tekstu normatywnego.