Barcode

At a glance

NextPDF Pro adds specialty 2D and supply-chain barcode symbologies on top of the linear and QR symbologies in the open-source edition. Each symbology renders directly into a PDF page surface as a deterministic content stream.

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.

Install

composer require nextpdf/pro:^3

The Pro encoders register themselves through the standard barcode encoder registry. Applications that build their own registry can re-register the Pro encoders explicitly through the published service provider.

Conceptual overview

The open-source edition covers the everyday linear and QR symbologies. NextPDF Pro extends the same registry with specialty symbologies for retail, logistics, postal, and high-density industrial use:

• Micro QR Code — the compact QR variant for small label real estate.
• DotCode — a dot-matrix symbology designed for high-speed industrial marking.
• Han Xin Code — a 2D symbology with native large-set CJK text capacity, per ISO/IEC 20830.
• JabCode — a polychrome 2D symbology with multi-symbol cascading.
• rMQR — the rectangular Micro QR variant for narrow, wide labels.
• GS1 DataBar — the GS1 retail and coupon symbology family.
• GS1 Composite (CC-C) — a linked 1D base plus a high-density PDF417 2D extension component carrying GS1 Application Identifier data. (CC-A and CC-B 2D extended-component encoding is not supported in this release; see the support matrix.)

Each encoder produces a barcode data object that the page renderer converts to PDF content operators. Encoding is deterministic: the same input and options always produce the same module pattern, which keeps signed and archived documents reproducible.

The barcode deep reference carries a per-symbology support matrix with evidence. For every symbology and variant, the matrix records one of three states: an in-repository conformance fixture exercises it (Verified), the implementation surface asserts it without a dedicated fixture (Claimed), or it falls out of scope (Not supported). A variant that ships an encoder but lacks a reference-trace fixture is recorded as Claimed.

Why it works this way

Every Pro encoder is a pure function: the same payload and options always produce the same module matrix, with no hidden state or seeded randomness. That determinism is the load-bearing decision. It lets a barcode round-trip through a signed or archived document without perturbing the byte stream, so a re-render never invalidates a signature. It also makes conformance auditable: the support matrix pins each symbology to a stored reference trace, checked bit-for-bit against a golden file. Extending the Core BarcodeEncoderRegistry rather than forking it keeps these guarantees identical across the open and Pro editions.

Design background: The same bytes every time: reproducible PDFs.

API surface

composer require nextpdf/pro:^3

The Pro barcode public surface consists of:

• A static service-provider entry point that registers the Pro 2D encoders into a barcode encoder registry (MicroQR, DotCode, HanXin, JabCode, RMQR, GS1DataBar, and the GS1 Composite CC-C component key gs1-composite-cc-c). GS1 Composite CC-A and CC-B 2D extended-component encoding is not supported in this release and is not registered.
• A GS1 Application Identifier parser that accepts both human-readable AI strings and GS1 Digital Link URIs and produces encoded byte sequences for GS1-128, QR Code, and Data Matrix carriers.
• A GS1 supply-chain validator that checks check digits, AI structure, date logic, and industry-profile mandatory AI combinations.

The full generated method-signature table renders in the barcode deep reference.

Code sample — Quick start

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

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

Code sample — Production

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,
        ]);
    }
}

Edge cases & gotchas

• The default registry pre-binds the Pro encoder entries lazily and gates them through the capability registry. An explicit BarcodeProServiceProvider::register() call is the supported fallback when an application composes its own registry with no defaults.
• Re-registration is idempotent: a second register() call replaces the first binding rather than throwing.
• GS1 DataBar variant coverage is partial by design. Omnidirectional, Truncated, Stacked, Stacked Omnidirectional, and Limited are reference-verified; Expanded and Expanded Stacked are out of scope in this release. See the support matrix.
• rMQR accepts every ISO 23941 version through the Annex-validated conformance suite. Scope-tracking metadata that predates the later size-range expansion may understate this; the support matrix records the code-verified reality.

Performance

Encoding cost scales with payload length and target symbol size. Each symbology lays out its symbol in a single pass with no reflow. JabCode multi-symbol cascades scale with the symbol count (1–61). Encoding holds the module matrix in memory; the largest selected symbol version bounds the cost.

Security notes

Barcode encoders do not execute payload content; they encode it as data. GS1 validation rejects malformed AI structures and invalid check digits before encoding, which prevents a malformed supply-chain string from producing a scannable but non-conformant symbol. The encoders log no payload themselves; applications must scrub sensitive payloads from their own logs.

Conformance

Each symbology follows its relevant published standard (ISO/IEC 24724 for GS1 DataBar, ISO/IEC 24723 for GS1 Composite, ISO/IEC 23941 for rMQR, ISO/IEC 18004 Annex for Micro QR, ISO/IEC 20830 for Han Xin Code, ISO/IEC 23634 for JabCode, USPS-B-3200 for the postal symbology). Clause-level conformance mapping with citation identifiers renders in the barcode deep reference.

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.

See also

• Core barcode module
• Chart — NextPDF Pro
• Barcode deep reference