Barkod: 1D ve 2D sembol kodlayıcıları

Bir bakışta

Barkod modülü, sembol uygulama katmanını sağlar. Doğrusal sembolojileri (Code 128, EAN, UPC, Interleaved 2 of 5, Codabar, posta kodları) ve matris sembolojilerini (QR Code, Data Matrix, PDF417) kodlar. Hata düzeltmesini hesaplar ve her kodlayıcıyı barkod sözleşmelerinin arkasına kaydeder; böylece belge yazıcısı sonucu boyayabilir. Sözleşme tanımları ayrı bir sayfada yer alır. Aşağıdaki notu okuyun.

Her konu için tek bir kanonik sayfa. Bir kodlayıcının uyguladığı arabirimler (Barcode1DEncoderInterface, Barcode2DEncoderInterface, BarcodeEncoderInterface, Gs1DataParserInterface) şurada belgelenmiştir: Contracts / Barcode. Bu sayfa, bu sözleşmeleri uygulayan somut kodlayıcıları belgeler. Sayfalar birbirini tamamlar, kopya değildir. Hizmet sağlayıcı arabirimi (SPI) ayrıntıları için sözleşmeler sayfasını okuyun. Sembolojiler için bu sayfayı okuyun.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Bir barkod kodlayıcısı, bir yük dizesini belge yazıcısının Taşınabilir Belge Biçimi (PDF) grafikleri olarak boyadığı iki boyutlu (2D) bir modül matrisine ya da tek boyutlu (1D) bir çubuk dizisine dönüştürür. Bu modül somut kodlayıcıları sağlar.

Barcode1D doğrusal motordur. BarcodeType, desteklenen doğrusal sembolojileri sıralar: Code 39 (sağlama toplamı olan ve olmayan), Code 93, Code 128 ailesi, EAN-8/EAN-13, UPC-A/UPC-E, Interleaved ve Standard 2 of 5, Codabar, Code 11, POSTNET, PLANET, Intelligent Mail (IMB) ve MSI. generate(), çubuk desenini açıklayan bir BarcodeData değer nesnesi döndürür.

2D kodlayıcılar, QrEncoder, DataMatrixEncoder ve Pdf417Encoder, BarcodeEncoderInterface arabirimini uygular ve bir Barcode2DData matrisi döndürür. Barcode2DType, motorun tanıdığı matris sembolojilerini sıralar; bunlara QR Code, Data Matrix ve PDF417 dâhildir. Micro QR, rMQR, GS1 DataBar ve Han Xin gibi ek sembolojiler, kayıt defteri yönlendirmesinde kullanılmak üzere sıralanmıştır. Her sembolojiyi destekleyen kodlayıcı kümesi sürüme bağlıdır. Matris hata düzeltmesi bir Galois alanı üzerinde hesaplanır. GaloisField ve GaloisFieldPrime, QR, Data Matrix ve PDF417 kodlayıcılarının paylaştığı Reed-Solomon aritmetiğini sağlar.

BarcodeEncoderRegistry arama mekanizmasıdır. PHP Standards Recommendation 11 (PSR-11) ContainerInterface arabirimini uygular, createDefault() aracılığıyla varsayılan kayıt defterini sağlar ve bir sembolojiyi resolve() ile ilgili kodlayıcıya çözer. Uygulama kodu bir kodlayıcıya nadiren doğrudan erişir. Üst düzey Document::write1DBarcode() / write2DBarcode() cephesi sembolojiyi belirtir; kayıt defteri de kodlayıcıyı sağlar. 1D motoru @since 1.0.0 sürümündendir. 2D kodlayıcılar @since 1.3.0 sürümündendir. Kayıt defteri @since 3.0.0 sürümündendir.

API yüzeyi

Sınıf	Temel üyeler	Rol
Barcode1D	generate(string $code, BarcodeType $type): BarcodeData	Doğrusal sembol kodlayıcısı (@since 1.0.0)
QrEncoder	encode(string $data, array $options = []): Barcode2DData	QR Code kodlayıcısı (@since 1.3.0)
DataMatrixEncoder	encode(string $data, array $options = []): Barcode2DData	Data Matrix kodlayıcısı (@since 1.3.0)
Pdf417Encoder	encode(string $data, array $options = []): Barcode2DData	PDF417 kodlayıcısı (@since 1.3.0)
BarcodeEncoderRegistry	createDefault(), register(), resolve(), has(), get(), registered()	PSR-11 kodlayıcı kayıt defteri (@since 3.0.0)
BarcodeType / Barcode2DType	enum durumları	Desteklenen semboloji numaralandırmaları
GaloisField / GaloisFieldPrime	sonlu alan aritmetiği	Reed-Solomon hata düzeltmesi

Tam PHPDoc tablosunu üretmek için composer docs:generate-api-php -- --module=Barcode komutunu çalıştırın.

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

Kaynak: examples/10-barcodes.php. Cephe, istenen semboloji için kodlayıcıyı kayıt defteri aracılığıyla çözer.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Barcode\Barcode2DType;
use NextPDF\Barcode\BarcodeType;
use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->addPage();

$doc->write1DBarcode('4006381333931', BarcodeType::EAN13, x: 15, y: null, w: 60, h: 20);
$doc->write2DBarcode('https://nextpdf.dev', Barcode2DType::QRCode, x: 15, y: 40, w: 40, h: 40);

$doc->save(__DIR__ . '/output/10-barcodes.pdf');

Kod örneği — üretim

Bir 2D kodlayıcıyı doğrudan kayıt defteri aracılığıyla çözün ve kodlamadan önce yükü sınırlandırın.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Barcode\Barcode2DType;
use NextPDF\Barcode\BarcodeEncoderRegistry;
use NextPDF\Exception\BarcodeException;
use Psr\Log\LoggerInterface;

final readonly class TrackingCodeService
{
    private const int MAX_PAYLOAD = 512;

    public function __construct(
        private BarcodeEncoderRegistry $registry,
        private LoggerInterface $logger,
    ) {}

    /** @return \NextPDF\Barcode\Barcode2DData */
    public function encode(string $trackingId): \NextPDF\Barcode\Barcode2DData
    {
        if (strlen($trackingId) > self::MAX_PAYLOAD) {
            throw new \LengthException('Tracking payload exceeds the encode bound.');
        }

        try {
            $encoder = $this->registry->resolve(Barcode2DType::QRCode->value);

            return $encoder->encode($trackingId, ['errorCorrection' => 'high']);
        } catch (BarcodeException $e) {
            $this->logger->error('Barcode encode failed', ['error' => $e->getMessage()]);

            throw $e;
        }
    }
}

Sınır durumları ve tuzaklar

• Bir sembolojinin karakter kümesini ya da kontrol basamağı kuralını ihlal eden doğrusal yük, BarcodeException oluşturur. EAN/UPC, kontrol basamağını hesaplar ve ekler. Kontrol basamağını önceden eklemeyin.
• 2D $options dizisi, QR için hata düzeltme düzeyi gibi sembolojiye özgüdür. Çoğu kodlayıcı bilinmeyen anahtarları yok sayar. Her anahtarı kodlayıcının kendi belgelerine göre doğrulayın.
• Barcode2DType, core sürümünün kodlayıcı sağladığından daha fazla semboloji sıralar. BarcodeEncoderRegistry::resolve(), kaydedilmemiş bir semboloji için yer tutucu döndürmek yerine bir özel durum oluşturur.
• Kaydedilmiş kodlayıcılar paylaşılan örneklerdir. Bunları, yapıcı yapılandırması dışında durumsuz tutun. Çağrı başına durum, eşzamanlı üretimleri bozar.
• Aşırı uzun bir yük, daha yoğun ve daha büyük bir matris üretir. Sembol boyutu üzerinden hizmet reddini önlemek için kodlamadan önce yük uzunluğunu sınırlandırın.

Performans

Kodlama maliyeti, O(1) olan kayıt defteri aramasıyla değil, yük uzunluğu ve matris boyutuyla ölçeklenir. Kısa bir Code 128 yükü mikrosaniyeler içinde kodlanır. Yüksek hata düzeltmeli yoğun bir QR Code en ağır durumdur. Çok sembollü örnek sayfası, 1500 ms duvar süresi / 64 MB tepe bellek bütçesinin içinde kalır. Yeniden üretilebilirlik profili bitwise’dır. Aynı yük ve seçenekler her zaman aynı modül matrisini ve aynı boyanmış baytları üretir.

Güvenlik notları

Barkod yükleri çoğunlukla güvenilmeyen kaynaklardan gelir: taranan bir tekdüzen kaynak konumlayıcısı (URL), bir seri numarası ya da bir izleme kodu. Kodlayıcılar baytları kodlar; bunları yorumlamaz. Zararlı bir URL’yi kodlayan bir QR Code yine de geçerli bir QR Code’dur; bu nedenle yükün güvenilirliğinden tüketici sorumludur. Matris boyutunu, iş yükünü ve çıktı boyutunu bir bütçe içinde tutmak için kodlamadan önce yük uzunluğunu sınırlandırın. Başka bir yerde bir barkoddan çözülen herhangi bir veriyi, uygulamaya yeniden girdiğinde güvenilmeyen girdi olarak değerlendirin. Motor tehdit modeli için bkz. /modules/core/security/.

Uygunluk

İddia	Standart	Başvuru
QR Code sembolleri, QR Code matris semboloji belirtimine uyar.	ISO/IEC 18004	QR Code sembolojisi
Data Matrix sembolleri, Data Matrix semboloji belirtimine uyar.	ISO/IEC 16022	Data Matrix sembolojisi
PDF417 sembolleri, PDF417 semboloji belirtimine uyar.	ISO/IEC 15438	PDF417 sembolojisi
Code 128 sembolleri, Code 128 doğrusal semboloji belirtimine uyar.	ISO/IEC 15417	Code 128 sembolojisi
EAN/UPC sembolleri, EAN/UPC semboloji belirtimine uyar.	ISO/IEC 15420	EAN/UPC sembolojisi

Bu semboloji standartları doğrulanabilir alıntı külliyatında bulunmadığından hiçbir reference_id kaydedilmemiştir. Bu sayfa, gereksinimi kendi ifadeleriyle aktarır ve kaynağı numara ve maddeyle belirtir. Yetkili kodlama kuralları için yayımlanan standartlara başvurun. Kodlayıcılar tests/Unit/Barcode/ tarafından sınanır. Semboloji belirtimlerine göre doğruluk, uçtan uca PDF uygunluğu beyanı değil, test paketinin sorumluluğundadır.

Ayrıca bakın

• Contracts / Barcode — bu sınıfların uyguladığı kodlayıcı arabirimleri (SPI).
• Graphics modülü — kodlanmış matrisi boyayan çizim katmanı.
• Document modülü — üst düzey write1DBarcode() / write2DBarcode() cephesi.
• Uygunluk genel bakışı
• Motor güvenlik modeli