Pro edition

Barcode — Deep Reference

At a glance

The NextPDF Pro barcode surface adds specialty 2D and supply-chain symbologies on top of the Core barcode module. It ships six registry-resolved 2D encoders (Micro QR, DotCode, Han Xin Code, JabCode, rMQR, GS1 DataBar), one GS1 Composite 2D component encoder (CC-C), the USPS Intelligent Mail 1D encoder, and a GS1 Application Identifier parser plus supply-chain validator. Encoding is deterministic: the same payload and options always produce an identical module matrix. This page states the public API, the behavior contract, the failure modes, and the per-symbology conformance evidence.

Availability & licensing

This capability ships in NextPDF Pro (nextpdf/pro) and activates with a Pro-tier license envelope. A deployment without that entitlement does not load the capability’s classes. Compare editions and get a license.

composer require nextpdf/pro:^3

Each symbology binds its own capability name in the license envelope: barcode.microqr, barcode.dotcode, barcode.hanxin, barcode.jabcode, barcode.rmqr, barcode.gs1databar, and barcode.gs1-composite-cc-c. When a capability is not licensed, the registry does not resolve that encoder. GS1 Composite CC-A and CC-B full-symbol encoding is not supported (see the support status table), so no barcode.gs1-composite-cc-a or barcode.gs1-composite-cc-b key is registered.

Public API surface

Registry keys come from the Core NextPDF\Barcode\Barcode2DType case values plus the literal key gs1-composite-cc-c. For registry-resolved encoders, the registry key is the stable contract, not the encoder FQCN.

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
`BarcodeProServiceProvider::register()`	`BarcodeEncoderRegistry $registry`	Binds all seven Pro registry keys	`void`	—	Static; idempotent — a second call replaces the first binding
`MicroQrEncoder::encode()`	`$data`; options `ecLevel` (`'L'`, `'M'`, `'Q'`; default `'L'`), `version` (1–4 or null), `mask` (0–3 or null)	Auto-selects the smallest fitting version M1–M4	`Barcode2DData`	`InvalidArgumentException`	Unsupported `'H'` SILENTLY coerces to `'L'` (callers needing fail-closed EC selection must prevalidate); M1 ignores `ecLevel`
`DotCodeEncoder::encode()`	`$data`; options `gs1` (bool, default false), `columns` (int), `rows` (int), `ratio` (float, default 1.5)	Auto grid sizing at 1.5 width:height	`Barcode2DData`	`InvalidArgumentException`	Grid dimensions may be forced per axis
`HanXinEncoder::encode()`	`$data`; options `ecLevel` (0–3, default 1), `version` (1–84, default auto)	Smallest fitting version	`Barcode2DData`	`InvalidArgumentException`	GB 2312 Region 1/2 text modes per ISO/IEC 20830
`JabCodeEncoder::encode()`	`$data`; options `colors` (4, 8, 16, 32, 64, 128, 256; default 8), `eccLevel` (0–10, default 3), `symbolNumber` (1–61, default 1), `symbolVersions`, `symbolPositions`, `symbolEccLevels`	Single 8-color symbol	`BarcodeColorData`	`InvalidArgumentException`, `JabCodeEncodingException`	Polychrome module matrix with palette
`RmqrEncoder::encode()`	`$data`; options `ecLevel` (`RmqrConstants::EC_M` default, or `EC_H`), `version` (e.g. `'R7x43'`, default auto)	Smallest fitting of the 32 ISO/IEC 23941 versions	`Barcode2DData`	`InvalidArgumentException`	Rejects payloads exceeding capacity; never truncates
`Gs1DataBarEncoder::encode()`	`$data`; options `variant` (`Gs1DataBarVariant`, default `OMNIDIRECTIONAL`), `linkage` (bool, default false), `height` (int, default variant minimum; per-row for Expanded Stacked), `segmentsPerRow` (int, default 4; Expanded Stacked only)	Encodes GTIN input (§5/§6 family) or a GS1 AI element string (§7 family)	`Barcode2DData`	`InvalidArgumentException`; `InvalidSymbolStructureException`	All seven ISO/IEC 24724 Annex J variants encode
`Gs1DataBarVariant`	—	`isImplemented()` returns true for all seven cases	enum (7 cases)	—	`minimumHeightX()` and `defaultHeightX()` per Annex J
`ImbEncoder::encode()`	`string $code` (20, 25, 29, or 31 digits)	65 four-state bars	`BarcodeData`	`InvalidArgumentException`	1D encoder interface; not a 2D registry key
`ImbEncoder::encodeToString()`	`string $code`	Bar states as a T/A/D/F string	`string`	`InvalidArgumentException`	For checks against USPS reference vectors
`Gs1DataParser::parse()`	`string $data`	Auto-detects Digital Link URIs, else `(AI)value` format	`Gs1ParsedData`	`InvalidArgumentException`	Implements the Core `Gs1DataParserInterface` contract
`Gs1DataParser::parseDigitalLink()`	`string $uri`	Parses a GS1 Digital Link URI	`Gs1ParsedData`	`InvalidArgumentException`	—
`Gs1DataParser::encodeForCode128()` / `::encodeForQrCode()` / `::encodeForDataMatrix()`	`object $parsed`	Carrier byte sequence with that carrier’s FNC1 convention	`string`	—	Expects a `Gs1ParsedData` instance
`Gs1DataParser::validateAI()`	`string $ai`, `string $value`	Structural check of one AI value	`bool`	—	—
`Gs1Validator::validate()`	`string $barcodeData`, `Gs1SupplyChainProfile $profile` (default `NONE`)	Static quick path over `run()`	`Gs1ValidationResult`	—	Parse failures become findings, not exceptions
`Gs1Validator::run()`	as `validate()`	Parse, check digits, dates, cross-AI rules, profile	`Gs1ValidationResult`	—	Instance path; constructor accepts an injected parser
`Gs1SupplyChainProfile`	—	`NONE` skips profile rules	enum (5 cases)	—	`RETAIL`, `FOOD`, `PHARMA`, `LOGISTICS`, `NONE`; `requiredAIs()`, `recommendedAIs()`, `primaryIdentifiers()`
`Gs1ValidationResult`	—	Findings partitioned by severity at construction	readonly class	—	`isValid`, `findings`, `errors`, `warnings`, `infos`, `parsedData`; `passes()`, `fails()`, `totalFindings()`
`Gs1ValidationFinding` / `Gs1FindingSeverity`	—	`severity`, `ruleId`, `message`, optional `ai` and `suggestion`	readonly class / enum	—	Severities: `Error`, `Warning`, `Info`
`CompositeComponentA::codewordsFor()`	`string $data`	§5 general-purpose binary-string encodation, base-928 conversion, round-trip self-check	`list<int>` (each 0–927)	`InvalidArgumentException`	Feed `linkFor()` or an external CC-A carrier renderer
`CompositeComponentA::encode()`	ignored	Refuses CC-A full-symbol rendering	—	`UnsupportedBarcodeFeature` (always)	Fail-closed; see Edge cases
`CompositeComponentB::encode()`	ignored	Refuses CC-B 2D encoding	—	`UnsupportedBarcodeFeature` (always)	`linkFor()` remains available (CCSI 901)
`CompositeComponentC::encode()`	`$data`; options forwarded to the PDF417 carrier; `carrierType` (default `GS1_128`)	Full PDF417 carrier with CCSI codeword 920 leading	`Barcode2DData`	`BarcodeException`; `CompositeLinkageException`	Only the `GS1_128` carrier is admissible
`CompositeComponent{A,B,C}::linkFor()`	`string $carrierId`, `array $codewords`, `CompositeCarrierType $carrierType`	Pairs component codewords with a 1D carrier	`CompositeLinkage`	`CompositeLinkageException`	Enforces carrier admissibility and capacity
`CompositeVariant` / `CompositeCarrierType`	—	`CC_A`, `CC_B`, `CC_C`; `GS1_DATABAR`, `GS1_128`	enums	—	`maxCodewords()`, `ccsi()`, `allowedCarriers()`, `usesFullPdf417()`

Entry-point signatures

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

Behavior contract

Registry resolution

The Core default registry factory pre-binds the Pro encoders as lazy, capability-licensed entries. BarcodeProServiceProvider::register() is the supported fallback for applications that compose a registry with no defaults, for example framework integrations with their own container. Each encoder converts a string payload and per-symbology options into a barcode data object that the page renderer turns into PDF content operators.

GS1 parsing and validation

Gs1DataParser accepts human-readable AI strings ((01)09521234543213(17)260131) and GS1 Digital Link URIs. It produces encoded byte sequences for GS1-128, QR Code, and Data Matrix carriers, applying each carrier’s FNC1 and group-separator convention. Gs1Validator runs a five-step pipeline: parse, check digits (GTIN, SSCC), date logic, cross-AI rules, and industry-profile mandatory AIs. A parse failure yields an invalid result carrying findings; it does not throw. Findings partition by severity into errors, warnings, and infos.

GS1 DataBar variant dispatch

Gs1DataBarEncoder::encode() dispatches all seven ISO/IEC 24724:2011 Annex J variants through one options contract. Omnidirectional, Truncated, Stacked, and Stacked Omnidirectional share the §5 element-width algebra with a mod-79 check character. Limited uses its own §6 symbol-character algebra with a mod-89 check character. Expanded and Expanded Stacked use the §7 (17,4) algebra: the §7.2.5.5 three-mode numeric, alphanumeric, and ISO/IEC 646 compaction state machine plus a mod-211 check character (§7.2.6). The §5/§6 family takes a 14-digit GTIN-14 with mod-10 check digit or a 13-digit item identification. The §7 family takes a raw GS1 AI element string (digits, letters, the ISO/IEC 646 punctuation subset, FNC1 as byte 0x1D). The linkage option sets the 2D-component linkage flag for use as the linear component of a GS1 Composite symbol.

GS1 Composite components

CC-C produces a complete 2D extended component over the full PDF417 carrier, injecting the mandatory CCSI codeword 920 as the leading data codeword (ISO/IEC 24723:2010 §5.4). CC-A generates conformant base-928 data codewords through codewordsFor(), with a fail-closed encode-decode round-trip self-check, but refuses full-symbol rendering. CC-B refuses 2D encoding entirely. linkFor() pairs component codewords with a 1D carrier as a CompositeLinkage value, enforcing carrier admissibility and capacity.

Edge cases & failure modes

Every encoder rejects an empty payload with InvalidArgumentException.
Micro QR: requesting the unsupported H error-correction level SILENTLY coerces to L instead of failing (prevalidate options if you require fail-closed EC selection), because ISO/IEC 18004 defines only L, M, and Q for Micro QR symbols.
rMQR: the error-correction level must be M or H; a payload exceeding the capacity of the 32 versions is rejected, never truncated.
JabCode: a color count outside the supported power-of-two set, an ECC level outside 0–10, or a symbol count outside 1–61 is rejected; downstream encoding failures raise JabCodeEncodingException.
GS1 DataBar: the §5/§6 family validates the GTIN mod-10 check digit, and Limited restricts the indicator digit to 0 or 1. The §7 family rejects unencodable characters and trailing or doubled FNC1 separators. Expanded Stacked rejects an odd symbol-character count per row and per-row heights below the 34X minimum. Internal structure self-checks fail with InvalidSymbolStructureException rather than emitting a malformed symbol.
GS1 Composite: CC-A and CC-B encode() always throw UnsupportedBarcodeFeature (fail closed). CC-C throws BarcodeException on empty data or PDF417 capacity overflow (more than 925 codewords), and CompositeLinkageException for an inadmissible carrier.
GS1 validation flags malformed AI structure and bad check digits before encoding; an invalid supply-chain string never produces a scannable conformant symbol.
IMB accepts only 20-, 25-, 29-, or 31-digit inputs.
Barcode encoding performs no cryptography. There is no FIPS-mode-specific behavior; encoders run identically regardless of the FIPS profile.

Conformance

NextPDF implements these symbologies against the published standards cited below and pins reference traces in its test suite. Clause anchors are paraphrased from the product source and its conformance fixtures.

Surface	Standard	Clause anchor (paraphrased)
GS1 DataBar element-width 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

Per-symbology support status

A variant is Verified when a fixture under pro/tests/** exercises it, preferably a reference trace pinned to a published worked example. A shipped variant with no dedicated fixture stays Claimed. A variant with no encoder is Not supported.

Symbology / variant	Status	Evidence (test path)	Notes
Micro QR (M1–M4)	Verified	`pro/tests/Unit/Barcode/MicroQrEncoderTest.php`	Unit-level; a worked-example reference-trace fixture is a tracked backfill
DotCode	Verified	`pro/tests/Unit/Barcode/DotCodeEncoderTest.php`; `DotCodeGfArithmeticTest.php`	Galois-field arithmetic covered; no vendor decoder round trip
Han Xin Code	Verified	`pro/tests/Unit/Barcode/HanXinEncoderTest.php`; `HanXinRsEncodingTest.php`	Reed–Solomon encoding path explicitly exercised
JabCode (1–61 symbols, 4–256 colors, ECC 0–10)	Verified	`pro/tests/Unit/Barcode/JabCode/JabCodeEncoderTest.php` (+ 11 component suites in the same directory)	Multi-symbol cascade and ECC range exercised; no vendor decoder round trip
USPS Intelligent Mail Barcode	Verified	`pro/tests/Unit/Barcode/ImbEncoderTest.php`; `ImbRoutingCodeTest.php`	Routing-code and 20/25/29/31-digit length validation exercised
rMQR — all 32 ISO/IEC 23941 versions	Verified	`pro/tests/Conformance/Barcode/Rmqr/AnnexValidatedSizesTest.php`; `RmqrAnnexCFormatInfoTest.php`; `pro/tests/Unit/Barcode/Rmqr/RmqrEncoderTest.php`	Version and EC pairs checked against ISO/IEC 23941 Table 1; Annex C / Annex I format-information reference values
GS1 DataBar — Omnidirectional / Truncated	Verified	`pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarReferenceTest.php`	Byte-equal to the Annex F.1 worked example; Truncated shares the encoding at reduced height
GS1 DataBar — Stacked / Stacked Omnidirectional	Verified	`pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarStackedReferenceTest.php`	Row split derived from the Annex F.1 trace; separator construction per §5.4 and §5.5
GS1 DataBar — Limited	Verified	`pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarLimitedReferenceTest.php`; `pro/tests/Unit/Barcode/Gs1DataBar/Gs1DataBarLimitedEncoderTest.php`	Byte-equal to the Annex F.2 worked example (item 00098765432105)
GS1 DataBar — Expanded	Verified	`pro/tests/Conformance/Barcode/Gs1DataBar/Gs1DataBarExpandedReferenceTest.php`; `pro/tests/Integration/Barcode/Gs1DataBarExpandedTwoDecoderTest.php`	Byte-equal to the Annex F.3 worked example (`(10)12A`); independent-decoder round trip against zxing-cpp and ZBar
GS1 DataBar — Expanded Stacked	Verified	`pro/tests/Unit/Barcode/Gs1DataBar/Gs1DataBarExpandedEncoderTest.php` (stacked cases); the integration round trip above	Same data pipeline as single-row Expanded; §7.2.8 row partition and separators asserted
GS1 Composite — CC-C (PDF417 carrier)	Verified	`pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentCTest.php`; `CompositeRoundtripTest.php`; `CompositeLinkageTest.php`	CCSI codeword 920 and linkage-flag interplay covered
GS1 Composite — CC-A	Partial	`pro/tests/Unit/Barcode/Gs1Composite/CompositeComponentACodewordTest.php`; `pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentATest.php`	Codeword generation Verified (base-928, round-trip self-check); full-symbol rendering not supported — `encode()` fails closed
GS1 Composite — CC-B	Not supported	`pro/tests/Conformance/Barcode/Gs1Composite/CompositeComponentBTest.php` (asserts fail-closed rejection)	No 2D encoding; the linkage helper (CCSI 901) remains available
GS1 AI parser	Verified	`pro/tests/Unit/Barcode/Gs1DataParserTest.php`; `Gs1DataParserFnc1Test.php`	Both input formats and all three carrier byte-sequence outputs exercised
GS1 supply-chain validator	Verified	`pro/tests/Unit/Barcode/Gs1ValidatorTest.php`; `Gs1ValidatorCrossAiTest.php`; `pro/tests/Unit/Barcode/Gs1/Gs1ValidatorDateValidationEdgeCaseTest.php`	Check digits, cross-AI mandatory combinations, and date logic exercised

Development notes

Evidence anchors on this page are test paths under pro/tests/**; the repository ships no examples/ directory for this module.
The seven capability names listed under Availability & licensing are the keys the service provider binds. The IMB encoder is constructed directly and carries no registry key.
CC-A emits only the general-purpose encodation method; the application-specific compressed methods are a documented density residual, not a correctness gap.

Publication boundary

This page documents externally observable behavior and the supported public API surface only. Internal namespace paths, helper classes, mechanism tables, runbook filenames, and ticket prefixes are out of scope.