===============
LIBRARY RULES
===============
From library maintainers:
- The Composer package is tecnickcom/tc-lib-barcode, the namespace is \Com\Tecnick\Barcode and the entry class is \Com\Tecnick\Barcode\Barcode. It requires PHP 8.2 or later and the gd extension.
- Every format uses the same API: (new \Com\Tecnick\Barcode\Barcode())->getBarcodeObj(type, code, width, height, color, padding) returns a Model object, and the same output methods work for all 73 types.
- Output methods on the returned object: getInlineSvgCode(), getSvgCode(), getSvg(), getPngData(), getPng(), getGd(), getHtmlDiv(), getGrid(), getArray(), getBarsArrayXYXY(), getBarsArrayXYWH(), setSize(), setColor(), setBackgroundColor().
- The type argument is the format code, optionally followed by comma-separated extra parameters, for example 'QRCODE,H', 'C39+' or 'PDF417,2,4'.
- Supported format codes are the keys of Barcode::BARCODETYPES, also available as the \Com\Tecnick\Barcode\BarcodeType enum, which getBarcodeObj() accepts in place of a string.
- Negative width and height values are multiplication factors per column and per row rather than absolute sizes; positive values are absolute user units excluding padding. Padding is [top, right, bottom, left] and follows the same sign convention.
- Colors are given in web notation (color name, hexadecimal code or CSS syntax) or as a PDF spot color name.
- tecnickcom/tc-lib-color is the only Composer dependency. bcmath and imagick are optional accelerators for the IMB and PDF417 arithmetic and for PNG rendering; the library never requires them.
- Payloads longer than Barcode::MAX_CODE_LENGTH (30000 bytes) are rejected by getBarcodeObj(), which throws \Com\Tecnick\Barcode\Exception on any encoding error.
- The library encodes the data it is given. Formats such as EAN, UPC, ITF-14, GS1-128, HIBC, MAILMARK, PZN, IDENTCODE and LEITCODE carry numbers that only their registration body can issue.

### Start Development Server

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/README.md

Commands to launch the example application server.

```bash
make server
```

--------------------------------

### Development Environment Commands

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/configuration.md

Standard commands for installing dependencies, running tests, performing analysis, and starting the local development server.

```bash
# Install dependencies
composer install

# Run tests
composer test

# Run code analysis
composer analyse

# Run quality checks
composer qa

# Start development server
php -S localhost:8000 -t example/
```

--------------------------------

### Install via Composer

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/configuration.md

Recommended installation method using Composer, which also installs the required tc-lib-color dependency.

```bash
composer require tecnickcom/tc-lib-barcode
```

--------------------------------

### setSize Usage Examples

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/barcode-model.md

Examples demonstrating fixed size configuration, multiplication factors, and method chaining.

```php
// Set fixed size with padding
$bobj->setSize(200, 100, [10, 5, 10, 5]);

// Use multiplication factors (3 units per column/row)
$bobj->setSize(-3, -3, [0, 0, 0, 0]);

// Chain with other methods
$bobj->setSize(150, 75)->setColor('blue')->setBackgroundColor('white');
```

--------------------------------

### Install via System Packages

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/configuration.md

Installation commands for RPM-based and DEB-based Linux distributions.

```bash
# RPM-based systems
rpm -i tc-lib-barcode-*.rpm

# DEB-based systems
dpkg -i tc-lib-barcode-*.deb
```

--------------------------------

### setBackgroundColor Usage Examples

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/barcode-model.md

Examples showing background color configuration and method chaining.

```php
$bobj->setBackgroundColor('white');
$bobj->setBackgroundColor('#FFFFFF');
$bobj->setBackgroundColor('lightyellow');

// Chain with other methods
$bobj->setColor('black')->setBackgroundColor('white');
```

--------------------------------

### Dockerfile Configuration

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/configuration.md

Example Dockerfile for a PHP 8.2 Apache environment, including necessary extensions and composer installation.

```dockerfile
FROM php:8.2-apache

RUN docker-php-ext-install gd bcmath

COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

WORKDIR /app
RUN composer install

CMD ["apache2-foreground"]
```

--------------------------------

### setColor Usage Examples

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/barcode-model.md

Examples showing various supported color formats including names, hex codes, and RGB strings.

```php
$bobj->setColor('black');
$bobj->setColor('#003366');
$bobj->setColor('rgb(0, 51, 102)');
$bobj->setColor('darkblue');
```

--------------------------------

### Initialize with System Package Autoloader

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/configuration.md

Standard initialization when the library is installed via system packages.

```php
<?php
require_once '/usr/share/php/Com/Teknick/Barcode/autoload.php';

use Com\Teknick\Barcode\Barcode;

$barcode = new Barcode();
```

--------------------------------

### Initialize with Composer Autoloader

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/configuration.md

Standard initialization when the library is installed via Composer.

```php
<?php
require_once __DIR__ . '/vendor/autoload.php';

use Com\Teknick\Barcode\Barcode;

$barcode = new Barcode();
```

--------------------------------

### Generate Minimal Barcode Example

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/configuration.md

Example showing how to create a barcode object and output it as inline SVG code.

```php
<?php
require_once __DIR__ . '/vendor/autoload.php';

use Com\Teknick\Barcode\Barcode;

// Create factory
$barcode = new Barcode();

// Generate barcode
$bobj = $barcode->getBarcodeObj(
    type: 'QRCODE',
    code: 'https://example.com',
    width: -4,
    height: -4,
);

// Output SVG
echo $bobj->getInlineSvgCode();
```

--------------------------------

### Bootstrap System Package Installation

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/configuration.md

Required bootstrap file path when using system package installations.

```php
require_once '/usr/share/php/Com/Tecnick/Barcode/autoload.php';
```

--------------------------------

### BarcodeType::fromLoose Usage Examples

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/types.md

Examples showing how to convert string tokens or existing enum instances, and how to handle invalid types.

```php
// From string token
$type = BarcodeType::fromLoose('QRCODE');

// From enum (returned unchanged)
$type = BarcodeType::fromLoose(BarcodeType::QRCODE);

// Invalid type throws exception
try {
    $type = BarcodeType::fromLoose('INVALID');
} catch (Exception $e) {
    echo $e->getMessage();  // "Unsupported barcode type: INVALID"
}
```

--------------------------------

### Start Development Server on Custom Port

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/README.md

Command to launch the development server on a specific port.

```bash
make server PORT=8080
```

--------------------------------

### getGrid Usage Examples

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/barcode-model.md

Demonstrates retrieving a barcode grid and customizing the space and bar characters.

```php
$bobj = $barcode->getBarcodeObj('C128', '0123456789', -3, -30);
echo $bobj->getGrid();

// Custom characters
echo $bobj->getGrid(' ', '█');  // Space and block characters
echo $bobj->getGrid('_', '#');  // Custom characters
```

--------------------------------

### getSvg usage examples

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/barcode-model.md

Demonstrates how to write a barcode as an SVG file with custom or auto-generated filenames.

```php
$bobj->getSvg('my_barcode');      // Writes 'my_barcode.svg'
$bobj->getSvg('barcode_123_456');  // Valid characters: alphanumeric, _, -
$bobj->getSvg();                   // Auto-generated filename
```

--------------------------------

### Development Commands

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/README.md

Common Makefile commands for managing dependencies, running quality assurance, and starting the development server.

```bash
make deps
make help
make qa
```

--------------------------------

### Install tc-lib-barcode via Composer

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/README.md

Use this command to add the library to your project dependencies.

```bash
composer require tecnickcom/tc-lib-barcode
```

--------------------------------

### PNG Response Pattern

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/README.md

Example of generating and outputting a PNG barcode image.

```php
header('Content-Type: image/png');
echo $barcode->getBarcodeObj('QRCODE', 'data', -4, -4)->getPngData();
```

--------------------------------

### getPng usage examples

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/barcode-model.md

Writes the barcode as a PNG file using the GD or Imagick extension.

```php
$bobj->getPng('barcode_image');  // Writes 'barcode_image.png'
$bobj->getPng();                 // Auto-generated filename
```

--------------------------------

### getGridArray Usage Example

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/barcode-model.md

Demonstrates retrieving a 2D array representation of a barcode and iterating through it.

```php
$bobj = $barcode->getBarcodeObj('EAN13', '5901234123457', -3, -30);
$grid = $bobj->getGridArray();

foreach ($grid as $row) {
    echo implode('', $row) . "\n";
}
```

--------------------------------

### getHtmlDiv usage examples

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/barcode-model.md

Demonstrates rendering a barcode as HTML div elements for web display.

```php
$bobj = $barcode->getBarcodeObj('C128', '0123456789', -3, -30);
echo $bobj->getHtmlDiv();

// Output in a web page
?>
<html>
    <head><title>Barcode</title></head>
    <body>
        <?php echo $bobj->getHtmlDiv(); ?>
    </body>
</html>
<?php
```

--------------------------------

### Generate a QR Code

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/README.md

A basic example showing how to instantiate the Barcode object and generate an inline SVG QR code.

```php
<?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();
```

--------------------------------

### getInlineSvgCode usage examples

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/barcode-model.md

Shows how to retrieve inline SVG markup for direct embedding in HTML.

```php
$bobj = $barcode->getBarcodeObj('QRCODE', 'https://example.com', -4, -4);
echo $bobj->getInlineSvgCode();

// Embed in HTML
?>
<div id="barcode">
    <?php echo $bobj->getInlineSvgCode(); ?>
</div>
<?php
```

--------------------------------

### getGd usage example

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/barcode-model.md

Retrieves a GD image object for further manipulation.

```php
$bobj = $barcode->getBarcodeObj('QRCODE', 'test', -4, -4);
$img = $bobj->getGd();

// Manipulate with GD functions
imagepng($img, 'output.png');
imagedestroy($img);
```

--------------------------------

### getBarsArrayXYWH Usage Example

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/barcode-model.md

Demonstrates retrieving and iterating over bar coordinates in (x, y, width, height) format.

```php
$bobj = $barcode->getBarcodeObj('QRCODE', 'test', -4, -4);
$bars = $bobj->getBarsArrayXYWH();

foreach ($bars as $bar) {
    [$x, $y, $w, $h] = $bar;
    echo "Bar at ($x, $y) sized $w × $h\n";
}
```

--------------------------------

### Barcode Generation Workflow

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/README.md

A complete example demonstrating how to initialize the Barcode class, generate QR codes and EAN-13 barcodes, and export them into various formats.

```php
<?php
require_once __DIR__ . '/vendor/autoload.php';

use Com\Teknick\Barcode\Barcode;
use Com\Teknick\Barcode\BarcodeType;
use Com\Teknick\Barcode\Exception as BarcodeException;

$barcode = new Barcode();

try {
    // Generate QR Code with high error correction
    $qr = $barcode->getBarcodeObj(
        type: 'QRCODE,H',
        code: 'https://example.com',
        width: -4,
        height: -4,
        color: 'black',
        padding: [0, 0, 0, 0],
    )->setBackgroundColor('white');

    // Multiple output formats
    $svg = $qr->getInlineSvgCode();
    $png = $qr->getPngData();
    $html = $qr->getHtmlDiv();
    $data = $qr->getArray();

    // Save files
    file_put_contents('qrcode.svg', $qr->getSvgCode());
    file_put_contents('qrcode.png', $qr->getPngData());

    // Generate EAN-13 barcode
    $ean = $barcode->getBarcodeObj('EAN13', '5901234123457', -3, -30)
        ->setColor('black');

    // Get extended code with check digit
    $extcode = $ean->getExtendedCode();

    // Access bar coordinates
    $bars = $ean->getBarsArrayXYWH();

} catch (BarcodeException $e) {
    echo "Barcode error: " . $e->getMessage();
}
?>
```

--------------------------------

### getPngData usage examples

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/barcode-model.md

Retrieves the barcode as binary PNG data for headers or file storage.

```php
$bobj = $barcode->getBarcodeObj('QRCODE', 'https://example.com', -4, -4);
$pngData = $bobj->getPngData();
header('Content-Type: image/png');
echo $pngData;

// Save PNG to a database or file
file_put_contents('barcode.png', $pngData);
```

--------------------------------

### getBarsArrayXYXY Usage Example

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/barcode-model.md

Demonstrates retrieving and iterating over bar coordinates in (x1, y1, x2, y2) format.

```php
$bobj = $barcode->getBarcodeObj('QRCODE', 'test', -4, -4);
$bars = $bobj->getBarsArrayXYXY();

foreach ($bars as $bar) {
    [$x1, $y1, $x2, $y2] = $bar;
    echo "Bar from ($x1, $y1) to ($x2, $y2)\n";
}
```

--------------------------------

### Configure 2D Barcode Parameters

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/types.md

Examples of configuring QR Code, Micro QR, and Aztec barcodes using the getBarcodeObj method with specific error correction, mode, and version parameters.

```php
// QR Code with high error correction
$bobj = $barcode->getBarcodeObj('QRCODE,H', 'data', -4, -4);

// Micro QR with mode and version
$bobj = $barcode->getBarcodeObj('MICROQR,M,4,AN', 'data', -4, -4);

// Aztec with parameters
$bobj = $barcode->getBarcodeObj('AZTEC,50,A,A', 'data', -4, -4);
```

--------------------------------

### getSvgCode usage example

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/barcode-model.md

Retrieves the complete SVG markup including the XML declaration.

```php
$bobj = $barcode->getBarcodeObj('QRCODE', 'test', -4, -4);
file_put_contents('barcode.svg', $bobj->getSvgCode());
```

--------------------------------

### Generate Aztec Rune Barcode

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/format-reference.md

Example for generating an Aztec Rune barcode, a compact format for numeric data.

```php
$bobj = $barcode->getBarcodeObj('AZTECRUNE', '125', -4, -4);
```

--------------------------------

### getPngDataImagick usage example

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/barcode-model.md

Retrieves PNG binary data specifically using the Imagick extension with error handling.

```php
try {
    $pngData = $bobj->getPngDataImagick();
} catch (Exception $e) {
    echo "Imagick not available: " . $e->getMessage();
}
```

--------------------------------

### Generate Micro QR Code Barcodes

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/format-reference.md

Examples for generating Micro QR Code barcodes, suitable for small form factor data encoding.

```php
// Default
$bobj = $barcode->getBarcodeObj('MICROQR', '0123456789', -4, -4);

// With parameters: error_level, version, encoding_mode
$bobj = $barcode->getBarcodeObj('MICROQR,M,4,AN', 'ABCDEFGHIJKLMNOPQR', -4, -4);
```

--------------------------------

### Generate QR Code Barcodes

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/format-reference.md

Examples for generating QR Code barcodes with varying error correction levels and encoding parameters.

```php
// Default
$bobj = $barcode->getBarcodeObj('QRCODE', 'https://example.com', -4, -4);

// High error correction
$bobj = $barcode->getBarcodeObj('QRCODE,H', 'https://example.com', -4, -4);

// With parameters: error_level, encoding_mode, version_min, version_max
$bobj = $barcode->getBarcodeObj('QRCODE,H,ST,0,0', 'https://example.com', -4, -4);
```

--------------------------------

### Generate 2D Barcode Objects

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/api-overview.md

Examples of generating QR Code and Data Matrix barcode objects using the getBarcodeObj method.

```php
$bobj = $barcode->getBarcodeObj('QRCODE,H', 'https://example.com', -4, -4);
$bobj = $barcode->getBarcodeObj('DATAMATRIX', 'Large data payload', -4, -4);
```

--------------------------------

### Catch Barcode Exceptions

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/errors.md

Example of how to catch and handle barcode-specific exceptions using the custom Exception class.

```php
use Com\Teknick\Barcode\Exception as BarcodeException;

try {
    $bobj = $barcode->getBarcodeObj('INVALID', 'test');
} catch (BarcodeException $e) {
    echo "Barcode error: " . $e->getMessage();
    // Handle error
}
```

--------------------------------

### Generate HIBC in 2D Barcodes

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/format-reference.md

Examples for generating HIBC formats in QR, Aztec, and Data Matrix using the getBarcodeObj method.

```php
$bobj = $barcode->getBarcodeObj('HIBCQR', '+A123BJC5D6E71', -4, -4);
$bobj = $barcode->getBarcodeObj('HIBCAZ', '+A123BJC5D6E71', -4, -4);
$bobj = $barcode->getBarcodeObj('HIBCDM', '+A123BJC5D6E71', -4, -4);
```

--------------------------------

### Create System Packages

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/README.md

Commands to build RPM and DEB packages.

```bash
make rpm
make deb
```

--------------------------------

### Create Barcode Factory

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/api-overview.md

Initialize the Barcode factory instance.

```php
use Com\Teknick\Barcode\Barcode;

$barcode = new Barcode();
```

--------------------------------

### Fluent method chaining

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/configuration.md

Chain configuration methods together as they return the object instance.

```php
$bobj = $barcode->getBarcodeObj('QRCODE', 'https://example.com', -4, -4)
    ->setColor('black')
    ->setBackgroundColor('white')
    ->setSize(-4, -4, [0, 0, 0, 0]);
```

--------------------------------

### Implement Fallback Output Formats

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/errors.md

Demonstrates attempting to output a PNG image and falling back to SVG if the PNG generation fails.

```php
try {
    $png = $bobj->getPngData();
    header('Content-Type: image/png');
    echo $png;
} catch (Exception $e) {
    // Fall back to SVG if PNG not available
    header('Content-Type: image/svg+xml');
    echo $bobj->getSvgCode();
}
```

--------------------------------

### System Package Autoloading

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/README.md

Use this path for autoloading when using system-installed packages.

```php
require_once '/usr/share/php/Com/Tecnick/Barcode/autoload.php';
```

--------------------------------

### Autoload Configuration

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/api-overview.md

Methods for including the library via Composer or system packages.

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

// System packages
require_once '/usr/share/php/Com/Teknick/Barcode/autoload.php';
```

--------------------------------

### Render Barcode to Multiple Formats

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/barcode-model.md

Demonstrates creating a QR code object with custom sizing and color settings, then exporting it to SVG, HTML, PNG, and raw data formats.

```php
use Com\Teknick\Barcode\Barcode;

$barcode = new Barcode();

// Create QR Code with custom sizing and colors
$bobj = $barcode->getBarcodeObj(
    type: 'QRCODE,H',
    code: 'https://example.com',
    width: -4,
    height: -4,
    color: 'black',
    padding: [-2, -2, -2, -2],
)->setBackgroundColor('white');

// Render to different formats
$svg = $bobj->getInlineSvgCode();
$html = $bobj->getHtmlDiv();
$png = $bobj->getPngData();
$grid = $bobj->getGrid();

// Get raw data
$data = $bobj->getArray();
$extcode = $bobj->getExtendedCode();
```

--------------------------------

### Generate Linear Barcode Objects

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/api-overview.md

Examples of generating CODE 128 and EAN-13 barcode objects using the getBarcodeObj method.

```php
$bobj = $barcode->getBarcodeObj('C128', '0123456789', -3, -30);
$bobj = $barcode->getBarcodeObj('EAN13', '5901234123457', -3, -30);
```

--------------------------------

### Web API Endpoint Pattern

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/README.md

Example of generating an SVG barcode for a web API endpoint using query parameters.

```php
header('Content-Type: image/svg+xml');
$bobj = $barcode->getBarcodeObj($_GET['type'], $_GET['code'], -4, -4);
echo $bobj->getSvgCode();
```

--------------------------------

### Handle Missing Graphics Library Errors

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/errors.md

Shows how to catch errors when GD or Imagick extensions are missing and how to check for their availability.

```php
$barcode = new Barcode();
$bobj = $barcode->getBarcodeObj('QRCODE', 'test', -4, -4);

// Throws if GD not installed
try {
    $png = $bobj->getPngData();
} catch (Exception $e) {
    echo "PNG rendering error: " . $e->getMessage();
}

// Imagick-specific call fails without Imagick
try {
    $png = $bobj->getPngDataImagick();
} catch (Exception $e) {
    echo "Imagick not available";
}

// Can check for GD extension before calling
if (!extension_loaded('gd')) {
    echo "GD library required for PNG output";
}
```

--------------------------------

### Generate Data Matrix (ECC200) barcodes

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/format-reference.md

Examples for generating standard square, rectangular, and GS1-compliant Data Matrix barcodes.

```php
// Default (square)
$bobj = $barcode->getBarcodeObj('DATAMATRIX', '0123456789', -4, -4);

// Rectangular variant
$bobj = $barcode->getBarcodeObj('DATAMATRIX,R', 'Data...', -4, -4);

// With GS1 support
$bobj = $barcode->getBarcodeObj('DATAMATRIX,S,GS1', \chr(232).'01095011010209171719050810ABCD1234'.\chr(232).'2110', -4, -4);
```

--------------------------------

### Generate Aztec Code Barcodes

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/format-reference.md

Examples for generating square matrix Aztec Code barcodes for documents and identity cards.

```php
// Default
$bobj = $barcode->getBarcodeObj('AZTEC', 'ABCDabcd01234', -4, -4);

// With parameters: compact_percentage, encoding_mode_1, encoding_mode_2
$bobj = $barcode->getBarcodeObj('AZTEC,50,A,A', 'ABCDabcd01234', -4, -4);
```

--------------------------------

### Validate Input Before Encoding

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/errors.md

Provides examples of pre-checking payload length and barcode type support to ensure safe encoding.

```php
// Pre-check payload length
if (strlen($data) > Barcode::MAX_CODE_LENGTH) {
    echo "Data too long";
    exit;
}

// Pre-check type
if (!isset(Barcode::BARCODETYPES[$type])) {
    echo "Unsupported format";
    exit;
}

// Now safe to encode
$bobj = $barcode->getBarcodeObj($type, $data);
```

--------------------------------

### Method Chaining with getBarcodeObj

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/README.md

Demonstrates the fluent API where configuration methods return $this to allow chaining.

```php
$bobj = $barcode->getBarcodeObj('QRCODE', 'data', -4, -4)
    ->setColor('black')
    ->setBackgroundColor('white')
    ->setSize(-4, -4, [0, 0, 0, 0]);

echo $bobj->getInlineSvgCode();
```

--------------------------------

### Get Extended Barcode Code

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/barcode-model.md

The getExtendedCode method returns the barcode content with any necessary checksums or format-specific suffixes appended.

```php
public function getExtendedCode(): string
```

```php
$bobj = $barcode->getBarcodeObj('EAN13', '123456789012');
echo $bobj->getExtendedCode();  // e.g., "1234567890128"

$bobj = $barcode->getBarcodeObj('C39+', 'TEST');
echo $bobj->getExtendedCode();  // Original code with checksum
```

--------------------------------

### Barcode Library Usage with Enums

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/types.md

Demonstrates using BarcodeType enums and string tokens with the Barcode library, as well as accessing the backing value.

```php
use Com\\\Teknick\\\Barcode\\\Barcode;
use Com\\\Teknick\\\Barcode\\\BarcodeType;

$barcode = new Barcode();

// Type-safe enum usage
$bobj = $barcode->getBarcodeObj(
    type: BarcodeType::QRCODE,
    code: 'https://example.com',
    width: -4,
    height: -4,
);

// String tokens also work
$bobj = $barcode->getBarcodeObj(
    type: 'QRCODE',
    code: 'https://example.com',
    width: -4,
    height: -4,
);

// Access backing value
$typeToken = BarcodeType::QRCODE->value;  // 'QRCODE'
```

--------------------------------

### Barcode Entry Point Structure

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/api-overview.md

Visual representation of the Barcode factory class structure.

```text
Com\Teknick\Barcode\Barcode
    └─ getBarcodeObj() → Model
```

--------------------------------

### Configure barcode colors

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/configuration.md

Set foreground and background colors using named colors, hex codes, or RGB strings.

```php
// Set foreground (bar) color
$bobj->setColor('black');
$bobj->setColor('#000000');
$bobj->setColor('rgb(0, 0, 0)');

// Set background color
$bobj->setBackgroundColor('white');
$bobj->setBackgroundColor('#FFFFFF');
```

--------------------------------

### Set Output Directory Permissions

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/configuration.md

Commands to ensure the web server has write access to the output directory for generated files.

```bash
# Ensure write permissions
chmod 755 /var/www/html/output
chown www-data:www-data /var/www/html/output
```

--------------------------------

### Generate 2D Raw Mode Barcode

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/format-reference.md

Example for generating a barcode in SRAW mode using comma-separated rows of '0' and '1' strings.

```php
$bobj = $barcode->getBarcodeObj('SRAW', '0101,1010', -4, -4);
```

--------------------------------

### Configure getBarcodeObj parameters

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/configuration.md

Pass configuration parameters directly to the getBarcodeObj method to define the barcode format, content, dimensions, color, and padding.

```php
$bobj = $barcode->getBarcodeObj(
    type: 'QRCODE',              // Barcode format
    code: 'data',                // Content to encode
    width: -4,                   // Width (negative = multiplier)
    height: -4,                  // Height (negative = multiplier)
    color: 'black',              // Foreground color
    padding: [0, 0, 0, 0],      // [top, right, bottom, left]
);
```

--------------------------------

### Web API Barcode Endpoint

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/configuration.md

Example implementation of a PHP web API endpoint that returns barcodes in SVG, PNG, or JSON format.

```php
<?php
require_once __DIR__ . '/vendor/autoload.php';

use Com	eknickarcodearcode;
use Com	eknickarcodearcodeexception;

header('Content-Type: application/json');

try {
    $type = $_GET['type'] ?? 'QRCODE';
    $code = $_GET['code'] ?? '';
    $format = $_GET['format'] ?? 'svg';

    $barcode = new Barcode();
    $bobj = $barcode->getBarcodeObj($type, $code, -4, -4);

    if ($format === 'png') {
        header('Content-Type: image/png');
        echo $bobj->getPngData();
    } elseif ($format === 'json') {
        $data = $bobj->getArray();
        echo json_encode($data);
    } else {
        header('Content-Type: image/svg+xml');
        echo $bobj->getSvgCode();
    }
} catch (BarcodeException $e) {
    http_response_code(400);
    echo json_encode(['error' => $e->getMessage()]);
}
```

--------------------------------

### Catch All Barcode Exceptions

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/errors.md

Shows how to catch specific BarcodeException instances to log errors or display fallback UI.

```php
use Com\\,Teknick\\Barcode\\Barcode;
use Com\Teknick\Barcode\Exception as BarcodeException;

$barcode = new Barcode();

try {
    $bobj = $barcode->getBarcodeObj(
        type: $_GET['type'] ?? 'QRCODE',
        code: $_GET['data'] ?? '',
    );
} catch (BarcodeException $e) {
    echo "Barcode error: " . htmlspecialchars($e->getMessage());
    // Log error, display fallback UI
}
```

--------------------------------

### File Organization Structure

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/README.md

The directory structure of the output documentation, highlighting key files for API reference, configuration, and barcode models.

```text
output/
├── README.md                 ← Start here
├── api-overview.md           ← Quick reference
├── barcode-factory.md        ← Barcode::getBarcodeObj()
├── barcode-model.md          ← Model interface
├── types.md                  ← BarcodeType, Exception
├── configuration.md          ← Setup & integration
├── errors.md                 ← Error handling
└── format-reference.md       ← All 73 formats
```

--------------------------------

### Generate Data Matrix Rectangular Extension (DMRE) barcodes

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/format-reference.md

Examples for generating DMRE barcodes, including options for GS1 support and specific size dimensions.

```php
$bobj = $barcode->getBarcodeObj('DMRE', 'A1B2C3D4E5F6G7H8I9J0K1L2', -4, -4);

// With GS1 and size specification
$bobj = $barcode->getBarcodeObj('DMRE,GS1,N,ASCII,8x144', '...', -4, -4);
```

--------------------------------

### Configure PHP Memory Limit

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/configuration.md

Recommended memory limit setting in php.ini for handling large 2D barcode formats.

```ini
; php.ini
memory_limit = 128M  ; Default is usually sufficient
```

--------------------------------

### Generate Han Xin Code

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/format-reference.md

Examples for generating Han Xin barcodes using default settings or custom error correction, version, and encoding mode parameters.

```php
// Default
$bobj = $barcode->getBarcodeObj('HANXIN', '0123456789', -4, -4);

// With parameters: error_correction, version, encoding_mode
$bobj = $barcode->getBarcodeObj('HANXIN,L3,10,2', '1234567890ABCDEFGabcdefg,Han Xin Code', -4, -4);
```

--------------------------------

### Method Chaining with Barcode Model

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/types.md

Methods return the static implementing class, allowing for fluent method chaining when configuring barcode objects.

```php
$bobj = $barcode->getBarcodeObj('QRCODE', 'test', -4, -4)
    ->setColor('black')
    ->setBackgroundColor('white')
    ->setSize(-4, -4, [0, 0, 0, 0]);
```

--------------------------------

### Padding Configuration with getBarcodeObj

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/api-overview.md

Padding is defined as an array of 4 integers [top, right, bottom, left]. Positive values provide fixed padding, while negative values act as multipliers for rows and columns.

```php
// Fixed padding: 10 top, 5 right, 10 bottom, 5 left
$padding = [10, 5, 10, 5];

// Multiplier padding: 2 rows/columns on all sides
$padding = [-2, -2, -2, -2];

$bobj = $barcode->getBarcodeObj('QRCODE', 'data', -4, -4, 'black', $padding);
```

--------------------------------

### Barcode Configuration Methods

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/api-overview.md

Methods for configuring the barcode object using method chaining.

```APIDOC
## Barcode Configuration Methods

### Methods
- **setSize(int $width, int $height, array $padding)**: Configures dimensions and padding.
- **setColor(string $color)**: Sets the foreground color.
- **setBackgroundColor(string $color)**: Sets the background color.
```

--------------------------------

### Configure Barcode via Method Chaining

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/api-overview.md

Modify barcode properties such as size, foreground color, and background color using fluent method chaining.

```php
$bobj
    ->setSize(width: int, height: int, padding: [int, int, int, int]): Model
    ->setColor(color: string): Model
    ->setBackgroundColor(color: string): Model
```

--------------------------------

### Configure barcode size

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/configuration.md

Use setSize to define dimensions using absolute values or multipliers for width, height, and padding.

```php
$bobj->setSize(
    width: 200,
    height: 100,
    padding: [10, 5, 10, 5]
);

// Or use multipliers
$bobj->setSize(
    width: -3,   // 3 units per column
    height: -3,  // 3 units per row
    padding: [-2, -2, -2, -2]  // 2 rows/columns padding
);
```

--------------------------------

### Windows File Path Formatting

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/configuration.md

Use forward slashes or escaped backslashes for file paths on Windows to avoid issues with escape sequences.

```php
// Good
$file = __DIR__ . '/output/barcode.svg';
$file = __DIR__ . '\\output\\barcode.svg';

// Avoid
$file = __DIR__ . '\output\barcode.svg';  // Escape sequences
```

--------------------------------

### PNG Output Methods

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/configuration.md

Methods for generating PNG barcode data or files. Requires the GD or Imagick extension.

```php
// Use GD (or Imagick as fallback)
$png = $bobj->getPngData();

// Force GD only
$png = $bobj->getPngData(imagick: false);

// Force Imagick (throws if unavailable)
$png = $bobj->getPngDataImagick();

// Get GD image object for further manipulation
$img = $bobj->getGd();

// Write PNG file
$bobj->getPng('barcode_filename');  // Creates barcode_filename.png
```

--------------------------------

### Absolute Sizing with getBarcodeObj

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/api-overview.md

Use positive integers to define exact barcode dimensions in user units.

```php
$bobj = $barcode->getBarcodeObj('QRCODE', 'data', 200, 200);
// Barcode will be 200×200 user units
```

--------------------------------

### setSize Method Signature

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/barcode-model.md

The method signature for configuring barcode dimensions and padding.

```php
public function setSize(
    int $width,
    int $height,
    array $padding = [0, 0, 0, 0],
): static
```

--------------------------------

### Create Barcode Object

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/README.md

Initialize a new barcode object using the getBarcodeObj method. The width and height parameters accept positive values for fixed dimensions or negative values as multipliers.

```php
$barcode = new Barcode();
$bobj = $barcode->getBarcodeObj(
    type: 'QRCODE',          // Format: string or BarcodeType enum
    code: 'data',            // Content to encode
    width: -4,               // Dimension: positive (fixed) or negative (multiplier)
    height: -4,
    color: 'black',          // Web color (name, hex, rgb, rgba, PDF spot color)
    padding: [0, 0, 0, 0],  // [top, right, bottom, left] in units
): Model;
```

--------------------------------

### Basic QR Code generation

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/barcode-factory.md

Generates a QR code with a specified width and height multiplication factor.

```php
$barcode = new \Com\Tecnick\Barcode\Barcode();
$bobj = $barcode->getBarcodeObj(
    type: 'QRCODE',
    code: 'https://example.com',
    width: -4,
    height: -4,
    color: 'black',
);

echo $bobj->getInlineSvgCode();
```

--------------------------------

### HTML Output Method

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/configuration.md

Method for rendering the barcode as HTML.

```APIDOC
## getHtmlDiv()
Returns the barcode rendered as CSS-styled <div> elements.
```

--------------------------------

### getPng

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/barcode-model.md

Writes the barcode as a PNG file to the output directory.

```APIDOC
## getPng(?string $filename = null): void

### Description
Writes the barcode as a PNG file to the output directory. Requires GD or Imagick extension.

### Parameters
- **$filename** (?string) - Optional - File name without extension.
```

--------------------------------

### Using BarcodeType enum

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/barcode-factory.md

Demonstrates type-safe barcode selection using the BarcodeType enum.

```php
$barcode = new \Com\Teknick\Barcode\Barcode();
$bobj = $barcode->getBarcodeObj(
    type: \Com\Teknick\Barcode\BarcodeType::QRCODE,
    code: 'Test data',
    width: -3,
    height: -3,
);
```

--------------------------------

### Grid Output Methods

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/configuration.md

Methods for retrieving character-based representations of the barcode as a string grid or a 2D array.

```php
// 2D string grid (multiline)
$grid = $bobj->getGrid();           // Default: '0' and '1'
$grid = $bobj->getGrid(' ', '█');   // Custom characters

// 2D array
$gridArray = $bobj->getGridArray();  // array[row][col]
```

--------------------------------

### Generate and Output PNG in Web

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/api-overview.md

Sets the content type header to image/png and outputs the generated PNG data.

```php
header('Content-Type: image/png');
echo $bobj->getPngData();
```

--------------------------------

### setBackgroundColor Method Signature

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/barcode-model.md

The method signature for setting the background color.

```php
public function setBackgroundColor(string $color): static
```

--------------------------------

### Handle Invalid Filename Errors

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/errors.md

Illustrates valid filename character constraints and the use of automatic filename generation.

```php
$barcode = new Barcode();
$bobj = $barcode->getBarcodeObj('QRCODE', 'test', -4, -4);

// Valid filenames
$bobj->getSvg('barcode_01');      // OK: alphanumeric + underscore
$bobj->getSvg('barcode-01');      // OK: alphanumeric + hyphen
$bobj->getSvg('barcode_test_01'); // OK

// Invalid characters (depends on implementation)
// $bobj->getSvg('barcode@01');    // May fail: @ not allowed
// $bobj->getSvg('barcode 01');    // May fail: space not allowed
// $bobj->getSvg('barcode.01');    // May fail: dot not allowed

// Auto-generated filename (MD5 hash)
$bobj->getSvg();  // Generates filename from data
```

--------------------------------

### Catch Barcode and Color Library Exceptions

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/errors.md

Demonstrates catching multiple exception types using a union type catch block when performing operations that involve both barcode and color settings.

```php
use Com\Teknick\Barcode\Exception as BarcodeException;
use Com\Teknick\Color\Exception as ColorException;

try {
    $bobj = $barcode->getBarcodeObj('QRCODE', 'test', -4, -4)
        ->setColor($_GET['color'] ?? 'black');
} catch (BarcodeException | ColorException $e) {
    echo "Error: " . htmlspecialchars($e->getMessage());
}
```

--------------------------------

### Barcode Model Output Interface

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/api-overview.md

List of available rendering methods provided by the Model interface.

```text
Com\Teknick\Barcode\Model
    ├─ setSize()
    ├─ setColor()
    ├─ setBackgroundColor()
    ├─ getArray()
    ├─ getExtendedCode()
    ├─ getInlineSvgCode()
    ├─ getSvgCode()
    ├─ getSvg()
    ├─ getHtmlDiv()
    ├─ getPngData()
    ├─ getPngDataImagick()
    ├─ getGd()
    ├─ getGrid()
    ├─ getGridArray()
    ├─ getBarsArrayXYXY()
    └─ getBarsArrayXYWH()
```

--------------------------------

### Fallback Rendering Pattern

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/README.md

Implementing a try-catch block to fallback to SVG rendering if PNG generation fails.

```php
try {
    $output = $bobj->getPngData();
    $type = 'image/png';
} catch (Exception $e) {
    $output = $bobj->getSvgCode();
    $type = 'image/svg+xml';
}
```

--------------------------------

### setColor Method Signature

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/barcode-model.md

The method signature for setting the foreground bar color.

```php
public function setColor(string $color): static
```

--------------------------------

### PHP Configuration for Barcode Extensions

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/configuration.md

Required and optional PHP extensions for barcode generation. Ensure these are enabled in your php.ini file.

```ini
; php.ini
extension=gd.so           ; or gd.dll on Windows
extension=pcre.so
extension=ctype.so

; Optional for performance
extension=bcmath.so       ; Speeds up IMB and PDF417
extension=imagick.so      ; Alternative PNG renderer
```

--------------------------------

### setSize(int $width, int $height, array $padding)

Source: https://github.com/tecnickcom/tc-lib-barcode/blob/main/_autodocs/barcode-model.md

Configures the barcode dimensions and padding. Supports both fixed sizes and multiplication factors for columns and rows.

```APIDOC
## public function setSize(int $width, int $height, array $padding = [0, 0, 0, 0]): static

### Description
Configure the barcode dimensions and padding. A negative value for width or height indicates a multiplication factor for each column or row.

### Parameters
- **$width** (int) - Required - Barcode width in user units (or multiplication factor if negative).
- **$height** (int) - Required - Barcode height in user units (or multiplication factor if negative).
- **$padding** (array{int, int, int, int}) - Optional - Padding around the barcode (top, right, bottom, left) in user units. Defaults to [0, 0, 0, 0].

### Return Value
Returns $this for method chaining.

### Throws
- Exception: If the barcode is empty or padding is invalid.
```