Menghasilkan barcode GS1 Composite (pembawa CC-C)

Sekilas

Kapabilitas preview opt-in — default MATI. Dukungan GS1 Composite adalah fitur eksperimental yang opt-in. Satu-satunya composite yang dikirimkan adalah CC-C (pembawa PDF417 penuh): Core mendaftarkan kapabilitas barcode.gs1-composite-cc-c dan paket Premium (nextpdf/pro) menggerbangi encoder di baliknya. Dengan Core saja, kapabilitas terdaftar tetapi statusnya Unavailable, sehingga tidak ada yang dipancarkan. CC-A dan CC-B belum tersedia: permintaan untuk meng-encode salah satunya gagal secara fail-closed dengan eksepsi bertipe (UnsupportedBarcodeFeature). Ini adalah batas cakupan yang terdokumentasi, bukan cacat.

Sebuah simbol GS1 Composite memasangkan komponen linear (pengidentifikasi item primer) dengan komponen composite 2D (data tambahan seperti batch atau kedaluwarsa). Resep ini menunjukkan bagaimana kapabilitas composite didaftarkan dan diselesaikan, apa yang disediakan Core, apa yang ditambahkan Premium, dan persis di mana dukungannya berhenti.

Pemasangan

composer require nextpdf/core:^3

Encoder composite CC-C membutuhkan paket Premium:

composer require nextpdf/pro

Ikhtisar konseptual

NextPDF menyelesaikan sebuah simbologi melalui registry kapabilitas, dengan cara yang sama Modul Barcode menyelesaikan encoder mana pun. Satu kapabilitas GS1 Composite terdaftar di sana:

• barcode.gs1-composite-cc-c terdaftar di CapabilityRegistry dalam Core, di bawah tier produk Pro. Ia adalah pembawa PDF417 penuh (ISO/IEC 15438) untuk komponen composite CC-C. Encoder Pro merutekan payload melalui encoder PDF417 core kanonis. Kapabilitas ini selalu terdaftar tetapi Available hanya saat Premium dipasang — dengan Core saja statusnya Unavailable, sehingga ia terdaftar namun inert (opt-in, default MATI).

Tidak ada kapabilitas CC-A atau CC-B yang terdaftar. Komponen 2D CC-A/CC-B yang konforman membutuhkan encodation tingkat-tinggi base-928 ISO/IEC 24723 Clause 5 plus pembawa spesifik-komponen, dan rilis ini tidak mengimplementasikan jalur itu, sehingga mengiklankan kapabilitas CC-A/CC-B akan menamai sebuah encoder yang tidak dapat memancarkan simbol yang dapat di-decode.

Batasan fail-closed — apa yang belum tersedia

CC-A dan CC-B sengaja tidak dikirimkan sebagai simbologi yang dapat dipakai:

• CC-A — sebuah primitif radix base-928 tingkat-rendah (Base928Converter, hanya codeword) dan sebuah pembangun string-biner Clause-5 ada secara internal, tetapi encodation tingkat-tinggi CC-A ISO/IEC 24723 Clause 5 penuh dan pembawa spesifik-CC-A tidak diimplementasikan, sehingga tidak ada simbol CC-A yang dapat dipakai yang dihasilkan. CompositeComponentA::encode() selalu melempar eksepsi bertipe UnsupportedBarcodeFeature.
• CC-B — komponen composite berkapasitas-menengah pun tidak diimplementasikan; CompositeComponentB::encode() selalu melempar UnsupportedBarcodeFeature.

Keduanya gagal secara fail-closed: permintaan untuk meng-encode salah satunya memunculkan eksepsi bertipe alih-alih memancarkan simbol parsial atau keliru. Ini adalah garis cakupan yang disengaja, bukan cacat.

Jalur CC-C yang dikirimkan mengikuti disiplin codeword-golden: codeword yang dihasilkannya dipatok terhadap sebuah golden dan diperiksa-silang dengan decoder independen, sehingga aliran codeword CC-C diverifikasi, bukan sekadar dihasilkan. Tidak ada sertifikasi ujung-ke-ujung terhadap standar GS1 Composite yang diklaim.

Permukaan API

Simbol GS1 Composite diselesaikan melalui registry kapabilitas alih-alih metode fasad tingkat-atas yang baru:

• NextPDF\Support\CapabilityRegistry — pencarian yang melaporkan apakah barcode.gs1-composite-cc-c Available dalam edisi saat ini. Gunakan get('barcode.gs1-composite-cc-c')->status untuk keputusan ketersediaan; has() hanya melaporkan bahwa kapabilitas terdaftar (true bahkan pada pemasangan Core-saja), sehingga itu bukan gerbang ketersediaan.
• Encoder composite CC-C disuplai oleh nextpdf/pro dan terdaftar di balik kontrak encoder yang sama yang didokumentasikan halaman Contracts / Barcode.
• Tidak ada encoder CC-A atau CC-B untuk dipanggil. Kelas komponen CC-A/CC-B gagal secara fail-closed pada encode().

Jalankan composer docs:generate-api-php -- --module=Barcode untuk tabel encoder yang dihasilkan.

Contoh kode — Mulai cepat

Periksa bahwa kapabilitas pembawa CC-C tersedia sebelum Anda mengandalkannya. Dengan Core saja, ia terdaftar tetapi Unavailable; dengan Premium dipasang ia Available. Gerbangi pada status, bukan pada has() — has() true pada pemasangan Core-saja juga, karena kapabilitas selalu terdaftar.

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

Contoh kode — Produksi

Gerbangi pada status kapabilitas, dan perlakukan komponen yang tidak tersedia secara eksplisit. Sebuah simbol CC-C yang setia atau penolakan yang jelas — tidak pernah composite yang keliru.

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

Kasus tepi & jebakan

• CC-C memerlukan Premium agar tersedia, dan ia default-MATI. Core mendaftarkan kapabilitas di bawah tier Pro; encoder di baliknya dikirimkan dalam nextpdf/pro. Pada pemasangan Core-saja, kapabilitas terdaftar tetapi statusnya Unavailable. Gerbangi pada get(...)->status, bukan pada has() — has() true bahkan pada Core-saja karena entri selalu terdaftar.
• Tidak ada encoder CC-A yang dapat dipakai. Sebuah primitif radix base-928 tingkat-rendah ada secara internal, tetapi encodation tingkat-tinggi CC-A ISO/IEC 24723 Clause 5 penuh dan pembawa spesifik-CC-A tidak diimplementasikan, sehingga tidak ada simbol CC-A yang dihasilkan.
• CC-A dan CC-B gagal secara fail-closed. encode()-nya selalu melempar eksepsi bertipe UnsupportedBarcodeFeature alih-alih memancarkan simbol parsial. Ini adalah batas cakupan yang terdokumentasi, secara sengaja.
• Application identifier GS1 tetap berlaku. Komponen linear membawa data berstruktur-GS1 dengan prefiks FNC1, seperti pada Menghasilkan barcode 1D dan 2D.
• Batasi payload. Payload composite yang lebih besar menghasilkan simbol yang lebih padat. Batasi panjang payload sebelum meng-encode.

Kinerja

Pembangkitan codeword linear terhadap panjang payload; pancaran pembawa linear terhadap luas matriks. Tidak ada langkah rasterisasi — setiap modul adalah operator path — sehingga memori tetap datar terlepas dari ukuran simbol. Resep ini tetap di dalam anggaran 1500 ms / 64 MB.

Catatan keamanan

Sebuah simbol composite membawa payload apa pun yang Anda berikan; perlakukan nilai itu sebagai tak-tepercaya di sisi yang mengonsumsi. Encoder meng-encode byte dan tidak mengautentikasinya. Batasi panjang payload sebelum meng-encode untuk menjaga ukuran simbol dan pekerjaan tetap dalam anggaran.

Konformitas

Pernyataan	Standar	Klausul
Komponen composite CC-C yang dikirimkan memakai pembawa PDF417.	ISO/IEC 15438 (PDF417)	§5
Encodation tingkat-tinggi base-928 CC-A adalah metode Clause 5 yang tidak diimplementasikan rilis ini.	ISO/IEC 24723 (GS1 Composite)	§5

Ini adalah implementasi preview eksperimental yang opt-in. Core mendaftarkan kapabilitas barcode.gs1-composite-cc-c di bawah tier Pro; paket Premium menggerbangi encoder CC-C, yang default-MATI pada pemasangan Core-saja (status Unavailable). CC-A dan CC-B belum tersedia — encode()-nya gagal secara fail-closed dengan eksepsi bertipe UnsupportedBarcodeFeature. Codeword CC-C yang dikirimkan dipatok terhadap sebuah golden dan diperiksa-silang dengan decoder independen. Tidak ada GA, konformitas, atau sertifikasi ujung-ke-ujung terhadap standar GS1 Composite yang diklaim, dan tidak ada teks standar yang direproduksi.

Lihat juga

• Modul Barcode
• Menghasilkan barcode 1D dan 2D
• Contracts / Barcode