Barcode

Auf einen Blick

NextPDF Pro ergänzt spezielle 2D- und Lieferketten-Barcode-Symbologien über den linearen und QR-Symbologien der Open-Source-Edition. Jede Symbologie rendert direkt als deterministischer Content-Stream in eine PDF-Seitenoberfläche.

Verfügbarkeit & Lizenzierung

Diese Fähigkeit ist in NextPDF Pro (nextpdf/pro) enthalten und aktiviert sich mit einem Lizenzumschlag der Pro-Stufe. Ein Deployment ohne diese Berechtigung lädt die Klassen der Fähigkeit nicht. Editionen vergleichen und Lizenz erwerben.

Installation

composer require nextpdf/pro:^3

Die Pro-Encoder registrieren sich selbst über die Standard-Barcode-Encoder-Registry. Anwendungen, die ihre eigene Registry bauen, können die Pro-Encoder explizit über den veröffentlichten Service Provider neu registrieren.

Konzeptioneller Überblick

Die Open-Source-Edition deckt die alltäglichen linearen und QR-Symbologien ab. NextPDF Pro erweitert dieselbe Registry um spezielle Symbologien für den Einzelhandels-, Logistik-, Post- und hochdichten industriellen Einsatz:

• Micro QR Code — die kompakte QR-Variante für kleine Etikettenfläche.
• DotCode — eine Punktmatrix-Symbologie, ausgelegt für die industrielle Hochgeschwindigkeitskennzeichnung.
• Han Xin Code — eine 2D-Symbologie mit nativer CJK-Textkapazität für große Zeichensätze, gemäß ISO/IEC 20830.
• JabCode — eine polychrome 2D-Symbologie mit Mehr-Symbol-Kaskadierung.
• rMQR — die rechteckige Micro-QR-Variante für schmale, breite Etiketten.
• GS1 DataBar — die GS1-Symbologiefamilie für Einzelhandel und Coupons.
• GS1 Composite (CC-C) — eine verknüpfte 1D-Basis plus eine hochdichte PDF417-2D-Erweiterungskomponente, die GS1-Application-Identifier-Daten trägt. (Das CC-A- und CC-B-2D-Erweiterungskomponenten-Encoding wird in diesem Release nicht unterstützt; siehe die Support-Matrix.)

Jeder Encoder erzeugt ein Barcode-Datenobjekt, das der Seiten-Renderer in PDF-Content-Operatoren umwandelt. Das Encoding ist deterministisch: Dieselbe Eingabe und dieselben Optionen erzeugen stets dasselbe Modulmuster, was signierte und archivierte Dokumente reproduzierbar hält.

Die Barcode-Tiefenreferenz trägt eine Support-Matrix pro Symbologie mit Evidenz. Für jede Symbologie und Variante erfasst die Matrix einen von drei Zuständen: Eine Konformitäts-Fixture im Repository übt sie aus (Verified), die Implementierungsoberfläche behauptet sie ohne eine dedizierte Fixture (Claimed) oder sie fällt aus dem Umfang (Not supported). NextPDF meldet die Matrix ehrlich: Eine Variante, die einen Encoder ausliefert, aber keine Referenz-Trace-Fixture hat, bleibt Claimed mit einem Backfill-Hinweis, statt überzeichnet zu werden.

Warum es so funktioniert

Jeder Pro-Encoder ist eine reine Funktion: Dieselbe Payload und dieselben Optionen erzeugen stets dieselbe Modulmatrix, ohne verborgenen Zustand oder geseedete Zufälligkeit. Dieser Determinismus ist die tragende Entscheidung. Er lässt einen Barcode einen Roundtrip durch ein signiertes oder archiviertes Dokument durchlaufen, ohne den Byte-Stream zu stören, sodass ein Re-Render eine Signatur nie ungültig macht. Er macht die Konformität außerdem auditierbar: Die Support-Matrix pinnt jede Symbologie an einen gespeicherten Referenz-Trace, Bit für Bit gegen eine Golden-Datei geprüft. Die Erweiterung der Core-BarcodeEncoderRegistry, statt sie zu forken, hält diese Garantien über die Open- und Pro-Editionen hinweg identisch.

Design-Hintergrund: The same bytes every time: reproducible PDFs.

API-Oberfläche

composer require nextpdf/pro:^3

Die öffentliche Pro-Barcode-Oberfläche besteht aus:

• Einem statischen Service-Provider-Einstiegspunkt, der die Pro-2D-Encoder in eine Barcode-Encoder-Registry registriert (MicroQR, DotCode, HanXin, JabCode, RMQR, GS1DataBar und den GS1-Composite-CC-C-Komponentenschlüssel gs1-composite-cc-c). Das GS1-Composite-CC-A- und CC-B-2D-Erweiterungskomponenten-Encoding wird in diesem Release nicht unterstützt und nicht registriert.
• Einem GS1-Application-Identifier-Parser, der sowohl menschenlesbare AI-Strings als auch GS1-Digital-Link-URIs akzeptiert und encodete Byte-Sequenzen für GS1-128-, QR-Code- und Data-Matrix-Träger erzeugt.
• Einem GS1-Lieferketten-Validator, der Prüfziffern, AI-Struktur, Datumslogik und die für ein Branchenprofil verpflichtenden AI-Kombinationen prüft.

Die vollständige generierte Methoden-Signatur-Tabelle rendert in der Barcode-Tiefenreferenz.

Codebeispiel — Schnellstart

use NextPDF\Barcode\BarcodeEncoderRegistry;
use NextPDF\Pro\Barcode\BarcodeProServiceProvider;

$registry = new BarcodeEncoderRegistry();
BarcodeProServiceProvider::register($registry);
// $registry now resolves the Pro specialty symbologies.

Codebeispiel — Produktion

use NextPDF\Pro\Barcode\Gs1\Gs1Validator;
use NextPDF\Pro\Barcode\Gs1\Gs1SupplyChainProfile;

$result = Gs1Validator::validate(
    '(01)09521234543213(17)260131(10)ABC123',
    Gs1SupplyChainProfile::NONE,
);

if (! $result->isValid) {
    // Surface findings to your observability pipeline before encoding.
    foreach ($result->findings as $finding) {
        $logger->warning('GS1 validation finding', [
            'rule' => $finding->ruleId,
            'detail' => $finding->message,
        ]);
    }
}

Sonderfälle & Fallstricke

• Die Standard-Registry bindet die Pro-Encoder-Einträge lazy vor und gated sie über die Capability-Registry. Ein expliziter BarcodeProServiceProvider::register()-Aufruf ist der unterstützte Fallback, wenn eine Anwendung ihre eigene Registry ohne Defaults zusammenstellt.
• Die Neuregistrierung ist idempotent: Ein zweiter register()-Aufruf ersetzt die erste Bindung, statt auszulösen.
• Die GS1-DataBar-Variantenabdeckung ist designbedingt teilweise. Omnidirectional, Truncated, Stacked, Stacked Omnidirectional und Limited sind referenzverifiziert; Expanded und Expanded Stacked liegen in diesem Release außerhalb des Umfangs. Siehe die Support-Matrix.
• rMQR akzeptiert jede ISO-23941-Version über die Annex-validierte Konformitäts-Suite. Scope-Tracking-Metadaten, die der späteren Größenbereichserweiterung vorausgehen, können dies untertreiben; die Support-Matrix erfasst die code-verifizierte Realität.

Performance

Die Encoding-Kosten skalieren mit der Payload-Länge und der Zielsymbolgröße. Jede Symbologie legt ihr Symbol in einem einzigen Durchlauf ohne Reflow aus. JabCode-Mehr-Symbol-Kaskaden skalieren mit der Symbolanzahl (1–61). Das Encoding hält die Modulmatrix im Speicher; die größte gewählte Symbolversion begrenzt die Kosten.

Sicherheitshinweise

Barcode-Encoder führen Payload-Inhalt nicht aus; sie encoden ihn als Daten. Die GS1-Validierung lehnt fehlerhafte AI-Strukturen und ungültige Prüfziffern vor dem Encoding ab, was verhindert, dass ein fehlerhafter Lieferketten-String ein scanbares, aber nicht-konformes Symbol erzeugt. Die Encoder protokollieren selbst keinen Payload; Anwendungen müssen sensible Payloads aus ihren eigenen Logs bereinigen.

Konformität

Jede Symbologie folgt ihrem relevanten veröffentlichten Standard (ISO/IEC 24724 für GS1 DataBar, ISO/IEC 24723 für GS1 Composite, ISO/IEC 23941 für rMQR, ISO/IEC 18004 Annex für Micro QR, ISO/IEC 20830 für Han Xin Code, ISO/IEC 23634 für JabCode, USPS-B-3200 für die Post-Symbologie). Die klausel-genaue Konformitätszuordnung mit Zitat-Identifikatoren rendert in der Barcode-Tiefenreferenz.

Publikationsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismustabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Umfangs.

Siehe auch

• Core-Barcode-Modul
• Chart — NextPDF Pro
• Barcode-Tiefenreferenz