Barcode — Diepe referentie

In één oogopslag

Het NextPDF Pro barcode-oppervlak voegt specialistische 2D- en supply-chain-symbologieën toe bovenop de Core-barcodemodule. Het levert zes via de registry geresolveerde 2D-encoders (Micro QR, DotCode, Han Xin Code, JabCode, rMQR, GS1 DataBar), één GS1 Composite 2D-componentencoder (CC-C), de USPS Intelligent Mail 1D-encoder en een GS1 Application Identifier-parser plus supply-chain-validator. Encodering is deterministisch: dezelfde payload en opties produceren altijd een identieke modulematrix. Deze pagina benoemt de publieke API, het gedragscontract, de faalmodi en het conformiteitsbewijs per symbologie.

Beschikbaarheid en licentiëring

Deze capaciteit wordt geleverd in NextPDF Pro (nextpdf/pro) en activeert met een license-envelope op Pro-niveau. Een deployment zonder dat recht laadt de klassen van de capaciteit niet. Vergelijk edities en verkrijg een licentie.

composer require nextpdf/pro:^3

Elke symbologie bindt zijn eigen capaciteitsnaam in de license-envelope: barcode.microqr, barcode.dotcode, barcode.hanxin, barcode.jabcode, barcode.rmqr, barcode.gs1databar en barcode.gs1-composite-cc-c. Wanneer een capaciteit niet is gelicentieerd, resolveert de registry die encoder niet. GS1 Composite CC-A- en CC-B-full-symbol-encodering wordt niet ondersteund (zie de ondersteuningsstatustabel), dus er wordt geen barcode.gs1-composite-cc-a- of barcode.gs1-composite-cc-b-sleutel geregistreerd.

Publiek API-oppervlak

Registry-sleutels komen uit de case-waarden van de Core NextPDF\Barcode\Barcode2DType plus de letterlijke sleutel gs1-composite-cc-c. Voor via de registry geresolveerde encoders is de registry-sleutel het stabiele contract, niet de FQCN van de encoder.

Symbool	Parameters	Standaardgedrag	Retourneert	Werpt of faalt met	Notities
BarcodeProServiceProvider::register()	BarcodeEncoderRegistry $registry	Bindt alle zeven Pro-registry-sleutels	void	—	Statisch; idempotent — een tweede aanroep vervangt de eerste binding
MicroQrEncoder::encode()	$data; opties ecLevel ('L', 'M', 'Q'; standaard 'L'), version (1–4 of null), mask (0–3 of null)	Kiest automatisch de kleinste passende versie M1–M4	Barcode2DData	InvalidArgumentException	Niet-ondersteund 'H' wordt STILZWIJGEND naar 'L' gedwongen (callers die fail-closed EC-selectie nodig hebben, moeten vooraf valideren); M1 negeert ecLevel
DotCodeEncoder::encode()	$data; opties gs1 (bool, standaard false), columns (int), rows (int), ratio (float, standaard 1.5)	Automatische grid-dimensionering op breedte:hoogte 1.5	Barcode2DData	InvalidArgumentException	Grid-dimensies kunnen per as worden afgedwongen
HanXinEncoder::encode()	$data; opties ecLevel (0–3, standaard 1), version (1–84, standaard auto)	Kleinste passende versie	Barcode2DData	InvalidArgumentException	GB 2312 Region 1/2 tekstmodi volgens ISO/IEC 20830
JabCodeEncoder::encode()	$data; opties colors (4, 8, 16, 32, 64, 128, 256; standaard 8), eccLevel (0–10, standaard 3), symbolNumber (1–61, standaard 1), symbolVersions, symbolPositions, symbolEccLevels	Enkel 8-kleuren-symbool	BarcodeColorData	InvalidArgumentException, JabCodeEncodingException	Polychrome modulematrix met palet
RmqrEncoder::encode()	$data; opties ecLevel (RmqrConstants::EC_M standaard, of EC_H), version (bijv. 'R7x43', standaard auto)	Kleinste passende van de 32 ISO/IEC 23941-versies	Barcode2DData	InvalidArgumentException	Wijst payloads af die de capaciteit overschrijden; kapt nooit af
Gs1DataBarEncoder::encode()	$data; opties variant (Gs1DataBarVariant, standaard OMNIDIRECTIONAL), linkage (bool, standaard false), height (int, standaard variantminimum; per rij voor Expanded Stacked), segmentsPerRow (int, standaard 4; alleen Expanded Stacked)	Encodeert GTIN-invoer (§5/§6-familie) of een GS1 AI-elementstring (§7-familie)	Barcode2DData	InvalidArgumentException; InvalidSymbolStructureException	Alle zeven ISO/IEC 24724 Annex J-varianten encoderen
Gs1DataBarVariant	—	isImplemented() retourneert true voor alle zeven cases	enum (7 cases)	—	minimumHeightX() en defaultHeightX() volgens Annex J
ImbEncoder::encode()	string $code (20, 25, 29 of 31 cijfers)	65 four-state bars	BarcodeData	InvalidArgumentException	1D-encoder-interface; geen 2D-registry-sleutel
ImbEncoder::encodeToString()	string $code	Bar-states als een T/A/D/F-string	string	InvalidArgumentException	Voor controles tegen USPS-referentievectoren
Gs1DataParser::parse()	string $data	Detecteert automatisch Digital Link-URI’s, anders (AI)value-formaat	Gs1ParsedData	InvalidArgumentException	Implementeert het Core Gs1DataParserInterface-contract
Gs1DataParser::parseDigitalLink()	string $uri	Parseert een GS1 Digital Link-URI	Gs1ParsedData	InvalidArgumentException	—
Gs1DataParser::encodeForCode128() / ::encodeForQrCode() / ::encodeForDataMatrix()	object $parsed	Drager-bytesequentie met de FNC1-conventie van die drager	string	—	Verwacht een Gs1ParsedData-instantie
Gs1DataParser::validateAI()	string $ai, string $value	Structurele controle van één AI-waarde	bool	—	—
Gs1Validator::validate()	string $barcodeData, Gs1SupplyChainProfile $profile (standaard NONE)	Statisch snelpad over run()	Gs1ValidationResult	—	Parsefouten worden bevindingen, geen excepties
Gs1Validator::run()	zoals validate()	Parse, controlecijfers, datums, cross-AI-regels, profiel	Gs1ValidationResult	—	Instantiepad; constructor accepteert een geïnjecteerde parser
Gs1SupplyChainProfile	—	NONE slaat profielregels over	enum (5 cases)	—	RETAIL, FOOD, PHARMA, LOGISTICS, NONE; requiredAIs(), recommendedAIs(), primaryIdentifiers()
Gs1ValidationResult	—	Bevindingen bij constructie op ernst gepartitioneerd	readonly class	—	isValid, findings, errors, warnings, infos, parsedData; passes(), fails(), totalFindings()
Gs1ValidationFinding / Gs1FindingSeverity	—	severity, ruleId, message, optioneel ai en suggestion	readonly class / enum	—	Ernstniveaus: Error, Warning, Info
CompositeComponentA::codewordsFor()	string $data	§5 general-purpose binary-string-encodatie, base-928-conversie, round-trip-zelfcontrole	list<int> (elk 0–927)	InvalidArgumentException	Voed linkFor() of een externe CC-A-drager-renderer
CompositeComponentA::encode()	genegeerd	Weigert CC-A-full-symbol-rendering	—	UnsupportedBarcodeFeature (altijd)	Fail-closed; zie Randgevallen
CompositeComponentB::encode()	genegeerd	Weigert CC-B-2D-encodering	—	UnsupportedBarcodeFeature (altijd)	linkFor() blijft beschikbaar (CCSI 901)
CompositeComponentC::encode()	$data; opties doorgestuurd naar de PDF417-drager; carrierType (standaard GS1_128)	Volledige PDF417-drager met CCSI-codeword 920 vooraan	Barcode2DData	BarcodeException; CompositeLinkageException	Alleen de GS1_128-drager is toegelaten
CompositeComponent{A,B,C}::linkFor()	string $carrierId, array $codewords, CompositeCarrierType $carrierType	Koppelt component-codewords aan een 1D-drager	CompositeLinkage	CompositeLinkageException	Handhaaft drager-toelaatbaarheid en capaciteit
CompositeVariant / CompositeCarrierType	—	CC_A, CC_B, CC_C; GS1_DATABAR, GS1_128	enums	—	maxCodewords(), ccsi(), allowedCarriers(), usesFullPdf417()

Toegangspunt-signaturen

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

Gedragscontract

Registry-resolutie

De Core-standaardregistry-factory pre-bindt de Pro-encoders als lazy, capability-gelicentieerde entries. BarcodeProServiceProvider::register() is de ondersteunde fallback voor applicaties die een registry zonder defaults samenstellen, bijvoorbeeld framework-integraties met hun eigen container. Elke encoder zet een string-payload en per-symbologie-opties om in een barcode-data-object dat de paginarenderer omzet in PDF-content-operatoren.

GS1-parsing en -validatie

Gs1DataParser accepteert voor mensen leesbare AI-strings ((01)09521234543213(17)260131) en GS1 Digital Link-URI’s. Het produceert gecodeerde bytesequenties voor GS1-128-, QR Code- en Data Matrix-dragers, waarbij de FNC1- en group-separator-conventie van elke drager wordt toegepast. Gs1Validator draait een pijplijn in vijf stappen: parse, controlecijfers (GTIN, SSCC), datumlogica, cross-AI-regels en verplichte AI’s per branchprofiel. Een parsefout levert een ongeldig resultaat met bevindingen op; het werpt niet. Bevindingen partitioneren op ernst in errors, warnings en infos.

GS1 DataBar-variant-dispatch

Gs1DataBarEncoder::encode() dispatcht alle zeven ISO/IEC 24724:2011 Annex J-varianten via één optiescontract. Omnidirectional, Truncated, Stacked en Stacked Omnidirectional delen de §5-element-breedte-algebra met een mod-79-controleteken. Limited gebruikt zijn eigen §6-symbol-character-algebra met een mod-89-controleteken. Expanded en Expanded Stacked gebruiken de §7 (17,4)-algebra: de §7.2.5.5-driemodus numerieke, alfanumerieke en ISO/IEC 646-compactie-toestandsmachine plus een mod-211-controleteken (§7.2.6). De §5/§6-familie neemt een 14-cijferige GTIN-14 met mod-10-controlecijfer of een 13-cijferige item-identificatie. De §7-familie neemt een ruwe GS1 AI-elementstring (cijfers, letters, de ISO/IEC 646-interpunctie-subset, FNC1 als byte 0x1D). De optie linkage stelt de 2D-component-linkage-vlag in voor gebruik als de lineaire component van een GS1 Composite-symbool.

GS1 Composite-componenten

CC-C produceert een complete 2D-extended-component over de volledige PDF417-drager, waarbij het verplichte CCSI-codeword 920 als leidend data-codeword wordt geïnjecteerd (ISO/IEC 24723:2010 §5.4). CC-A genereert conforme base-928-data-codewords via codewordsFor(), met een fail-closed encode-decode-round-trip-zelfcontrole, maar weigert full-symbol-rendering. CC-B weigert 2D-encodering volledig. linkFor() koppelt component-codewords aan een 1D-drager als een CompositeLinkage-waarde en handhaaft drager-toelaatbaarheid en capaciteit.

Randgevallen en faalmodi

• Elke encoder wijst een lege payload af met InvalidArgumentException.
• Micro QR: het aanvragen van het niet-ondersteunde error-correction-niveau H wordt STILZWIJGEND naar L gedwongen in plaats van te falen (valideer opties vooraf als je fail-closed EC-selectie nodig hebt), omdat ISO/IEC 18004 alleen L, M en Q definieert voor Micro QR-symbolen.
• rMQR: het error-correction-niveau moet M of H zijn; een payload die de capaciteit van de 32 versies overschrijdt, wordt afgewezen, nooit afgekapt.
• JabCode: een kleurenaantal buiten de ondersteunde macht-van-twee-set, een ECC-niveau buiten 0–10, of een symboolaantal buiten 1–61 wordt afgewezen; downstream-encoderingsfouten werpen JabCodeEncodingException.
• GS1 DataBar: de §5/§6-familie valideert het GTIN-mod-10-controlecijfer, en Limited beperkt het indicatorcijfer tot 0 of 1. De §7-familie wijst niet-encodeerbare tekens en achterliggende of verdubbelde FNC1-scheiders af. Expanded Stacked wijst een oneven symbol-character-aantal per rij en per-rij-hoogten onder het 34X-minimum af. Interne structuur-zelfcontroles falen met InvalidSymbolStructureException in plaats van een misvormd symbool uit te geven.
• GS1 Composite: encode() van CC-A en CC-B werpt altijd UnsupportedBarcodeFeature (fail closed). CC-C werpt BarcodeException bij lege data of PDF417-capaciteitsoverloop (meer dan 925 codewords), en CompositeLinkageException voor een niet-toegelaten drager.
• GS1-validatie markeert misvormde AI-structuur en foute controlecijfers vóór de encodering; een ongeldige supply-chain-string produceert nooit een scanbaar conform symbool.
• IMB accepteert alleen 20-, 25-, 29- of 31-cijferige invoer.
• Barcode-encodering voert geen cryptografie uit. Er is geen FIPS-modusspecifiek gedrag; encoders draaien identiek, ongeacht het FIPS-profiel.

Conformiteit

NextPDF implementeert deze symbologieën tegen de hieronder aangehaalde gepubliceerde standaarden en pint referentie-traces in zijn testsuite. Uitspraken op deze pagina zijn capability-claims: ondersteuning is geen conformiteit, en conformiteit is geen certificering. NextPDF houdt geen symbologiecertificering. Clausule-ankers zijn geparafraseerd vanuit de productbron en zijn conformiteitsfixtures; de compliance-engine-corpus dekt geen barcode-symbologiestandaarden, dus de onderstaande ankers zijn product-onderbouwd zonder reference-identifiers.

Oppervlak	Standaard	Clausule-anker (geparafraseerd)
GS1 DataBar element-breedte-algebra	ISO/IEC 24724:2011	§5.2 symbol-character structure; Annex F.1 worked example (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 row partition and separators
GS1 DataBar Expanded encodation	ISO/IEC 24724:2011	§7.2.5.5 three-mode compaction state machine; §7.2.6 mod-211 check character
GS1 Composite linkage and CC-C	ISO/IEC 24723:2010	§5.4 CCSI codeword semantics; §5.1 carrier admissibility
GS1 Composite CC-A codewords	ISO/IEC 24723:2010	§5 general-purpose binary-string encodation with base-928 conversion
rMQR symbol structure	ISO/IEC 23941:2022	§6.3.2 Table 1 version dimensions; §7.8.2 fixed mask; Annex C / Annex I format-information reference
Micro QR	ISO/IEC 18004	Micro QR M1–M4 capacity and format information
Han Xin Code	ISO/IEC 20830:2021	Symbol structure; finder and alignment patterns; GB 2312 Region 1/2 modes; Reed–Solomon ECC; masking
JabCode	ISO/IEC 23634	Symbol, colour, and ECC structure
Postal symbology	USPS-B-3200	Intelligent Mail Barcode field structure

Ondersteuningsstatus per symbologie

Een variant is Geverifieerd wanneer een fixture onder pro/tests/** deze uitoefent, bij voorkeur een referentie-trace gepind op een gepubliceerd uitgewerkt voorbeeld. Een geleverde variant zonder toegewijde fixture blijft Geclaimd. Een variant zonder encoder is Niet ondersteund.

Symbologie / variant	Status	Bewijs (testpad)	Notities
Micro QR (M1–M4)	Geverifieerd	pro/tests/Unit/Barcode/MicroQrEncoderTest.php	Unit-niveau; een uitgewerkt-voorbeeld-referentie-trace-fixture is een gevolgde backfill
DotCode	Geverifieerd	pro/tests/Unit/Barcode/DotCodeEncoderTest.php; DotCodeGfArithmeticTest.php	Galois-veld-rekenkunde gedekt; geen vendor-decoder-round-trip
Han Xin Code	Geverifieerd	pro/tests/Unit/Barcode/HanXinEncoderTest.php; HanXinRsEncodingTest.php	Reed–Solomon-encoderingspad expliciet uitgeoefend
JabCode (1–61 symbolen, 4–256 kleuren, ECC 0–10)	Geverifieerd	pro/tests/Unit/Barcode/JabCode/JabCodeEncoderTest.php (+ 11 componentsuites in dezelfde directory)	Multi-symbool-cascade en ECC-bereik uitgeoefend; geen vendor-decoder-round-trip
USPS Intelligent Mail Barcode	Geverifieerd	pro/tests/Unit/Barcode/ImbEncoderTest.php; ImbRoutingCodeTest.php	Routing-code- en 20/25/29/31-cijferige lengtevalidatie uitgeoefend
rMQR — alle 32 ISO/IEC 23941-versies	Geverifieerd	pro/tests/Conformance/Barcode/Rmqr/AnnexValidatedSizesTest.php; RmqrAnnexCFormatInfoTest.php; pro/tests/Unit/Barcode/Rmqr/RmqrEncoderTest.php	Versie- en EC-paren gecontroleerd tegen ISO/IEC 23941 Table 1; Annex C / Annex I format-information-referentiewaarden
GS1 DataBar — Omnidirectional / Truncated	Geverifieerd	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarReferenceTest.php	Byte-equal met het uitgewerkte voorbeeld van Annex F.1; Truncated deelt de encodering met gereduceerde hoogte
GS1 DataBar — Stacked / Stacked Omnidirectional	Geverifieerd	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarStackedReferenceTest.php	Rij-split afgeleid van de Annex F.1-trace; separator-constructie volgens §5.4 en §5.5
GS1 DataBar — Limited	Geverifieerd	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarLimitedReferenceTest.php; pro/tests/Unit/Barcode/Gs1DataBar/Gs1DataBarLimitedEncoderTest.php	Byte-equal met het uitgewerkte voorbeeld van Annex F.2 (item 00098765432105)
GS1 DataBar — Expanded	Geverifieerd	pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarExpandedReferenceTest.php; pro/tests/Integration/Barcode/Gs1DataBarExpandedTwoDecoderTest.php	Byte-equal met het uitgewerkte voorbeeld van Annex F.3 ((10)12A); onafhankelijke-decoder-round-trip tegen zxing-cpp en ZBar
GS1 DataBar — Expanded Stacked	Geverifieerd	pro/tests/Unit/Barcode/Gs1DataBar/Gs1DataBarExpandedEncoderTest.php (stacked cases); de integratie-round-trip hierboven	Zelfde datapijplijn als single-row Expanded; §7.2.8 rij-partitie en separators geasserteerd
GS1 Composite — CC-C (PDF417-drager)	Geverifieerd	pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentCTest.php; CompositeRoundtripTest.php; CompositeLinkageTest.php	CCSI-codeword 920 en samenspel van de linkage-vlag gedekt
GS1 Composite — CC-A	Gedeeltelijk	pro/tests/Unit/Barcode/Gs1Composite/CompositeComponentACodewordTest.php; pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentATest.php	Codeword-generatie Geverifieerd (base-928, round-trip-zelfcontrole); full-symbol-rendering niet ondersteund — encode() faalt gesloten
GS1 Composite — CC-B	Niet ondersteund	pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentBTest.php (asserteert fail-closed-afwijzing)	Geen 2D-encodering; de linkage-helper (CCSI 901) blijft beschikbaar
GS1 AI-parser	Geverifieerd	pro/tests/Unit/Barcode/Gs1DataParserTest.php; Gs1DataParserFnc1Test.php	Beide invoerformaten en alle drie de drager-bytesequentie-uitvoeren uitgeoefend
GS1 supply-chain-validator	Geverifieerd	pro/tests/Unit/Barcode/Gs1ValidatorTest.php; Gs1ValidatorCrossAiTest.php; pro/tests/Unit/Barcode/Gs1/Gs1ValidatorDateValidationEdgeCaseTest.php	Controlecijfers, cross-AI-verplichte combinaties en datumlogica uitgeoefend

Ontwikkelnotities

• Bewijsankers op deze pagina zijn testpaden onder pro/tests/**; de repository levert geen examples/-directory voor deze module.
• De zeven capaciteitsnamen die onder Beschikbaarheid en licentiëring staan, zijn de sleutels die de service provider bindt. De IMB-encoder wordt rechtstreeks geconstrueerd en draagt geen registry-sleutel.
• CC-A geeft alleen de general-purpose-encodatiemethode uit; de applicatiespecifieke gecomprimeerde methoden zijn een gedocumenteerd dichtheidsresidu, geen correctheidsleemte.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helper-klassen, mechanismetabellen, runbook-bestandsnamen en ticket-prefixen vallen buiten bereik.

Zie ook

• Barcode-capaciteitsoverzicht (NextPDF Pro)
• Chart diepe referentie
• Core-barcodemodule