Barcode: Encoder für 1D- und 2D-Symbologien

Auf einen Blick

Das Barcode-Modul bildet die Implementierungs-Schicht für Symbologien. Es kodiert lineare Symbologien (Code 128, EAN, UPC, Interleaved 2 of 5, Codabar, Postleitzahlen) und Matrix-Symbologien (QR Code, Data Matrix, PDF417) und berechnet die zugehörige Fehlerkorrektur. Außerdem registriert es jeden Encoder hinter den Barcode-Verträgen, damit der Document-Writer das Ergebnis zeichnen kann. Die Definitionen dieser Verträge stehen auf einer separaten Seite; beachten Sie den Hinweis unten.

Eine kanonische Seite pro Belang. Die Schnittstellen, die ein Encoder erfüllt (Barcode1DEncoderInterface, Barcode2DEncoderInterface, BarcodeEncoderInterface, Gs1DataParserInterface) sind dokumentiert auf Contracts / Barcode. Diese Seite dokumentiert die konkreten Encoder, die diese Verträge implementieren. Beide Seiten ergänzen einander; sie sind keine Duplikate. Lesen Sie die Vertragsseite für die SPI und diese Seite für die Symbologien.

Installation

composer require nextpdf/core:^3

Konzeptioneller Überblick

Ein Barcode-Encoder wandelt eine Payload-Zeichenkette in eine Modulmatrix (2D) oder eine Balkensequenz (1D) um, die der Writer anschließend als PDF-Grafik zeichnet. Dieses Modul stellt die konkreten Encoder bereit.

Barcode1D ist die lineare Engine. BarcodeType zählt die unterstützten linearen Symbologien auf — Code 39 (mit und ohne Prüfsumme), Code 93, die Code-128-Familie, EAN-8/EAN-13, UPC-A/UPC-E, Interleaved und Standard 2 of 5, Codabar, Code 11, POSTNET, PLANET, Intelligent Mail (IMB) und MSI. generate() gibt ein BarcodeData-Value-Object zurück, das das Balkenmuster beschreibt.

Die 2D-Encoder — QrEncoder, DataMatrixEncoder, Pdf417Encoder — implementieren BarcodeEncoderInterface und geben eine Barcode2DData-Matrix zurück. Barcode2DType zählt die Matrix-Symbologien auf, die die Engine erkennt, darunter QR Code, Data Matrix und PDF417. Weitere Symbologien wie Micro QR, rMQR, GS1 DataBar und Han Xin sind für das Registry-Routing aufgeführt. Welche davon durch Encoder unterstützt werden, hängt von der Edition ab. Die Matrix-Fehlerkorrektur wird über ein Galois-Feld berechnet. GaloisField und GaloisFieldPrime stellen die Reed-Solomon-Arithmetik bereit, die sich die Encoder für QR, Data Matrix und PDF417 teilen.

BarcodeEncoderRegistry ist die Lookup-Instanz. Sie implementiert PSR-11 ContainerInterface, liefert über createDefault() eine Standardregistrierung und löst eine Symbologie mit resolve() zu ihrem Encoder auf. Anwendungscode greift selten direkt auf einen Encoder zu. Die übergeordnete Document::write1DBarcode()- / write2DBarcode()-Fassade gibt eine Symbologie an, und die Registry liefert den passenden Encoder. Die 1D-Engine ist @since 1.0.0. Die 2D-Encoder sind @since 1.3.0. Die Registry ist @since 3.0.0.

API-Oberfläche

Klasse	Wesentliche Member	Rolle
Barcode1D	generate(string $code, BarcodeType $type): BarcodeData	Encoder für lineare Symbologien (@since 1.0.0)
QrEncoder	encode(string $data, array $options = []): Barcode2DData	QR-Code-Encoder (@since 1.3.0)
DataMatrixEncoder	encode(string $data, array $options = []): Barcode2DData	Data-Matrix-Encoder (@since 1.3.0)
Pdf417Encoder	encode(string $data, array $options = []): Barcode2DData	PDF417-Encoder (@since 1.3.0)
BarcodeEncoderRegistry	createDefault(), register(), resolve(), has(), get(), registered()	PSR-11-Encoder-Registry (@since 3.0.0)
BarcodeType / Barcode2DType	enum-Fälle	Aufzählungen der unterstützten Symbologien
GaloisField / GaloisFieldPrime	Arithmetik über endlichen Körpern	Reed-Solomon-Fehlerkorrektur

Führen Sie composer docs:generate-api-php -- --module=Barcode aus, um die vollständige PHPDoc-Tabelle zu erzeugen.

Codebeispiel — Schnellstart

Quelle: examples/10-barcodes.php. Die Fassade löst anhand der Symbologie einen Encoder über die Registry auf.

<?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');

Codebeispiel — Produktion

Lösen Sie einen 2D-Encoder direkt über die Registry auf und begrenzen Sie die Payload vor dem Kodieren.

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

Sonderfälle & Fallstricke

• Eine lineare Payload, die den Zeichensatz oder die Prüfzifferregel einer Symbologie verletzt, löst BarcodeException aus. EAN/UPC berechnen die Prüfziffer und hängen sie an. Hängen Sie sie nicht vorab an.
• Das 2D-$options-Array ist symbologiespezifisch (zum Beispiel ein Fehlerkorrekturlevel für QR). Unbekannte Schlüssel werden von den meisten Encodern ignoriert. Prüfen Sie den Schlüssel anhand der jeweiligen Encoder-Dokumentation.
• Die Core-Edition liefert nicht für alle in Barcode2DType aufgezählten Symbologien Encoder mit. BarcodeEncoderRegistry::resolve() löst bei einer nicht registrierten Symbologie eine Ausnahme aus, statt einen Platzhalter zurückzugeben.
• Registrierte Encoder sind gemeinsam genutzte Instanzen. Abgesehen von der Konstruktor-Konfiguration müssen sie zustandslos bleiben. Aufrufspezifischer Zustand beschädigt nebenläufige Renderings.
• Eine zu lange Payload erzeugt eine dichtere, größere Matrix. Begrenzen Sie die Payload-Länge vor dem Kodieren, um einen Denial-of-Service-Angriff über die Symbolgröße zu vermeiden.

Performance

Der Kodierungsaufwand skaliert mit der Payload-Länge und der Matrixgröße, nicht mit dem Registry-Lookup, der O(1) ist. Eine kurze Code-128-Payload wird in Mikrosekunden kodiert. Ein dichter QR Code mit hoher Fehlerkorrektur ist der schwerste Fall. Er bleibt für die Beispielseite mit mehreren Symbolen innerhalb des Budgets von 1500 ms Wall-Time / 64 MB Spitzenspeicher. Das Reproduzierbarkeitsprofil ist bitwise. Dieselbe Payload und dieselben Optionen erzeugen immer dieselbe Modulmatrix und dieselben gezeichneten Bytes.

Sicherheitshinweise

Barcode-Payloads werden häufig von Angreifern beeinflusst — etwa eine gescannte URL, eine Seriennummer oder ein Tracking-Code. Die Encoder kodieren Bytes. Sie interpretieren sie nicht. Ein QR Code, der eine bösartige URL kodiert, ist weiterhin ein gültiger QR Code; daher liegt die Vertrauenswürdigkeit der Payload in der Verantwortung des Konsumenten. Begrenzen Sie die Payload-Länge vor dem Kodieren, um die Matrixgröße — und damit Aufwand und Ausgabegröße — innerhalb eines Budgets zu halten. Behandeln Sie alle Daten, die an anderer Stelle aus einem Barcode dekodiert wurden, als nicht vertrauenswürdige Eingabe, wenn sie wieder in die Anwendung gelangen. Siehe das Bedrohungsmodell der Engine unter /modules/core/security/.

Konformität

Aussage	Standard	Referenz
QR-Code-Symbole folgen der Spezifikation der QR-Code-Matrix-Symbologie.	ISO/IEC 18004	QR-Code-Symbologie
Data-Matrix-Symbole folgen der Spezifikation der Data-Matrix-Symbologie.	ISO/IEC 16022	Data-Matrix-Symbologie
PDF417-Symbole folgen der Spezifikation der PDF417-Symbologie.	ISO/IEC 15438	PDF417-Symbologie
Code-128-Symbole folgen der Spezifikation der linearen Code-128-Symbologie.	ISO/IEC 15417	Code-128-Symbologie
EAN/UPC-Symbole folgen der Spezifikation der EAN/UPC-Symbologie.	ISO/IEC 15420	EAN/UPC-Symbologie

Diese Symbologie-Standards sind nicht im verifizierbaren Zitationskorpus vorhanden; daher wird keine reference_id erfasst. Die Engine paraphrasiert die Anforderung und zitiert die Quelle anhand von Nummer und Klausel. Ziehen Sie für verbindliche Kodierungsregeln die veröffentlichten Standards heran. Die Encoder werden durch tests/Unit/Barcode/ geprüft. Die Korrektheit gegenüber den Symbologie-Spezifikationen liegt in der Verantwortung der Test-Suite und ist keine Aussage über die End-to-End-PDF-Konformität.

Siehe auch

• Contracts / Barcode — die Encoder-Schnittstellen, die diese Klassen implementieren (die SPI).
• Graphics-Modul — die Zeichenschicht, die die kodierte Matrix zeichnet.
• Document-Modul — die übergeordnete write1DBarcode()- / write2DBarcode()-Fassade.
• Konformitäts-Überblick
• Sicherheitsmodell der Engine