1D- und 2D-Barcodes in einem PDF erzeugen

Auf einen Blick

Mit diesem Recipe zeichnen Sie 1D- und 2D-Barcodes direkt auf eine PDF-Seite. Der Core-Trait HasBarcodes stellt Ihnen write1DBarcode() und write2DBarcode() bereit. Beide zeichnen das Symbol als native PDF-Pfadoperatoren auf die aktuelle Seite, sodass die Ausgabe einfacher, deterministischer Vektorinhalt ist. Das Recipe orientiert sich an examples/10-barcodes.php.

Installation

composer require nextpdf/core:^3

Sie benötigen keine zusätzliche Erweiterung. Die Barcode-Encoder sind in reinem PHP implementiert, und die Symbole werden mit dem Standard-Rechteckoperator von PDF gezeichnet (ISO 32000-2 §8.5).

Konzeptioneller Überblick

Ein Barcode wird gezeichnet, nicht als Bild eingebettet. Die Payload besteht aus den Daten, die Sie kodieren, etwa einer Produktnummer oder einer Webadresse.

write1DBarcode() kodiert die Payload in ein bar/space-Muster für den gewählten BarcodeType und gibt anschließend eine Folge gefüllter Rechtecke aus. write2DBarcode() baut eine Modulmatrix für den gewählten Barcode2DType auf und gibt pro dunklem Modul ein gefülltes Rechteck aus. Data Matrix und QR Code nutzen Reed-Solomon-Fehlerkorrektur, sodass ein Scanner die Daten selbst dann wiederherstellen kann, wenn ein Teil des Symbols beschädigt ist.

Jedes Modul wird als deterministischer re … f-Pfad ohne Entropiequelle ausgegeben, sodass der Barcode-Inhalt selbst vollständig reproduzierbar ist. Das Reproduzierbarkeitsprofil ist structural, weil das umgebende Dokument weiterhin pro Speichervorgang Atome enthält: das Trailer-/ID sowie die Zeitstempel /CreationDate und /ModDate. Der Harness vergleicht die qpdf-normalisierte Struktur mit entfernten Atomen.

API-Oberfläche

NextPDF\Core\Concerns\HasBarcodes (eingebunden in 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

Eine Symbologie ist ein Barcode-Standard, der festlegt, wie Daten in Balken oder Module umgesetzt werden. BarcodeType listet die 1D-Symbologien auf (C128, EAN13, UPCA, I25, CODABAR, ISBN, GS1_128, …), und Barcode2DType listet die 2D-Symbologien auf (QRCode, DataMatrix, PDF417, HanXin, MicroQR, …).

Code-Beispiel — Schnellstart

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

Code-Beispiel — Produktion

Das vollständige Beispiel unten ist im Harness lauffähig und entspricht examples/10-barcodes.php. Es schreibt das PDF in den Pfad, den der Harness über NEXTPDF_COOKBOOK_OUTPUT liefert, und greift auf eine lokale Datei zurück, wenn Sie es manuell ausführen. Der Reproduzierbarkeits-Harness kann es dann zweimal ausführen und die strukturelle Identität bestätigen. Die Struktur ist qpdf-normalisiert, wobei die Atome je Speichervorgang — /ID und Zeitstempel — entfernt sind.

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

Erwartete Ausgabe:

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

Sonderfälle & Stolperfallen

Die Gültigkeit der Payload ist symbologiespezifisch. EAN13 erwartet 12 oder 13 Ziffern. Eine ungültige Payload löst eine Ausnahme aus, bevor irgendein Inhalt geschrieben wird. UPCA, ISBN und ISSN haben eigene Längen- und Prüfziffernregeln.
x/y sind optional. Wenn Sie sie weglassen, wird der Barcode an der aktuellen Cursorposition platziert. Übergeben Sie explizite Koordinaten für ein vorhersehbares Layout.
w = 0 skaliert automatisch. Eine Breite von null lässt den Encoder eine natürliche Modulbreite wählen. Übergeben Sie eine positive Breite, um den Barcode in eine feste Box einzupassen.
2D-Fehlerkorrekturstufe. write2DBarcode() verwendet standardmäßig ecLevel: 'L', die niedrigste Stufe. Erhöhen Sie sie ('M', 'Q', 'H') für QR Codes, die Druckschäden überstehen müssen. Höhere Stufen vergrößern die Matrix.
GS1-Anwendungsbezeichner. Übergeben Sie gs1: true an write2DBarcode() oder verwenden Sie BarcodeType::GS1_128 für GS1-strukturierte Daten mit dem FNC1-Präfix.
Eine Seite wird implizit angelegt. Wenn Sie eine Barcode-Methode vor addPage() aufrufen, fügt NextPDF zuerst eine Seite hinzu. Das ist praktisch; rufen Sie addPage() jedoch explizit auf, wenn die Seitengeometrie wichtig ist.

Performance

Die Kodierung ist O(Payload-Länge) bei 1D und O(Matrixfläche) bei 2D, und beide liegen im Mikrosekundenbereich. Jedes Modul ist ein einziger re … f-Pfadoperator, sodass ein dichter QR Code einige Kilobyte zum Content-Stream hinzufügt. Es gibt keinen Rasterisierungsschritt, sodass der Speicherbedarf unabhängig von der Symbolgröße konstant bleibt. Das Recipe bleibt deutlich innerhalb des Budgets von 1500 ms / 64 MB.

Sicherheitshinweise

Ein Barcode trägt genau die Payload, die Sie übergeben. Behandeln Sie einen Barcode-Wert auf der auswertenden Seite daher genauso wie jede andere nicht vertrauenswürdige Eingabe. Die Bibliothek signiert oder authentifiziert die Payload nicht. Ein 2D-Symbol ist keine Verschlüsselung: Jeder mit einem Scanner kann es lesen.

Konformität

Aussage	Spezifikation	Abschnitt
Barcode-Module werden mit dem Rechteck-Pfadkonstruktionsoperator gezeichnet.	ISO 32000-2	§8.5
Code-128-Symbolzeichen verwenden die definierte bar/space-Elementstruktur.	ISO/IEC 15417	§4.3.1
Data-Matrix-Symbole nutzen Reed-Solomon-Fehlerkorrektur.	ISO/IEC 16022	§7.6.1
QR-Code-Daten werden in Fehlerkorrekturblöcke aufgeteilt.	ISO/IEC 18004	§7.5.2

NextPDF implementiert die zitierten Symbologiekodierungen, behauptet aber keine formale Zertifizierung nach den Barcode-Standards. Die Korpusdokumente zur Barcode-Symbologie sind lizenzbedingt auf Stufe C begrenzt. Die Zitate bestehen ausschließlich aus Clause-ID- und reference_id-Verweisen; Standardtext wird nicht wiedergegeben.