Barcode — Ausführliche Referenz

Auf einen Blick

Die Barcode-Oberfläche von NextPDF Pro ergänzt das Core-Barcode-Modul um spezialisierte 2D- und Lieferketten-Symbologien. Sie liefert sechs registry-aufgelöste 2D-Encoder (Micro QR, DotCode, Han Xin Code, JabCode, rMQR, GS1 DataBar), einen GS1-Composite-2D-Komponenten-Encoder (CC-C), den USPS-Intelligent-Mail-1D-Encoder sowie einen GS1-Application-Identifier-Parser samt Lieferketten-Validator. Die Kodierung ist deterministisch: Dieselbe Nutzlast und dieselben Optionen erzeugen stets eine identische Modulmatrix. Diese Seite benennt die öffentliche API, den Verhaltensvertrag, die Fehlermodi und die Konformitätsnachweise je Symbologie.

Verfügbarkeit & Lizenzierung

Diese Fähigkeit wird mit NextPDF Pro (nextpdf/pro) ausgeliefert und aktiviert sich mit einer Lizenzhülle der Pro-Stufe. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Fähigkeit nicht. Editionen vergleichen und eine Lizenz erwerben.

composer require nextpdf/pro:^3

Jede Symbologie bindet ihren eigenen Fähigkeitsnamen in der Lizenzhülle: barcode.microqr, barcode.dotcode, barcode.hanxin, barcode.jabcode, barcode.rmqr, barcode.gs1databar und barcode.gs1-composite-cc-c. Ist eine Fähigkeit nicht lizenziert, löst die Registry diesen Encoder nicht auf. Die Vollsymbol-Kodierung von GS1 Composite CC-A und CC-B wird nicht unterstützt (siehe die Support-Status-Tabelle), daher wird kein Schlüssel barcode.gs1-composite-cc-a oder barcode.gs1-composite-cc-b registriert.

Öffentliche API-Oberfläche

Die Registry-Schlüssel stammen aus den Case-Werten von Core NextPDF\Barcode\Barcode2DType zuzüglich des literalen Schlüssels gs1-composite-cc-c. Bei registry-aufgelösten Encodern ist der Registry-Schlüssel der stabile Vertrag, nicht der FQCN des Encoders.

Symbol	Parameter	Standardverhalten	Rückgabe	Löst aus oder scheitert mit	Hinweise
BarcodeProServiceProvider::register()	BarcodeEncoderRegistry $registry	Bindet alle sieben Pro-Registry-Schlüssel	void	—	Statisch; idempotent — ein zweiter Aufruf ersetzt die erste Bindung
MicroQrEncoder::encode()	$data; Optionen ecLevel ('L', 'M', 'Q'; Standard 'L'), version (1–4 oder null), mask (0–3 oder null)	Wählt automatisch die kleinste passende Version M1–M4	Barcode2DData	InvalidArgumentException	Nicht unterstütztes 'H' wird STILL auf 'L' überführt (Aufrufer, die eine fail-closed EC-Auswahl benötigen, müssen vorab validieren); M1 ignoriert ecLevel
DotCodeEncoder::encode()	$data; Optionen gs1 (bool, Standard false), columns (int), rows (int), ratio (float, Standard 1.5)	Automatische Gittergröße bei 1.5 Breite:Höhe	Barcode2DData	InvalidArgumentException	Gitterabmessungen können je Achse erzwungen werden
HanXinEncoder::encode()	$data; Optionen ecLevel (0–3, Standard 1), version (1–84, Standard automatisch)	Kleinste passende Version	Barcode2DData	InvalidArgumentException	GB-2312-Region-1/2-Textmodi gemäß ISO/IEC 20830
JabCodeEncoder::encode()	$data; Optionen colors (4, 8, 16, 32, 64, 128, 256; Standard 8), eccLevel (0–10, Standard 3), symbolNumber (1–61, Standard 1), symbolVersions, symbolPositions, symbolEccLevels	Einzelnes 8-Farben-Symbol	BarcodeColorData	InvalidArgumentException, JabCodeEncodingException	Polychrome Modulmatrix mit Palette
RmqrEncoder::encode()	$data; Optionen ecLevel (RmqrConstants::EC_M Standard, oder EC_H), version (z. B. 'R7x43', Standard automatisch)	Kleinste passende der 32 ISO/IEC-23941-Versionen	Barcode2DData	InvalidArgumentException	Weist Nutzlasten zurück, die die Kapazität übersteigen; kürzt niemals
Gs1DataBarEncoder::encode()	$data; Optionen variant (Gs1DataBarVariant, Standard OMNIDIRECTIONAL), linkage (bool, Standard false), height (int, Standard Variantenminimum; je Reihe bei Expanded Stacked), segmentsPerRow (int, Standard 4; nur Expanded Stacked)	Kodiert GTIN-Eingabe (§5/§6-Familie) oder eine GS1-AI-Elementzeichenkette (§7-Familie)	Barcode2DData	InvalidArgumentException; InvalidSymbolStructureException	Alle sieben ISO/IEC-24724-Annex-J-Varianten werden kodiert
Gs1DataBarVariant	—	isImplemented() gibt für alle sieben Cases true zurück	Enum (7 Cases)	—	minimumHeightX() und defaultHeightX() gemäß Annex J
ImbEncoder::encode()	string $code (20, 25, 29 oder 31 Ziffern)	65 Vier-Zustands-Balken	BarcodeData	InvalidArgumentException	1D-Encoder-Schnittstelle; kein 2D-Registry-Schlüssel
ImbEncoder::encodeToString()	string $code	Balkenzustände als T/A/D/F-Zeichenkette	string	InvalidArgumentException	Für Prüfungen gegen USPS-Referenzvektoren
Gs1DataParser::parse()	string $data	Erkennt automatisch Digital-Link-URIs, sonst Format (AI)value	Gs1ParsedData	InvalidArgumentException	Implementiert den Core-Vertrag Gs1DataParserInterface
Gs1DataParser::parseDigitalLink()	string $uri	Parst einen GS1-Digital-Link-URI	Gs1ParsedData	InvalidArgumentException	—
Gs1DataParser::encodeForCode128() / ::encodeForQrCode() / ::encodeForDataMatrix()	object $parsed	Byte-Sequenz des Trägers mit der FNC1-Konvention dieses Trägers	string	—	Erwartet eine Gs1ParsedData-Instanz
Gs1DataParser::validateAI()	string $ai, string $value	Strukturprüfung eines einzelnen AI-Werts	bool	—	—
Gs1Validator::validate()	string $barcodeData, Gs1SupplyChainProfile $profile (Standard NONE)	Statischer Schnellpfad über run()	Gs1ValidationResult	—	Parse-Fehler werden zu Findings, nicht zu Ausnahmen
Gs1Validator::run()	wie validate()	Parsen, Prüfziffern, Daten, AI-übergreifende Regeln, Profil	Gs1ValidationResult	—	Instanzpfad; der Konstruktor akzeptiert einen injizierten Parser
Gs1SupplyChainProfile	—	NONE überspringt Profilregeln	Enum (5 Cases)	—	RETAIL, FOOD, PHARMA, LOGISTICS, NONE; requiredAIs(), recommendedAIs(), primaryIdentifiers()
Gs1ValidationResult	—	Findings bei der Konstruktion nach Schweregrad partitioniert	readonly-Klasse	—	isValid, findings, errors, warnings, infos, parsedData; passes(), fails(), totalFindings()
Gs1ValidationFinding / Gs1FindingSeverity	—	severity, ruleId, message, optional ai und suggestion	readonly-Klasse / Enum	—	Schweregrade: Error, Warning, Info
CompositeComponentA::codewordsFor()	string $data	§5-Allzweck-Binärstring-Encodierung, Basis-928-Konvertierung, Round-Trip-Selbstprüfung	list<int> (jeweils 0–927)	InvalidArgumentException	Speist linkFor() oder einen externen CC-A-Träger-Renderer
CompositeComponentA::encode()	ignoriert	Verweigert die CC-A-Vollsymbol-Wiedergabe	—	UnsupportedBarcodeFeature (immer)	Fail-closed; siehe Randfälle
CompositeComponentB::encode()	ignoriert	Verweigert die CC-B-2D-Kodierung	—	UnsupportedBarcodeFeature (immer)	linkFor() bleibt verfügbar (CCSI 901)
CompositeComponentC::encode()	$data; Optionen an den PDF417-Träger weitergereicht; carrierType (Standard GS1_128)	Vollständiger PDF417-Träger mit vorangestelltem CCSI-Codewort 920	Barcode2DData	BarcodeException; CompositeLinkageException	Nur der Träger GS1_128 ist zulässig
CompositeComponent{A,B,C}::linkFor()	string $carrierId, array $codewords, CompositeCarrierType $carrierType	Paart Komponenten-Codewörter mit einem 1D-Träger	CompositeLinkage	CompositeLinkageException	Erzwingt Trägerzulässigkeit und Kapazität
CompositeVariant / CompositeCarrierType	—	CC_A, CC_B, CC_C; GS1_DATABAR, GS1_128	Enums	—	maxCodewords(), ccsi(), allowedCarriers(), usesFullPdf417()

Signaturen der Einstiegspunkte

public static function register(BarcodeEncoderRegistry $registry): void

public function encode(string $data, array $options = []): Barcode2DData

public static function validate(
    string $barcodeData,
    Gs1SupplyChainProfile $profile = Gs1SupplyChainProfile::NONE,
): Gs1ValidationResult

public function run(
    string $barcodeData,
    Gs1SupplyChainProfile $profile = Gs1SupplyChainProfile::NONE,
): Gs1ValidationResult

public function parse(string $data): Gs1ParsedData
public function parseDigitalLink(string $uri): Gs1ParsedData
public function encodeForCode128(object $parsed): string
public function encodeForQrCode(object $parsed): string
public function encodeForDataMatrix(object $parsed): string
public function validateAI(string $ai, string $value): bool

public function codewordsFor(string $data): array

Verhaltensvertrag

Registry-Auflösung

Die Standard-Registry-Factory von Core bindet die Pro-Encoder vorab als lazy, fähigkeitslizenzierte Einträge. BarcodeProServiceProvider::register() ist der unterstützte Fallback für Anwendungen, die eine Registry ohne Standardwerte zusammenstellen, etwa Framework-Integrationen mit eigenem Container. Jeder Encoder wandelt eine Zeichenketten-Nutzlast und symbologiespezifische Optionen in ein Barcode-Datenobjekt um, das der Seiten-Renderer in PDF-Inhaltsoperatoren überführt.

GS1-Parsing und -Validierung

Gs1DataParser akzeptiert menschenlesbare AI-Zeichenketten ((01)09521234543213(17)260131) und GS1-Digital-Link-URIs. Er erzeugt kodierte Byte-Sequenzen für die Träger GS1-128, QR Code und Data Matrix und wendet dabei die FNC1- und Gruppentrenner-Konvention jedes Trägers an. Gs1Validator durchläuft eine fünfstufige Pipeline: Parsen, Prüfziffern (GTIN, SSCC), Datumslogik, AI-übergreifende Regeln und branchenprofil-verpflichtende AIs. Ein Parse-Fehler liefert ein ungültiges Ergebnis mit Findings; er löst keine Ausnahme aus. Die Findings werden nach Schweregrad in Errors, Warnings und Infos partitioniert.

GS1-DataBar-Variantendispatch

Gs1DataBarEncoder::encode() dispatcht alle sieben ISO/IEC-24724:2011-Annex-J-Varianten über einen Optionsvertrag. Omnidirectional, Truncated, Stacked und Stacked Omnidirectional teilen sich die §5-Elementbreiten-Algebra mit einem Mod-79-Prüfzeichen. Limited nutzt seine eigene §6-Symbolzeichen-Algebra mit einem Mod-89-Prüfzeichen. Expanded und Expanded Stacked nutzen die §7-(17,4)-Algebra: die §7.2.5.5-Zustandsmaschine der drei Modi numerisch, alphanumerisch und ISO/IEC-646-Kompaktierung zuzüglich eines Mod-211-Prüfzeichens (§7.2.6). Die §5/§6-Familie nimmt eine 14-stellige GTIN-14 mit Mod-10-Prüfziffer oder eine 13-stellige Artikelkennung. Die §7-Familie nimmt eine rohe GS1-AI-Elementzeichenkette (Ziffern, Buchstaben, die ISO/IEC-646-Interpunktions-Teilmenge, FNC1 als Byte 0x1D). Die Option linkage setzt das 2D-Komponenten-Verknüpfungsflag zur Nutzung als lineare Komponente eines GS1-Composite-Symbols.

GS1-Composite-Komponenten

CC-C erzeugt eine vollständige 2D-Erweiterungskomponente über den vollständigen PDF417-Träger und injiziert das verpflichtende CCSI-Codewort 920 als führendes Daten-Codewort (ISO/IEC 24723:2010 §5.4). CC-A erzeugt konforme Basis-928-Daten-Codewörter über codewordsFor(), mit einer fail-closed Encode-Decode-Round-Trip-Selbstprüfung, verweigert aber die Vollsymbol-Wiedergabe. CC-B verweigert die 2D-Kodierung vollständig. linkFor() paart Komponenten-Codewörter mit einem 1D-Träger als CompositeLinkage-Wert und erzwingt dabei Trägerzulässigkeit und Kapazität.

Randfälle & Fehlermodi

• Jeder Encoder weist eine leere Nutzlast mit InvalidArgumentException zurück.
• Micro QR: Das Anfordern des nicht unterstützten Fehlerkorrekturniveaus H wird STILL auf L überführt, statt zu scheitern (validieren Sie die Optionen vorab, wenn Sie eine fail-closed EC-Auswahl benötigen), da ISO/IEC 18004 für Micro-QR-Symbole nur L, M und Q definiert.
• rMQR: Das Fehlerkorrekturniveau muss M oder H sein; eine Nutzlast, die die Kapazität der 32 Versionen übersteigt, wird zurückgewiesen, niemals gekürzt.
• JabCode: Eine Farbanzahl außerhalb der unterstützten Zweierpotenz-Menge, ein ECC-Niveau außerhalb 0–10 oder eine Symbolanzahl außerhalb 1–61 wird zurückgewiesen; nachgelagerte Kodierungsfehler lösen JabCodeEncodingException aus.
• GS1 DataBar: Die §5/§6-Familie validiert die GTIN-Mod-10-Prüfziffer, und Limited beschränkt die Indikatorziffer auf 0 oder 1. Die §7-Familie weist nicht kodierbare Zeichen sowie nachgestellte oder verdoppelte FNC1-Trenner zurück. Expanded Stacked weist eine ungerade Symbolzeichenanzahl je Reihe und Reihenhöhen unterhalb des 34X-Minimums zurück. Interne Strukturselbstprüfungen scheitern mit InvalidSymbolStructureException, statt ein fehlerhaftes Symbol auszugeben.
• GS1 Composite: encode() von CC-A und CC-B löst stets UnsupportedBarcodeFeature aus (fail closed). CC-C löst BarcodeException bei leeren Daten oder PDF417-Kapazitätsüberlauf (mehr als 925 Codewörter) und CompositeLinkageException bei einem unzulässigen Träger aus.
• GS1-Validierung meldet fehlerhafte AI-Struktur und falsche Prüfziffern vor der Kodierung; eine ungültige Lieferkettenzeichenkette erzeugt niemals ein scanbares, konformes Symbol.
• IMB akzeptiert nur 20-, 25-, 29- oder 31-stellige Eingaben.
• Die Barcode-Kodierung führt keine Kryptografie aus. Es gibt kein FIPS-modus-spezifisches Verhalten; die Encoder laufen unabhängig vom FIPS-Profil identisch.

Konformität

NextPDF implementiert diese Symbologien gegen die unten zitierten veröffentlichten Standards und fixiert Referenztraces in seiner Testsuite. Die Aussagen auf dieser Seite sind Fähigkeitsansprüche: Support ist keine Konformität, und Konformität ist keine Zertifizierung. NextPDF hält keine Symbologie-Zertifizierung. Die Klauselanker sind aus dem Produktquelltext und dessen Konformitätsfixtures paraphrasiert; das Compliance-Engine-Korpus deckt Barcode-Symbologie-Standards nicht ab, daher sind die Anker unten produktgestützt ohne Referenzkennungen.

Oberfläche	Standard	Klauselanker (paraphrasiert)
GS1-DataBar-Elementbreiten-Algebra	ISO/IEC 24724:2011	§5.2 Symbolzeichenstruktur; Annex F.1 durchgerechnetes Beispiel (Omnidirectional); Annex F.2 (Limited); Annex F.3 (Expanded)
GS1-DataBar-Stacked-Layouts	ISO/IEC 24724:2011	§5.4 Stacked; §5.5 Stacked Omnidirectional; §7.2.8 Expanded-Stacked-Reihenpartition und -Trenner
GS1-DataBar-Expanded-Encodierung	ISO/IEC 24724:2011	§7.2.5.5 Zustandsmaschine der drei Kompaktierungsmodi; §7.2.6 Mod-211-Prüfzeichen
GS1-Composite-Verknüpfung und CC-C	ISO/IEC 24723:2010	§5.4 CCSI-Codewort-Semantik; §5.1 Trägerzulässigkeit
GS1-Composite-CC-A-Codewörter	ISO/IEC 24723:2010	§5 Allzweck-Binärstring-Encodierung mit Basis-928-Konvertierung
rMQR-Symbolstruktur	ISO/IEC 23941:2022	§6.3.2 Tabelle 1 Versionsabmessungen; §7.8.2 feste Maske; Annex C / Annex I Formatinformations-Referenz
Micro QR	ISO/IEC 18004	Micro-QR-M1–M4-Kapazität und -Formatinformation
Han Xin Code	ISO/IEC 20830:2021	Symbolstruktur; Finder- und Ausrichtungsmuster; GB-2312-Region-1/2-Modi; Reed–Solomon-ECC; Maskierung
JabCode	ISO/IEC 23634	Symbol-, Farb- und ECC-Struktur
Postalische Symbologie	USPS-B-3200	Intelligent-Mail-Barcode-Feldstruktur

Support-Status je Symbologie

Eine Variante gilt als Verifiziert, wenn eine Fixture unter pro/tests/** sie ausübt, vorzugsweise ein Referenztrace, der an ein veröffentlichtes durchgerechnetes Beispiel angeheftet ist. Eine ausgelieferte Variante ohne dedizierte Fixture bleibt Behauptet. Eine Variante ohne Encoder ist Nicht unterstützt.

Symbologie / Variante	Status	Nachweis (Testpfad)	Hinweise
Micro QR (M1–M4)	Verifiziert	pro/tests/Unit/Barcode/MicroQrEncoderTest.php	Unit-Ebene; eine Referenztrace-Fixture mit durchgerechnetem Beispiel ist ein nachverfolgter Nachtrag
DotCode	Verifiziert	pro/tests/Unit/Barcode/DotCodeEncoderTest.php; DotCodeGfArithmeticTest.php	Galois-Feld-Arithmetik abgedeckt; kein Round-Trip mit Fremd-Decoder
Han Xin Code	Verifiziert	pro/tests/Unit/Barcode/HanXinEncoderTest.php; HanXinRsEncodingTest.php	Reed–Solomon-Kodierungspfad explizit ausgeübt
JabCode (1–61 Symbole, 4–256 Farben, ECC 0–10)	Verifiziert	pro/tests/Unit/Barcode/JabCode/JabCodeEncoderTest.php (+ 11 Komponenten-Suiten im selben Verzeichnis)	Mehrsymbol-Kaskade und ECC-Bereich ausgeübt; kein Round-Trip mit Fremd-Decoder
USPS Intelligent Mail Barcode	Verifiziert	pro/tests/Unit/Barcode/ImbEncoderTest.php; ImbRoutingCodeTest.php	Routing-Code- und 20/25/29/31-stellige Längenvalidierung ausgeübt
rMQR — alle 32 ISO/IEC-23941-Versionen	Verifiziert	pro/tests/Conformance/Barcode/Rmqr/AnnexValidatedSizesTest.php; RmqrAnnexCFormatInfoTest.php; pro/tests/Unit/Barcode/Rmqr/RmqrEncoderTest.php	Versions- und EC-Paare gegen ISO/IEC 23941 Tabelle 1 geprüft; Annex-C-/Annex-I-Formatinformations-Referenzwerte
GS1 DataBar — Omnidirectional / Truncated	Verifiziert	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarReferenceTest.php	Byte-gleich mit dem durchgerechneten Beispiel aus Annex F.1; Truncated teilt die Kodierung bei reduzierter Höhe
GS1 DataBar — Stacked / Stacked Omnidirectional	Verifiziert	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarStackedReferenceTest.php	Reihenaufteilung aus dem Annex-F.1-Trace abgeleitet; Trennerkonstruktion gemäß §5.4 und §5.5
GS1 DataBar — Limited	Verifiziert	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarLimitedReferenceTest.php; pro/tests/Unit/Barcode/Gs1DataBar/Gs1DataBarLimitedEncoderTest.php	Byte-gleich mit dem durchgerechneten Beispiel aus Annex F.2 (Artikel 00098765432105)
GS1 DataBar — Expanded	Verifiziert	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarExpandedReferenceTest.php; pro/tests/Integration/Barcode/Gs1DataBarExpandedTwoDecoderTest.php	Byte-gleich mit dem durchgerechneten Beispiel aus Annex F.3 ((10)12A); Round-Trip mit unabhängigem Decoder gegen zxing-cpp und ZBar
GS1 DataBar — Expanded Stacked	Verifiziert	pro/tests/Unit/Barcode/Gs1DataBar/Gs1DataBarExpandedEncoderTest.php (Stacked-Fälle); der obige Integrations-Round-Trip	Dieselbe Datenpipeline wie einreihiges Expanded; §7.2.8-Reihenpartition und -Trenner asserted
GS1 Composite — CC-C (PDF417-Träger)	Verifiziert	pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentCTest.php; CompositeRoundtripTest.php; CompositeLinkageTest.php	CCSI-Codewort 920 und Verknüpfungsflag-Zusammenspiel abgedeckt
GS1 Composite — CC-A	Teilweise	pro/tests/Unit/Barcode/Gs1Composite/CompositeComponentACodewordTest.php; pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentATest.php	Codewort-Erzeugung verifiziert (Basis-928, Round-Trip-Selbstprüfung); Vollsymbol-Wiedergabe nicht unterstützt — encode() scheitert fail-closed
GS1 Composite — CC-B	Nicht unterstützt	pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentBTest.php (assertiert fail-closed Zurückweisung)	Keine 2D-Kodierung; der Verknüpfungs-Helfer (CCSI 901) bleibt verfügbar
GS1-AI-Parser	Verifiziert	pro/tests/Unit/Barcode/Gs1DataParserTest.php; Gs1DataParserFnc1Test.php	Beide Eingabeformate und alle drei Träger-Byte-Sequenz-Ausgaben ausgeübt
GS1-Lieferketten-Validator	Verifiziert	pro/tests/Unit/Barcode/Gs1ValidatorTest.php; Gs1ValidatorCrossAiTest.php; pro/tests/Unit/Barcode/Gs1/Gs1ValidatorDateValidationEdgeCaseTest.php	Prüfziffern, AI-übergreifende Pflichtkombinationen und Datumslogik ausgeübt

Entwicklungshinweise

• Die Nachweisanker auf dieser Seite sind Testpfade unter pro/tests/**; das Repository liefert für dieses Modul kein examples/-Verzeichnis.
• Die sieben unter Verfügbarkeit & Lizenzierung aufgeführten Fähigkeitsnamen sind die Schlüssel, die der Service-Provider bindet. Der IMB-Encoder wird direkt konstruiert und trägt keinen Registry-Schlüssel.
• CC-A emittiert nur die Allzweck-Encodierungsmethode; die anwendungsspezifischen komprimierten Methoden sind ein dokumentierter Dichte-Residual, kein Korrektheitsmangel.

Publikationsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Helferklassen, Mechanismus-Tabellen, Runbook-Dateinamen und Ticket-Präfixe sind nicht Gegenstand dieser Seite.

Siehe auch

• Barcode-Fähigkeitsübersicht (NextPDF Pro)
• Chart — Ausführliche Referenz
• Core-Barcode-Modul