PDF'de 1D ve 2D barkod oluşturma

Bir bakışta

Bu tarif, tek boyutlu (1D) ve iki boyutlu (2D) barkodların doğrudan bir Taşınabilir Belge Biçimi (PDF) sayfasına nasıl çizileceğini gösterir. Core HasBarcodes trait’i size write1DBarcode() ve write2DBarcode() yöntemlerini sağlar. Her iki yöntem de sembolü geçerli sayfaya yerel PDF yol işleçleriyle çizer; bu nedenle çıktı sade ve belirlenimci bir vektör içeriğidir. Bu tarif examples/10-barcodes.php dosyasını izler.

Kurulum

composer require nextpdf/core:^3

Ek bir uzantıya gerek yoktur. Barkod kodlayıcıları saf PHP’dir; NextPDF, sembolleri standart PDF dikdörtgen işleciyle (ISO 32000-2 §8.5) çizer.

Kavramsal genel bakış

Barkod, görüntü olarak gömülmez; çizilir. Yük, kodladığınız veridir; örneğin bir ürün numarası veya bir web adresi.

write1DBarcode(), yükü seçilen BarcodeType için bir bar/space desenine kodlar ve ardından bir dizi dolu dikdörtgen üretir. write2DBarcode(), seçilen Barcode2DType için bir modül matrisi oluşturur ve her koyu modül için dolu bir dikdörtgen üretir. Data Matrix ve QR Code, Reed-Solomon hata düzeltmesi kullanır; bu sayede sembolün bir kısmı hasar görse bile tarayıcı veriyi geri kazanabilir.

Her modül, entropi kaynağı içermeyen belirlenimci bir re … f yoludur; bu nedenle barkod içeriğinin kendisi tam olarak yeniden üretilebilir. Yeniden üretilebilirlik profili structural şeklindedir; çünkü çevreleyen belge hâlâ kayıt başına atomları taşır: trailer /ID ile birlikte /CreationDate ve /ModDate zaman damgaları. Test koşum düzeneği, bu atomlar çıkarıldıktan sonra qpdf ile normalleştirilmiş yapıyı karşılaştırır.

API yüzeyi

NextPDF\Core\Concerns\HasBarcodes (Document içine karıştırılmıştır):

write1DBarcode(string $code, BarcodeType $type, ?float $x = null, ?float $y = null, float $w = 0, float $h = 30, float $barWidth = 0.4, bool $skipZeroWidthBars = true): static
write2DBarcode(string $code, Barcode2DType $type, ?float $x = null, ?float $y = null, float $w = 0, float $h = 0, float $moduleSize = 1.0, string $ecLevel = 'L', ?int $mask = null, ?int $version = null, bool $gs1 = false, bool $dmre = false, bool $rectangular = false): static

Sembololoji, verinin çubuklara veya modüllere nasıl dönüştüğünü tanımlayan bir barkod standardıdır. BarcodeType, 1D sembolojilerini listeler (C128, EAN13, UPCA, I25, CODABAR, ISBN, GS1_128, …); Barcode2DType ise 2D sembolojilerini listeler (QRCode, DataMatrix, PDF417, HanXin, MicroQR, …).

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

<?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 Quick Start');
$doc->addPage();

$doc->write1DBarcode('NEXTPDF-2026', BarcodeType::C128, x: 15, y: 30, w: 80, h: 20);
$doc->write2DBarcode('https://nextpdf.dev', Barcode2DType::QRCode, x: 15, y: 60, w: 40, h: 40);

$doc->save(__DIR__ . '/barcodes.pdf');
echo "Wrote barcodes.pdf\n";

Kod örneği — üretim

Aşağıdaki eksiksiz ve koşum düzeneğiyle çalıştırılabilir örnek, examples/10-barcodes.php dosyasını yansıtır. PDF’i, koşum düzeneğinin NEXTPDF_COOKBOOK_OUTPUT aracılığıyla sağladığı yola yazar; örneği elle çalıştırdığınızda ise yerel bir dosyayı kullanır. Yeniden üretilebilirlik koşum düzeneği ardından örneği iki kez çalıştırabilir ve yapısal özdeşliği doğrulayabilir. Yapı, kayıt başına /ID ve zaman damgası atomları çıkarıldıktan sonra qpdf ile normalleştirilir.

<?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', 'B', 18);
$doc->cell(0, 12, 'Barcode Examples', newLine: true);
$doc->ln(5);

// --- 1D barcodes ---
$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, '1D Barcodes', newLine: true);
$doc->ln(3);

$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, 'EAN-13:', newLine: true);
$doc->write1DBarcode('4006381333931', BarcodeType::EAN13, x: 15, y: null, w: 60, h: 20);
$doc->ln(28);

// --- 2D barcodes ---
$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, '2D Barcodes', newLine: true);
$doc->ln(3);

$doc->setFont('helvetica', '', 10);
$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->ln(48);

$doc->cell(0, 6, 'DataMatrix:', newLine: true);
$doc->write2DBarcode('NextPDF-DM-2026', Barcode2DType::DataMatrix, x: 15, y: null, w: 30, h: 30);

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false ? $out : __DIR__ . '/barcodes.pdf');

echo "Wrote barcodes PDF (Code 128, EAN-13, QR Code, DataMatrix)\n";

Beklenen çıktı:

Wrote barcodes PDF (Code 128, EAN-13, QR Code, DataMatrix)

Sınır durumlar ve tuzaklar

Yük geçerliliği sembolojiye özgüdür. EAN13 12 veya 13 basamak bekler. Geçersiz yükte NextPDF, herhangi bir içerik yazmadan önce özel durum fırlatır. UPCA, ISBN ve ISSN, kendi uzunluk ve sağlama basamağı kurallarına sahiptir.
x/y isteğe bağlıdır. Bunları atladığınızda, barkod geçerli imleç konumuna yerleştirilir. Öngörülebilir yerleşim için açık koordinatlar geçirin.
w = 0 otomatik boyutlandırır. Genişliğin sıfır olması, kodlayıcının doğal bir modül genişliği seçmesini sağlar. Sabit bir kutuya sığdırmak için pozitif bir genişlik geçirin.
2D hata düzeltme düzeyi. write2DBarcode(), en düşük düzey olan ecLevel: 'L' değerini varsayılan kabul eder. Baskı hasarına dayanması gereken QR Code’lar için bu düzeyi yükseltin ('M', 'Q', 'H'). Daha yüksek düzeyler matrisi büyütür.
GS1 uygulama tanımlayıcıları. FNC1 ön ekine sahip GS1 yapılı veriler için gs1: true değerini write2DBarcode() yöntemine geçirin veya BarcodeType::GS1_128 kullanın.
Bir sayfa örtük olarak oluşturulur. addPage() öncesinde bir barkod yöntemi çağırdığınızda, NextPDF önce bir sayfa ekler. Bu kolaylık sunar; ancak sayfa geometrisi önemli olduğunda addPage() yöntemini açıkça çağırın.

Performans

Kodlama, 1D için O(yük uzunluğu) ve 2D için O(matris alanı) karmaşıklığındadır; her ikisi de mikrosaniye ölçeğinde çalışır. Her modül tek bir re … f yol işlecidir; bu nedenle yoğun bir QR Code, içerik akışına birkaç kilobayt ekler. Tarama (rasterizasyon) adımı yoktur; bu nedenle bellek, sembol boyutundan bağımsız olarak sabit kalır. Bu tarif, 1500 ms / 64 MB bütçesinin rahatça içinde kalır.

Güvenlik notları

Bir barkod, geçirdiğiniz herhangi bir yükü taşır; bu nedenle tüketen tarafta barkod değerini diğer tüm güvenilmeyen girdiler gibi ele alın. Kütüphane, yükü imzalamaz veya kimliğini doğrulamaz. Bir 2D sembol şifreleme değildir: tarayıcısı olan herkes onu okuyabilir.

Uyumluluk

İfade	Spesifikasyon	Madde
Barkod modülleri, dikdörtgen yol oluşturma işleciyle çizilir.	ISO 32000-2	§8.5
Code 128 sembol karakterleri, tanımlı bar/space öğe yapısını kullanır.	ISO/IEC 15417	§4.3.1
Data Matrix sembolleri, Reed-Solomon hata düzeltmesi kullanır.	ISO/IEC 16022	§7.6.1
QR Code verisi, hata düzeltme bloklarına bölünür.	ISO/IEC 18004	§7.5.2

NextPDF, söz konusu sembololoji kodlamalarını uygular; ancak barkod standartları için resmî sertifikasyon iddiasında bulunmaz. Barkod sembololojisi külliyatına ait belgeler, lisans bakımından Tier C ile sınırlandırılmıştır. Alıntılar yalnızca madde kimliği ve reference_id işaretçilerini kullanır; hiçbir standart metin yeniden üretilmez.