GS1 Composite barkodları oluşturma (CC-C taşıyıcısı)

Bir bakışta

Katılımlı önizleme yeteneği — varsayılan olarak KAPALI. GS1 Composite desteği deneysel, katılımlı bir özelliktir. Sevk edilen tek bileşik CC-C’dir (tam PDF417 taşıyıcısı): Core, barcode.gs1-composite-cc-c yeteneğini kaydeder ve Premium (nextpdf/pro) paketi kodlayıcıyı bunun arkasında kapılar. Yalnızca Core ile yetenek kayıtlıdır ama durumu Unavailable’dır; bu nedenle hiçbir şey yayılmaz. CC-A ve CC-B henüz kullanılamaz: bunlardan birini kodlama isteği, türlenmiş bir istisna (UnsupportedBarcodeFeature) ile hata durumunda kapalı kalır. Bu, bir kusur değil, belgelenmiş bir kapsam sınırıdır.

Bir GS1 Composite simgesi, bir doğrusal bileşeni (birincil öğe tanımlayıcısı) bir 2D bileşik bileşenle (parti ya da son kullanma gibi genişletilmiş veri) eşleştirir. Bu tarif, bileşik yeteneğin nasıl kaydedilip çözüldüğünü, Core’un ne sağladığını, Premium’un ne eklediğini ve desteğin tam olarak nerede durduğunu gösterir.

Kurulum

composer require nextpdf/core:^3

CC-C bileşik kodlayıcısı Premium paketi gerektirir:

composer require nextpdf/pro

Kavramsal genel bakış

NextPDF, bir simgelemeyi yetenek kayıt defteri üzerinden, Barkod modülünün herhangi bir kodlayıcıyı çözmesiyle aynı biçimde çözer. Orada bir GS1 Composite yeteneği kayıtlıdır:

• barcode.gs1-composite-cc-c, Core’da CapabilityRegistry içinde, Pro ürün katmanı altında kayıtlıdır. CC-C bileşik bileşeni için tam PDF417 taşıyıcısıdır (ISO/IEC 15438). Pro kodlayıcısı, yükü kurallı çekirdek PDF417 kodlayıcısı üzerinden yönlendirir. Yetenek her zaman kayıtlıdır ama yalnızca Premium yüklüyken Available’dır — yalnızca Core ile durumu Unavailable’dır; bu nedenle kayıtlı ama etkisizdir (katılımlı, varsayılan KAPALI).

Hiçbir CC-A ya da CC-B yeteneği kayıtlı değildir. Uygun bir CC-A/CC-B 2D bileşeni, ISO/IEC 24723 Madde 5 base-928 üst düzey kodlamasını artı bileşene özgü bir taşıyıcıyı gerektirir ve bu sürüm o yolu uygulamaz; bu nedenle bir CC-A/CC-B yeteneğinin tanıtımı, çözülebilir bir simge yayamayan bir kodlayıcıyı adlandırırdı.

Hata-durumunda-kapalı sınırı — henüz kullanılamayan

CC-A ve CC-B, kullanılabilir simgelemeler olarak kasıtlı biçimde sevk edilmez:

• CC-A — düşük düzeyli bir base-928 taban ilkel’i (Base928Converter, yalnızca kod sözcükleri) ve bir Madde-5 ikili-dize oluşturucusu içeride var olsa da, tam ISO/IEC 24723 Madde 5 CC-A üst düzey kodlaması ve CC-A’ya özgü taşıyıcı uygulanmamıştır; bu nedenle kullanılabilir bir CC-A simgesi üretilmez. CompositeComponentA::encode() her zaman türlenmiş UnsupportedBarcodeFeature istisnasını fırlatır.
• CC-B — orta kapasiteli bileşik bileşen de benzer biçimde uygulanmamıştır; CompositeComponentB::encode() her zaman UnsupportedBarcodeFeature fırlatır.

Bunlar hata durumunda kapalı kalır: bunlardan birini kodlama isteği, kısmi ya da yanlış bir simge yaymak yerine türlenmiş bir istisna yükseltir. Bu, bir kusur değil, kasıtlı bir kapsam çizgisidir.

Sevk edilen CC-C yolu, bir kod-sözcüğü-altın disiplini izler: ürettiği kod sözcükleri bir altına sabitlenir ve bağımsız bir kod çözücüyle çapraz denetlenir; böylece bir CC-C kod-sözcüğü akışı yalnızca üretilmez, doğrulanır. GS1 Composite standardına karşı uçtan uca hiçbir sertifikasyon iddia edilmez.

API yüzeyi

GS1 Composite simgeleri, yeni bir üst düzey cephe yöntemi yerine yetenek kayıt defteri üzerinden çözülür:

• NextPDF\Support\CapabilityRegistry — barcode.gs1-composite-cc-c’nin geçerli sürümde Available olup olmadığını bildiren arama. Kullanılabilirlik kararı için get('barcode.gs1-composite-cc-c')->status kullanın; has() yalnızca yeteneğin kayıtlı olduğunu bildirir (yalnızca Core kurulumlarında bile doğrudur), bu nedenle kullanılabilirlik kapısı değildir.
• CC-C bileşik kodlayıcısı nextpdf/pro tarafından sağlanır ve Sözleşmeler / Barkod sayfasının belgelediği aynı kodlayıcı sözleşmesinin arkasında kaydedilir.
• Çağrılacak bir CC-A ya da CC-B kodlayıcısı yoktur. CC-A/CC-B bileşen sınıfları encode() çağrısında hata durumunda kapalı kalır.

Üretilen kodlayıcı tablosu için composer docs:generate-api-php -- --module=Barcode çalıştırın.

Kod örneği — hızlı başlangıç

Ona bağlanmadan önce CC-C taşıyıcı yeteneğinin kullanılabilir olduğunu denetleyin. Yalnızca Core ile kayıtlı ama Unavailable’dır; Premium yüklüyken Available’dır. has() üzerine değil, durum üzerine kapı koyun — has() yalnızca Core kurulumunda da doğrudur; çünkü yetenek her zaman kayıtlıdır.

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

Kod örneği — üretim

Yetenek durumu üzerine kapı koyun ve kullanılamayan bileşenleri açıkça ele alın. Aslına uygun bir CC-C simgesi ya da açık bir reddetme — asla yanlış bir bileşik değil.

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

Sınır durumları ve dikkat edilmesi gerekenler

• CC-C’nin kullanılabilir olması için Premium gerekir ve varsayılan olarak KAPALIdır. Core, yeteneği Pro katmanı altında kaydeder; arkasındaki kodlayıcı nextpdf/pro ile gelir. Yalnızca Core kurulumunda yetenek kayıtlı ama durumu Unavailable’dır. has() üzerine değil, get(...)->status üzerine kapı koyun — has(), yalnızca Core’da bile doğrudur; çünkü girdi her zaman kayıtlıdır.
• Kullanılabilir bir CC-A kodlayıcısı yoktur. Düşük düzeyli bir base-928 taban ilkel’i içeride var olsa da, tam ISO/IEC 24723 Madde 5 CC-A üst düzey kodlaması ve CC-A’ya özgü taşıyıcı uygulanmamıştır; bu nedenle hiçbir CC-A simgesi üretilmez.
• CC-A ve CC-B hata durumunda kapalı kalır. encode() çağrıları, kısmi bir simge yaymak yerine her zaman türlenmiş UnsupportedBarcodeFeature istisnasını fırlatır. Bu, bilerek konulmuş, belgelenmiş bir kapsam sınırıdır.
• GS1 uygulama tanımlayıcıları hâlâ geçerlidir. Doğrusal bileşen, 1D ve 2D barkodlar oluşturma belgesindeki gibi, FNC1 ön ekiyle GS1-yapılandırılmış veri taşır.
• Yükü sınırlayın. Daha büyük bir bileşik yük, daha yoğun bir simge verir. Kodlamadan önce yük uzunluğunu sınırlayın.

Performans

Kod sözcüğü üretimi yük uzunluğunda doğrusaldır; taşıyıcı yayma, matris alanında doğrusaldır. Bir rasterleştirme adımı yoktur — her modül bir yol işlecidir — bu nedenle bellek, simge boyutundan bağımsız olarak düz kalır. Tarif, 1500 ms / 64 MB bütçesinin içinde kalır.

Güvenlik notları

Bir bileşik simge, geçirdiğiniz yükü taşır; tüketen tarafta değeri güvenilmez olarak ele alın. Kodlayıcılar baytları kodlar ve onların kimliğini doğrulamaz. Simge boyutunu ve işi bütçenin içinde tutmak için kodlamadan önce yük uzunluğunu sınırlayın.

Uygunluk

İfade	Standart	Madde
Sevk edilen CC-C bileşik bileşeni bir PDF417 taşıyıcısı kullanır.	ISO/IEC 15438 (PDF417)	§5
CC-A’nın base-928 üst düzey kodlaması, bu sürümün uygulamadığı Madde 5 yöntemidir.	ISO/IEC 24723 (GS1 Composite)	§5

Bu, deneysel, katılımlı bir önizleme uygulamasıdır. Core, barcode.gs1-composite-cc-c yeteneğini Pro katmanı altında kaydeder; Premium paketi, yalnızca Core kurulumunda varsayılan olarak KAPALI olan (durum Unavailable) CC-C kodlayıcısını kapılar. CC-A ve CC-B henüz kullanılamaz — encode() çağrıları türlenmiş UnsupportedBarcodeFeature istisnası ile hata durumunda kapalı kalır. Sevk edilen CC-C kod sözcükleri bir altına sabitlenir ve bağımsız bir kod çözücüyle çapraz denetlenir. GS1 Composite standardına karşı hiçbir GA, uygunluk ya da uçtan uca sertifikasyon iddia edilmez ve hiçbir standart metin olduğu gibi aktarılmaz.

Ayrıca bakınız

• Barkod modülü
• 1D ve 2D barkodlar oluşturma
• Sözleşmeler / Barkod