Generowanie kodów kreskowych 1D i 2D w pliku PDF

W skrócie

Ten przepis pokazuje, jak rysować jednowymiarowe (1D) i dwuwymiarowe (2D) kody kreskowe bezpośrednio na stronie dokumentu Portable Document Format (PDF). Cecha (trait) HasBarcodes w Core udostępnia metody write1DBarcode() oraz write2DBarcode(). Obie rysują symbol za pomocą natywnych operatorów ścieżki PDF na bieżącej stronie, więc wynikiem jest zwykła, deterministyczna treść wektorowa. Przepis opiera się na examples/10-barcodes.php.

Instalacja

composer require nextpdf/core:^3

Nie jest potrzebne dodatkowe rozszerzenie. Enkodery kodów kreskowych są napisane w czystym PHP, a NextPDF rysuje symbole za pomocą standardowego operatora prostokąta PDF (ISO 32000-2 §8.5).

Omówienie koncepcyjne

Kod kreskowy jest rysowany, a nie osadzany jako obraz. Ładunek (payload) oznacza dane, które kodujesz, na przykład numer produktu lub adres internetowy.

write1DBarcode() koduje ładunek jako wzorzec kresek i odstępów (bar/space) dla wybranego typu BarcodeType, a następnie emituje sekwencję wypełnionych prostokątów. write2DBarcode() buduje macierz modułów dla wybranego typu Barcode2DType i emituje jeden wypełniony prostokąt dla każdego ciemnego modułu. Data Matrix i QR Code stosują korekcję błędów Reeda-Solomona, dzięki czemu skaner może odzyskać dane nawet wtedy, gdy część symbolu jest uszkodzona.

Każdy moduł jest deterministyczną ścieżką re … f bez źródła entropii, więc treść samego kodu kreskowego jest w pełni odtwarzalna. Profil odtwarzalności to structural, ponieważ otaczający dokument nadal zawiera elementy zależne od zapisu: trailer /ID oraz znaczniki czasu /CreationDate i /ModDate. Środowisko testowe (harness) porównuje strukturę znormalizowaną przez qpdf po usunięciu tych elementów.

Zakres API

NextPDF\Core\Concerns\HasBarcodes (trait dołączany do Document):

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

Symbolika (symbology) oznacza standard kodu kreskowego definiujący, jak dane są zamieniane na kreski lub moduły. BarcodeType zawiera symboliki 1D (C128, EAN13, UPCA, I25, CODABAR, ISBN, GS1_128, …), a Barcode2DType zawiera symboliki 2D (QRCode, DataMatrix, PDF417, HanXin, MicroQR, …).

Przykład kodu — szybki start

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

Przykład kodu — wersja produkcyjna

Poniższy kompletny przykład, gotowy do uruchomienia w środowisku testowym, odzwierciedla examples/10-barcodes.php. Zapisuje plik PDF pod ścieżką, którą środowisko testowe przekazuje przez NEXTPDF_COOKBOOK_OUTPUT, a przy ręcznym uruchomieniu używa pliku lokalnego. Środowisko testowe odtwarzalności może potem uruchomić przykład dwukrotnie i potwierdzić identyczność strukturalną. Porównanie korzysta ze struktury znormalizowanej przez qpdf po usunięciu zależnych od zapisu elementów /ID oraz znaczników czasu.

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

Oczekiwany wynik:

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

Przypadki brzegowe i pułapki

Poprawność ładunku zależy od symboliki. EAN13 oczekuje 12 lub 13 cyfr. Nieprawidłowy ładunek powoduje zgłoszenie wyjątku, zanim NextPDF zapisze jakąkolwiek treść. UPCA, ISBN i ISSN mają własne reguły dotyczące długości i cyfry kontrolnej.
Parametry x/y są opcjonalne. Po ich pominięciu kod kreskowy zostaje umieszczony w bieżącej pozycji kursora. Podaj jawne współrzędne, aby uzyskać przewidywalny układ.
Wartość w = 0 dobiera rozmiar automatycznie. Zerowa szerokość pozwala enkoderowi wybrać naturalną szerokość modułu. Ustaw dodatnią szerokość, aby zmieścić kod w polu o stałym rozmiarze.
Poziom korekcji błędów 2D. write2DBarcode() domyślnie używa ecLevel: 'L', czyli najniższego poziomu. Zwiększ go ('M', 'Q', 'H') dla kodów QR, które muszą pozostać czytelne mimo uszkodzeń w druku. Wyższe poziomy powiększają macierz.
Identyfikatory aplikacji GS1. Przekaż gs1: true do write2DBarcode() albo użyj BarcodeType::GS1_128 dla danych w strukturze GS1 z prefiksem FNC1.
Strona jest tworzona automatycznie. Gdy wywołasz metodę rysującą kod kreskowy przed addPage(), NextPDF najpierw doda stronę. To wygodne, ale wywołaj addPage() jawnie, gdy geometria strony ma znaczenie.

Wydajność

Kodowanie ma złożoność O(długość ładunku) dla 1D oraz O(pole macierzy) dla 2D; oba warianty działają w czasie rzędu mikrosekund. Każdy moduł to jeden operator ścieżki re … f, więc gęsty kod QR dodaje do strumienia treści kilka kilobajtów. Nie występuje etap rasteryzacji, dlatego zużycie pamięci pozostaje stałe niezależnie od rozmiaru symbolu. Przepis mieści się z dużym zapasem w budżecie 1500 ms / 64 MB.

Uwagi dotyczące bezpieczeństwa

Kod kreskowy przenosi dowolny ładunek, który przekażesz, więc po stronie odczytującej traktuj wartość kodu kreskowego jak każde inne niezaufane dane wejściowe. Biblioteka nie podpisuje ani nie uwierzytelnia ładunku. Symbol 2D nie szyfruje danych: każdy, kto ma skaner, może odczytać jego zawartość.

Zgodność

Stwierdzenie	Specyfikacja	Klauzula
Moduły kodu kreskowego są rysowane operatorem konstruowania ścieżki prostokąta.	ISO 32000-2	§8.5
Znaki symboli Code 128 wykorzystują zdefiniowaną strukturę elementów bar/space.	ISO/IEC 15417	§4.3.1
Symbole Data Matrix wykorzystują korekcję błędów Reeda-Solomona.	ISO/IEC 16022	§7.6.1
Dane kodu QR są dzielone na bloki korekcji błędów.	ISO/IEC 18004	§7.5.2

NextPDF implementuje cytowane kodowania symbolik, ale nie deklaruje formalnej certyfikacji zgodności ze standardami kodów kreskowych. Dokumenty korpusu symbolik kodów kreskowych mają licencję ograniczoną do poziomu Tier C. Cytaty używają wyłącznie wskaźników clause-id i reference_id, a żaden tekst standardu nie jest odtwarzany.