tc-lib-barcode

Overview

tc-lib-barcode is a pure-PHP barcode generation library for industrial, retail, logistics, and document automation workflows.

Encoding follows the published specification for each symbology, and the result comes back as a bar grid you can render however the target needs: SVG or PDF operators for print, PNG for a web preview. Coverage spans 73 formats across the linear, 2D, and postal families, including the GS1 DataBar and GS1-128 sets, the HIBC health industry profiles, the Chinese Han Xin Code, and the national postal symbologies of the United States, the United Kingdom, Germany, the Netherlands, Japan, and Australia.

Why This Library

• One API for every format: getBarcodeObj() returns the same object for a UPC-A and a Han Xin Code, and getInlineSvgCode(), getPngData(), getGrid() and getArray() work across all 73 types.
• Pure PHP with one runtime dependency, tecnickcom/tc-lib-color, plus the gd, ctype and pcre extensions; bcmath and imagick are optional accelerators.
• Each symbology follows its own published specification, named alongside the format where one applies.
• Per-format encoding, ECC, size and input-validation test suites, run under strict static analysis on every commit.
• LGPL-3.0, so it can be used in closed-source applications.
• Part of the tc-lib-pdf / TCPDF ecosystem, in continuous development since 2015.

Repository and API Docs

• GitHub: https://github.com/tecnickcom/tc-lib-barcode
• API docs: https://tcpdf.org/docs/srcdoc/tc-lib-barcode
• Packagist: https://packagist.org/packages/tecnickcom/tc-lib-barcode

Project Metadata

Installation

composer require tecnickcom/tc-lib-barcode

Where It Fits

Anywhere the symbol has to be produced on the server: shipping labels, event tickets, warehouse manifests, and the barcodes tc-lib-pdf draws into documents.

Supported Formats

Linear

2D

Postal

Rendering

Width, height, padding, foreground and background color are set per barcode.

Output Formats

• SVG image: file, inline code, or standalone document
• PNG image, rendered with GD or with Imagick when the extension is loaded
• GD image object
• HTML div elements
• Character grid string
• Array of bar coordinates, as XYXY or XYWH

Typed Enums

Symbology and per-type options are also available as backed enums, so the type token no longer has to be a raw string. The string form remains fully supported: every affected parameter is declared as a string|Enum union.

Extra parameters are still appended to the type token after a comma (for example QRCODE,H).

Input Validation

Every type validates its payload and raises \Com\Tecnick\Barcode\Exception with the reason when the code cannot be represented, rather than emitting a symbol no scanner can read. Character set, length, and check digit are checked per symbology, GS1 Application Identifier strings are parsed against their element definitions, and Barcode::MAX_CODE_LENGTH caps the payload at 30000 bytes.

Validation happens at encode time, so a rejected code surfaces where the data is, not where the label is printed.

The Aztec, Datamatrix, Micro QR and GS1 DataBar Expanded encoders are verified by round-trip decoding tests that check both the decoded payload and the symbol structure.

Integration Notes

Pick the symbology from what the scanners in the field can read and from how much data the payload carries; those two constraints usually decide it between them.

Normalize the payload before encoding. A value that does not fit the symbology (wrong length, a character outside the charset, a bad check digit) raises an exception at encode time rather than producing a symbol that scans wrong.

The GS1 types split by input form. GS1128, DATABAREXP and DATABAREXPSTACK take the bracketed element string (ai)value(ai)value..., which is also the human readable interpretation returned by getExtendedCode(); the library inserts the FNC1 separators, and parentheses are reserved as delimiters so they cannot appear in a value. SSCC18, GS114, ITF14 and the five fixed-length DataBar variants take a plain digit string instead: a code of the full length must carry a valid check digit, a shorter one is left-padded with zeros and the check digit is appended.

The HIBC data structure is independent of the symbology that carries it, so the same string encodes as HIBC39, HIBC128, HIBCDM, HIBCQR, or HIBCAZ; the modulo 43 check character is appended for you.

Scale and quiet zone are the usual cause of labels that read on screen and fail on the printer. Fix them per printer DPI profile and keep the setting with the profile.

Requirements

• PHP 8.2 or later
• Extensions: ctype, gd, pcre
• Optional extensions:
  • bcmath: speeds up the arbitrary precision arithmetic used by the IMB and PDF417 types. When the extension is missing, a pure-PHP fallback (\Com\Tecnick\Barcode\Math) is used instead.
  • imagick: alternative PNG renderer used by getPngData() when the extension is loaded.
• Package dependency: tecnickcom/tc-lib-color
• Composer

Development and Packaging

• QA and local checks: make deps, make help, make qa
• Coverage report: make qa-coverage
• Local example server: make server (or make server PORT=8080)
• Packaging: make rpm, make deb

Identifiers Issued by a Registration Body

The library encodes the data it is given. Several formats carry a number that only its registration body can issue, so a symbol is valid in its scheme only once that number has been obtained:

Trademarks

The names below identify the symbologies this library encodes and belong to their respective owners. They are used descriptively; no affiliation with or endorsement by their owners is claimed or implied.

GS1 licenses the claims necessary to implement its standards under its IP Policy, to GS1 members and to the participants of the work group that developed the standard, rather than to the public at large.

Support and Contribution

• Sponsor: https://github.com/sponsors/tecnickcom
• Contribution guide: https://github.com/tecnickcom/tc-lib-barcode/blob/main/CONTRIBUTING.md
• Security policy: https://github.com/tecnickcom/tc-lib-barcode/blob/main/SECURITY.md

Example

<?php

require_once __DIR__ . '/vendor/autoload.php';

$barcode = new \Com\Tecnick\Barcode\Barcode();
$bobj = $barcode->getBarcodeObj(
    type: 'QRCODE,H',
    code: 'https://tecnick.com',
    width: -4,
    height: -4,
    color: 'black',
    padding: [-2, -2, -2, -2],
)->setBackgroundColor('white');

echo $bobj->getInlineSvgCode();

The same call using the BarcodeType enum for the symbology token:

use Com\Tecnick\Barcode\BarcodeType;

$bobj = $barcode->getBarcodeObj(
    type: BarcodeType::DATAMATRIX,
    code: 'https://tecnick.com',
    width: -4,
    height: -4,
    color: 'black',
);