Contracts / Barcode

Bir bakışta

Barkod alanı dört sözleşme tanımlar: tek boyutlu (1D) bir kodlayıcı, iki boyutlu (2D) bir kodlayıcı, kayıt defteri üzerinden keşfedilebilen genel bir kodlayıcı ve bir GS1 veri ayrıştırıcısı. Bu sözleşmeler birlikte, barkod hizmetlerinin karşılaması gereken biçimi tanımlar. Sembol bilgisi uygulamaları bu sözleşmelere göre kaydedilir.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Bir barkod kodlayıcısı, bir yük dizesini taşınabilir belge biçimi (PDF) yazıcısının çizeceği modül matrisine dönüştürür. NextPDF, kodlayıcı sözleşmelerini boyutlarına göre ayırır. Barcode1DEncoderInterface, Code 128 ve EAN-13 gibi doğrusal sembol bilgilerini işler ve bir BarcodeData değer nesnesi döndürür. Barcode2DEncoderInterface, hızlı yanıt (QR) kodu ve Data Matrix gibi matris sembol bilgilerini işler. Hata düzeltme düzeyi gibi sembol bilgisine özgü ayarlar için bir seçenek eşlemesi içeren bir Barcode2DData değer nesnesi döndürür.

BarcodeEncoderInterface, genel hizmet sağlayıcı sözleşmesidir. BarcodeEncoderRegistry aracılığıyla keşfedilebilen her 2D kodlayıcı bu sözleşmeyi uygular. Sözleşme, tek renkli bir Barcode2DData veya renkli bir BarcodeColorData matrisi döndürür; böylece kayıtlı bir kodlayıcı, ayrı bir arabirime gerek kalmadan renkli bir sembol üretebilir. Kodlayıcıların, oluşturma zamanı yapılandırması dışında durumsuz olması beklenir. Kayıt defteri, kayıtlı her tür için tek bir paylaşılan örnek döndürür; bu nedenle çağrıya özgü herhangi bir durum kusur sayılır.

Gs1DataParserInterface, yapılandırılmış veriye yönelik sözleşmedir. Bir GS1 öğe dizesini türlenmiş bir nesneye ayrıştırır, ardından o nesneyi bir QR kodu, bir Data Matrix veya bir Code 128 taşıyıcısı için yeniden kodlar. Bu, GS1 dilbilgisini sembol bilgisinden ayrı tutar. Ayrıştırıcı, uygulama tanımlayıcılarını bir kez doğrular. Taşıyıcıya özgü yöntemler, aynı ayrıştırılmış yapıyı her hedef için biçimlendirir. Dört sözleşme de stable durumdadır. BarcodeEncoderInterface 3.0.0 sürümünden beri kararlıdır; diğerleri 1.0.0 sürümünden beri. Yöntem eklemeleri yalnızca varsayılan uygulamalarla gelir.

API yüzeyi

Tür	Çeşit	Temel üyeler	Kararlılık	Bu sürümden beri
Barcode1DEncoderInterface	arabirim	encode(string): BarcodeData	stable	1.0.0
Barcode2DEncoderInterface	arabirim	encode(string, array): Barcode2DData	stable	1.0.0
BarcodeEncoderInterface	arabirim	encode(string, array): Barcode2DData|BarcodeColorData	stable	3.0.0
Gs1DataParserInterface	arabirim	parse(), encodeForQrCode(), encodeForDataMatrix(), encodeForCode128()	stable	1.0.0

2D sözleşmelerinde $options dizisi, QR kodu için bir hata düzeltme düzeyi gibi sembol bilgisine özgü ayarlar taşır. Sözleşme bu anahtarları kısıtlamaz. Kayıtlı her kodlayıcı kendi seçenek kümesini belgeler.

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

examples/10-barcodes.php

<?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->setTitle('Barcode Examples');
$doc->addPage();

$doc->setFont('helvetica', '', 10);
$doc->cell(0, 6, 'Code 128:', newLine: true);
$doc->write1DBarcode('NEXTPDF-2026', BarcodeType::C128, x: 15, y: null, w: 80, h: 20);
$doc->ln(28);

$doc->cell(0, 6, 'QR Code (URL):', newLine: true);
$doc->write2DBarcode('https://nextpdf.dev', Barcode2DType::QRCode, x: 15, y: null, w: 40, h: 40);

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

write1DBarcode() ve write2DBarcode(), bir kodlayıcıyı kayıt defteri aracılığıyla çözer. Uygulama kodunuzun sözleşmelere doğrudan dokunması nadirdir. Bir sembol bilgisi adı belirtirsiniz; kayıt defteri kodlayıcıyı sağlar.

Kod örneği — üretim

examples/contracts/barcode-production.php

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\Barcode2DEncoderInterface;
use NextPDF\Contracts\Gs1DataParserInterface;
use NextPDF\Exception\BarcodeException;
use Psr\Log\LoggerInterface;

final readonly class Gs1LabelService
{
    public function __construct(
        private Gs1DataParserInterface $parser,
        private Barcode2DEncoderInterface $dataMatrix,
        private LoggerInterface $logger,
    ) {}

    /**
     * Parse a GS1 element string and encode it as a Data Matrix.
     *
     * @param string $elementString A GS1 element string with Application Identifiers.
     */
    public function encodeLabel(string $elementString): \NextPDF\Barcode\Barcode2DData
    {
        try {
            $parsed = $this->parser->parse($elementString);
            $payload = $this->parser->encodeForDataMatrix($parsed);

            return $this->dataMatrix->encode($payload, ['errorCorrection' => 'high']);
        } catch (BarcodeException $e) {
            $this->logger->error('GS1 label encoding failed', [
                'error' => $e->getMessage(),
            ]);

            throw $e;
        }
    }
}

Hizmet, ayrıştırıcı ve kodlayıcı sözleşmelerine bağımlıdır. catch bloğu, belirli BarcodeException istisnasını günlüğe kaydeder ve yeniden fırlatır; hiçbir zaman çıplak bir \Exception yakalamaz.

Uç durumlar ve dikkat edilmesi gerekenler

• Kayıtlı bir kodlayıcı paylaşılır. Bir kodlayıcıdaki çağrıya özgü durum, eşzamanlı işlemleri bozar. Kodlayıcıları kurucu yapılandırması dışında durumsuz tutun.
• BarcodeEncoderInterface::encode() renkli veya tek renkli veri döndürebilir. Bunu tüketen kod, verinin tek renkli olduğunu varsaymak yerine hem Barcode2DData hem de BarcodeColorData türlerini işlemelidir.
• 2D $options dizisi sözleşme tarafından doğrulanmaz. Çoğu kodlayıcı bilinmeyen anahtarları sessizce yok sayar. Anahtar adını kodlayıcının kendi belgelerine göre doğrulayın.
• GS1 ayrıştırması dilbilgisi açısından katıdır. Bilinmeyen bir uygulama tanımlayıcısı içeren bir öğe dizesi, kısmi bir ayrıştırma üretmek yerine bir BarcodeException oluşturur. Üst akış girdisini doğrulayın.
• 1D ve 2D sözleşmeleri birbirinin yerine kullanılamaz. Bir QR yükünü bir 1D kodlayıcıya geçirmek geçersiz bir sembol üretir. Kayıt defteri, sembol bilgisi türüne göre yönlendirir; bu nedenle doğrudan bir sözleşme çağrısı yerine kayıt defterini tercih edin.

Performans

Kodlama maliyeti, çağırdığınız sözleşmeye göre değil, yük uzunluğuna ve hedef matris boyutuna göre ölçeklenir. Kısa bir Code 128 yükü mikrosaniyeler içinde kodlanır. Yüksek hata düzeltmeye sahip yoğun bir QR kodu, en ağır 2D durumudur. Birden çok sembol içeren örnek sayfa bile 1500 ms duvar süresi ve 64 MB tepe değeri içeren performance_budget sınırlarının oldukça içinde kalır. Matris bir kez hesaplanır ve PDF işleçleri olarak çizilir. Aynı yük ve seçenekler her zaman aynı modül matrisini ürettiğinden, yeniden üretilebilirlik bitwise düzeydedir. Kayıt defteri araması O(1) karmaşıklığındadır; asıl işi sembol bilgisi algoritması yapar.

Güvenlik notları

Barkod yükleri sıklıkla saldırgan etkisi altındadır; taranan bir tekdüzen kaynak konumlandırıcı (URL), bir seri numarası veya bir izleme kodu buna örnek olabilir. Sözleşmeler baytları kodlar; bunları yorumlamaz. Kötü niyetli bir URL’yi kodlayan bir QR kodu yine de geçerli bir QR kodudur; bu nedenle yükün güvenilirliği kodlayıcının değil, tüketicinin sorumluluğundadır. Matris boyutunu sınırlamak ve aşırı büyük bir sembol üzerinden hizmet reddinden kaçınmak için yük uzunluğunu kodlamadan önce kısıtlayın. GS1 ayrıştırıcısı, hatalı biçimlendirilmiş uygulama tanımlayıcılarını reddeder; bu da bir enjeksiyon yüzeyini ortadan kaldırır. Geçerli alanların anlamsal içeriğini doğrulamaz. Kodu çözülmüş barkod verilerini, uygulamaya yeniden girdiği her yerde güvenilmeyen girdi olarak ele alın.

Uygunluk

İddia	Standart	Kaynak
QR kodu sembolleri, QR kodu matris sembol bilgisi belirtimine uyar.	ISO/IEC 18004	QR kodu sembol bilgisi
Data Matrix sembolleri, Data Matrix sembol bilgisi belirtimine uyar.	ISO/IEC 16022	Data Matrix sembol bilgisi
Code 128 sembolleri, Code 128 doğrusal sembol bilgisi belirtimine uyar.	ISO/IEC 15417	Code 128 sembol bilgisi
GS1 öğe dizeleri, GS1 uygulama tanımlayıcısı dilbilgisine göre ayrıştırılır.	GS1 General Specifications	Uygulama tanımlayıcıları

Bu standartlara numara ve madde düzeyinde başvurulur. Doğrulanabilir alıntı külliyatında yer almadıklarından, hiçbir reference_id kaydedilmez. Motor, gereksinimi kendi sözcükleriyle aktarır ve kaynağa atıfta bulunur. Yetkili kodlama kuralları için yayımlanmış standartlara başvurun.

Ticari bağlam

Core, kodlayıcı sözleşmelerini tanımlar, dondurur ve yaygın sembol bilgilerini sunar. Pro ve Enterprise sürümleri, ek barkod sembol bilgileri için aynı BarcodeEncoderInterface ile genişletilmiş bir kodlayıcı kümesi kaydeder; böylece ticari bir dağıtım, bir uygulama programlama arabirimi (API) değişikliği olmadan kapsamını genişletir. Core, kayıtlı kodlayıcıları BarcodeEncoderRegistry aracılığıyla çözer. Sözleşme yüzeyi tüm sürümlerde aynıdır.

Ayrıca bakınız

• Contracts: 41 genel arabirim (SPI) — hizmet sağlayıcı arabirimi (SPI) genel bakışı ve kararlılık katmanları.
• Barcode — bu sözleşmelere göre kaydedilen sembol bilgisi uygulamaları.
• Contracts / Document — kodlanmış matrisi çizen PdfDocumentInterface.
• Graphics — barkod modüllerini işleyen çizim katmanı.
• Exception — hatalı biçimlendirilmiş GS1 girdisinde fırlatılan BarcodeException.