PHP Barcode Generator

https://github.com/picqer/php-barcode-generator
Admin
This is an easy to use, non-bloated, framework independent, barcode generator in PHP that creates...
Tokens:82,538
Snippets:561
Trust Score:8.6
License:LGPL-3.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install with Composer

Source: https://github.com/picqer/php-barcode-generator/blob/main/Readme.md

Install the package via Composer. For PNG or JPG output, the GD library or Imagick must also be installed; SVG and HTML renders have no dependencies.

```bash
composer require picqer/php-barcode-generator
```

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

### BarcodeBar usage example

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/barcode.md

Usage example creating BarcodeBar instances for bar, spacing, tracker, and full-height segments. Demonstrates isBar() returning true for bars and false for spacing.

```php
use Picqer\Barcode\BarcodeBar;

$bar = new BarcodeBar(3, 1, true);                 // bar, 3 modules wide
$space = new BarcodeBar(1, 1, false);              // spacing
$tracker = new BarcodeBar(1, 1, true, 1);          // short bar offset down (POSTNET-style)
$fullBar = new BarcodeBar(1, 3, true, 0);          // tall full-height bar

var_dump($bar->isBar());        // bool(true)
var_dump($space->isBar());      // bool(false)
```

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

### Usage example with TypeCode128

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/dynamic-html-renderer.md

Usage example: render a barcode and place it inside a sized container. The output reflows when the container size changes because no pixel dimensions are baked in.

```php
use Picqer\Barcode\Types\TypeCode128;
use Picqer\Barcode\Renderers\DynamicHtmlRenderer;

$barcode = (new TypeCode128())->getBarcode('081231723897');
$renderer = new DynamicHtmlRenderer();
$renderedBarcode = $renderer->render($barcode);
?>

<div style="width: 400px; height: 75px"><?php echo $renderedBarcode; ?></div>
```

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

### UPC add-ons usage example

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/types-ean-upc.md

Shows how to generate EAN-2 and EAN-5 supplement barcodes using TypeUpcExtension2 and TypeUpcExtension5.

```php
$eon2 = (new Picqer\Barcode\Types\TypeUpcExtension2())->getBarcode('5');
$eon5 = (new Picqer\Barcode\Types\TypeUpcExtension5())->getBarcode('51234');
```

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

### Barcode usage example

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/barcode.md

Shows how to construct a Barcode and add bars and spaces. The output comment shows the expected result: width=5 height=1 bars=3.

```php
use Picqer\Barcode\Barcode;
use Picqer\Barcode\BarcodeBar;

$barcode = new Barcode('12345');
$barcode->addBar(new BarcodeBar(2, 1, true));   // a 2-module-wide bar
$barcode->addBar(new BarcodeBar(1, 1, false));  // a 1-module-wide space
$barcode->addBar(new BarcodeBar(2, 1, true));

printf('width=%d height=%d bars=%d', $barcode->getWidth(), $barcode->getHeight(), count($barcode->getBars()));
// width=5 height=1 bars=3

```

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

### SvgRenderer API

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/svg-renderer.md

Code examples demonstrating the SvgRenderer class methods: render, setSvgType, setForegroundColor, and setBackgroundColor.

```APIDOC
## [SvgRenderer] render

### Description
Renders a barcode object to an SVG string. The output can be either a standalone SVG document or an inline SVG fragment suitable for embedding in HTML.

### Method
render

### Endpoint
SvgRenderer::render(Barcode $barcode, float $width, float $height): string

### Parameters
- **$barcode** (Picqer\Barcode\Barcode) - Required - The barcode object to render.
- **$width** (float) - Required - The width of the SVG in user units. Can be fractional.
- **$height** (float) - Required - The height of the SVG in user units. Can be fractional.

### Request Example
```php
$renderer->render($barcode, 450.20, 75);
```

### Response
#### Success Response
Returns a string containing the SVG markup.

#### Response Example
```php
$svg = $renderer->render($barcode, $barcode->getWidth() * 2, 75);
```

```

```APIDOC
## [SvgRenderer] setSvgType

### Description
Sets the SVG output type. Valid values are SvgRenderer::TYPE_SVG_INLINE and SvgRenderer::TYPE_SVG_STANDALONE. An invalid value throws an InvalidOptionException.

### Method
setSvgType

### Endpoint
SvgRenderer::setSvgType(string $svgType): void

### Parameters
- **$svgType** (string) - Required - The SVG type. Must be one of SvgRenderer::TYPE_SVG_INLINE or SvgRenderer::TYPE_SVG_STANDALONE.

### Request Example
```php
$renderer->setSvgType(SvgRenderer::TYPE_SVG_INLINE);
```

### Response
#### Success Response
No return value.

#### Error Response
Throws Picqer\Barcode\Exceptions\InvalidOptionException if the type is not valid.

```

```APIDOC
## [SvgRenderer] setForegroundColor

### Description
Sets the foreground color for the barcode bars. The color is specified as an RGB array.

### Method
setForegroundColor

### Endpoint
SvgRenderer::setForegroundColor(array $color): void

### Parameters
- **$color** (array) - Required - An array of three integers representing RGB values, e.g., [255, 0, 0] for red.

### Request Example
```php
$renderer->setForegroundColor([255, 0, 0]);
```

### Response
#### Success Response
No return value.

```

```APIDOC
## [SvgRenderer] setBackgroundColor

### Description
Sets the background color for the SVG. The color is specified as an RGB array.

### Method
setBackgroundColor

### Endpoint
SvgRenderer::setBackgroundColor(array $color): void

### Parameters
- **$color** (array) - Required - An array of three integers representing RGB values, e.g., [0, 0, 255] for blue.

### Request Example
```php
$renderer->setBackgroundColor([0, 0, 255]);
```

### Response
#### Success Response
No return value.

```

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

### Usage example with RendererInterface

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/renderer-interface.md

Consumes a renderer through the interface to be format-agnostic. Shows how to generate a barcode with TypeCode128 and render it with SvgRenderer or HtmlRenderer.

```php
use Picqer\Barcode\Types\TypeCode128;
use Picqer\Barcode\Renderers\RendererInterface;

function renderBarcode(RendererInterface $renderer, string $code, int $widthFactor = 3): string
{
    $barcode = (new TypeCode128())->getBarcode($code);
    return $renderer->render($barcode, $barcode->getWidth() * $widthFactor, 50);
}

echo renderBarcode(new Picqer\Barcode\Renderers\SvgRenderer(), '081231723897');
echo renderBarcode(new Picqer\Barcode\Renderers\HtmlRenderer(), '081231723897');
```

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

### PngRenderer API

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/png-renderer.md

Code examples and API documentation for the PngRenderer class from the picqer/php-barcode-generator library.

```APIDOC
## PngRenderer::render

### Description
Renders a barcode object to a PNG image string. The renderer can be configured with foreground and background colors, and can use either the GD or Imagick backend.

### Method
render(Barcode $barcode, int $width = 200, int $height = 30): string

### Parameters
- **$barcode** (Picqer\Barcode\Barcode) - Required - The barcode object to render.
- **$width** (int) - Optional - Width of the output image in pixels. Default is 200. For reliable scanning, pass `$barcode->getWidth() * N`.
- **$height** (int) - Optional - Height of the output image in pixels. Default is 30.

### Return Value
Returns a string containing the PNG image data.

### Example
```php
use Picqer\Barcode\Types\TypeCode128;
use Picqer\Barcode\Renderers\PngRenderer;

$barcode = (new TypeCode128())->getBarcode('081231723897');
$renderer = new PngRenderer();
$renderer->setForegroundColor([255, 0, 0]);

file_put_contents('barcode.png', $renderer->render($barcode, $barcode->getWidth() * 3, 50));
```
```

```APIDOC
## PngRenderer::setForegroundColor

### Description
Sets the foreground (bar) color for the rendered PNG image.

### Method
setForegroundColor(array $color): void

### Parameters
- **$color** (array) - Required - RGB array with three integer values between 0 and 255, e.g. `[255, 0, 0]` for red.

### Example
```php
$renderer->setForegroundColor([255, 0, 0]);
```
```

```APIDOC
## PngRenderer::setBackgroundColor

### Description
Sets the background color for the rendered PNG image. By default the background is transparent.

### Method
setBackgroundColor(array $color): void

### Parameters
- **$color** (array) - Required - RGB array with three integer values between 0 and 255, e.g. `[255, 255, 255]` for opaque white.

### Example
```php
$renderer->setBackgroundColor([255, 255, 255]);
```
```

```APIDOC
## PngRenderer::useGd

### Description
Forces the renderer to use the GD image backend instead of Imagick.

### Method
useGd(): void

### Example
```php
$renderer->useGd();
```
```

```APIDOC
## PngRenderer::__construct

### Description
Creates a new PngRenderer instance. Throws a BarcodeException if neither the GD library nor the Imagick extension is installed.

### Method
__construct()

### Exceptions
- **Picqer\Barcode\Exceptions\BarcodeException** - Thrown when no image backend (GD or Imagick) is available.

### Example
```php
try {
    $renderer = new PngRenderer();
} catch (Picqer\Barcode\Exceptions\BarcodeException $e) {
    exit('Install ext-gd or ext-imagick to generate PNG barcodes.');
}
```
```

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

### UPC Add-on Usage

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/types-ean-upc.md

Usage examples for UPC add-on barcodes.

```APIDOC
## TypeUpcExtension2::getBarcode (Usage)

### Description
Example usage for generating UPC add-on barcodes (EAN-2 and EAN-5).

### Examples
```php
$eon2 = (new Picqer\Barcode\Types\TypeUpcExtension2())->getBarcode('5');
$eon5 = (new Picqer\Barcode\Types\TypeUpcExtension5())->getBarcode('51234');
```
```

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

### HTML output structure

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/dynamic-html-renderer.md

Example HTML output structure. The container uses width:100% and height:100%, so the parent must have a defined size. Bars are positioned with percentages.

```html
<div style="font-size:0;position:relative;width:100%;height:100%[;background-color:rgb(...)]">
  <div style="background-color:rgb(...);width:X.XXXXXX%;height:H%;position:absolute;left:L%;top:T%">&nbsp;</div>
  ...
</div>
```

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

### Custom AsciiRenderer implementation

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/renderer-interface.md

Example of implementing a custom renderer. Only requires three methods: render(), setForegroundColor(), and setBackgroundColor(). The render() method converts bars to ASCII characters.

```php
use Picqer\Barcode\Barcode;
use Picqer\Barcode\Renderers\RendererInterface;

class AsciiRenderer implements RendererInterface
{
    private array $foregroundColor = [0, 0, 0];

    public function render(Barcode $barcode, float $width = 200, float $height = 30): string
    {
        $factor = $width / $barcode->getWidth();
        $out = '';
        foreach ($barcode->getBars() as $bar) {
            $out .= str_repeat($bar->isBar() ? '#' : ' ', max(1, (int)round($bar->getWidth() * $factor)));
        }
        return $out . PHP_EOL;
    }

    public function setForegroundColor(array $color): self
    {
        $this->foregroundColor = $color;
        return $this;
    }

    public function setBackgroundColor(?array $color): self
    {
        return $this; // no background support in this renderer
    }
}

echo (new AsciiRenderer())->render((new TypeCode128())->getBarcode('42'));
```

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

### Backend selection for JPG generator

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/barcode-generator.md

Forces GD backend for JPG generator even if Imagick is installed, then generates a CODABAR barcode.

```php
$generator = new Picqer\Barcode\BarcodeGeneratorJPG();
$generator->useGd(); // force GD even if Imagick is installed
echo $generator->getBarcode('081231723897', $generator::TYPE_CODABAR);
```

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

### Generate PNG barcode with all parameters

Source: https://github.com/picqer/php-barcode-generator/blob/main/Readme.md

Example using all parameters of getBarcode(): barcode string, type, width factor, height, and foreground color as RGB array. Saves the PNG output to a file.

```php
<?php

require 'vendor/autoload.php';

$redColor = [255, 0, 0];

$generator = new Picqer\Barcode\BarcodeGeneratorPNG();
file_put_contents('barcode.png', $generator->getBarcode('081231723897', $generator::TYPE_CODE_128, 3, 50, $redColor));
```

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

### Error handling on encode

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/type-interface.md

Example showing how to catch exceptions when encoding invalid data, such as an empty string, and fallback to a valid code.

```APIDOC
## Error handling on encode

### Description
Demonstrates catching exceptions thrown during encoding, specifically InvalidLengthException, and providing a fallback value.

### Method
PHP try-catch

### Example
```php
try {
    $barcode = (new Picqer\Barcode\Types\TypeCode128())->getBarcode('');
} catch (Picqer\Barcode\Exceptions\InvalidLengthException $e) {
    // 'You should provide a barcode string.' (src/Types/TypeCode128.php:138)
    $barcode = (new Picqer\Barcode\Types\TypeCode128())->getBarcode('fallback');
}
```
```

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

### Pharmacode two-track usage

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/types-misc.md

Usage example for Pharmacode two-track barcode type.

```php
$pharma2 = (new Picqer\Barcode\Types\TypePharmacodeTwoCode())->getBarcode('123456');
```

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

### Telepen alpha and numeric usage

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/types-misc.md

Usage example for Telepen alpha and numeric modes. The numeric mode is equivalent to using TypeTelepenNumeric.

```php
$telepenAlpha = (new Picqer\Barcode\Types\TypeTelepen())->getBarcode('Telepen 123');
$telepenNum   = (new Picqer\Barcode\Types\TypeTelepen('numeric'))->getBarcode('082311723897');
// equivalent: (new TypeTelepenNumeric())->getBarcode('...')
```

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

### Pharmacode two-track error handling

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/types-misc.md

Error handling example for Pharmacode two-track: passing '0' throws InvalidLengthException with message 'Pharmacode 2 needs a number of 1 or larger'.

```php
try {
    (new Picqer\Barcode\Types\TypePharmacodeTwoCode())->getBarcode('0'); // 0 < 1
} catch (Picqer\Barcode\Exceptions\InvalidLengthException $e) {
    // 'Pharmacode 2 needs a number of 1 or larger' (src/Types/TypePharmacodeTwoCode.php:24)
}
```

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

### Generic encode + render (type-swappable)

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/type-interface.md

Example function that accepts a TypeInterface and a code string, encodes the barcode, and renders it as SVG. Demonstrates usage with TypeCode128 and TypeEan13.

```APIDOC
## Generic encode + render (type-swappable)

### Description
Encodes a barcode using a given type and renders it as SVG. The function is type-swappable, meaning any TypeInterface implementation can be passed.

### Method
PHP function

### Signature
`function encode(TypeInterface $type, string $code): string`

### Parameters
- **$type** (TypeInterface) - Required - The barcode type to use for encoding.
- **$code** (string) - Required - The data to encode.

### Returns
- **string** - The rendered SVG string.

### Example
```php
use Picqer\Barcode\Types\TypeInterface;
use Picqer\Barcode\Renderers\SvgRenderer;

function encode(TypeInterface $type, string $code): string
{
    $barcode = $type->getBarcode($code);
    return (new SvgRenderer())->render($barcode, $barcode->getWidth() * 2, 50);
}

echo encode(new Picqer\Barcode\Types\TypeCode128(), '081231723897');
echo encode(new Picqer\Barcode\Types\TypeEan13(), '0049000004632');
```
```

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

### UPC-E error handling example

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/types-ean-upc.md

Demonstrates catching an InvalidCheckDigitException when an invalid check digit is supplied. The exception message is 'Provided UPC-E check digit is invalid.'

```php
try {
    (new TypeUpcE())->getBarcode('01234567'); // check digit 7 is wrong for these digits
} catch (Picqer\Barcode\Exceptions\InvalidCheckDigitException $e) {
    // 'Provided UPC-E check digit is invalid.' (src/Helpers/UpcEConverter.php:64)
}
```

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

### Save JPG barcode to disk with JpgRenderer

Source: https://github.com/picqer/php-barcode-generator/blob/main/Readme.md

Generates a Codabar barcode as a JPG image and saves it to a file named 'barcode.jpg'. Requires the Imagick or GD library; Imagick is preferred if installed. The width argument is the final output width, so multiply the intrinsic width by a factor to preserve scaling.

```php
$barcode = (new Picqer\Barcode\Types\TypeCodabar())->getBarcode('081231723897');
$renderer = new Picqer\Barcode\Renderers\JpgRenderer();

file_put_contents('barcode.jpg', $renderer->render($barcode, $barcode->getWidth() * 2));
```

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

### Codabar and Code 11 usage

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/types-misc.md

Usage example for Codabar and Code 11 barcode types. Codabar wraps the data in A...A automatically. The SvgRenderer renders the Code 11 barcode at twice its width and height 50.

```php
use Picqer\Barcode\Types\TypeCodabar;
use Picqer\Barcode\Types\TypeCode11;
use Picqer\Barcode\Renderers\SvgRenderer;

$codabar = (new TypeCodabar())->getBarcode('081231723897'); // wrapped in A...A automatically
$code11  = (new TypeCode11())->getBarcode('123-456');
echo (new SvgRenderer())->render($code11, $code11->getWidth() * 2, 50);
```

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

### Generic encode and render with TypeInterface and SvgRenderer

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/type-interface.md

Defines a function that accepts any barcode type and renders it as SVG. The function uses TypeInterface to get the barcode and SvgRenderer to render it with a width of twice the barcode's natural width and a height of 50. It then echoes two examples: a Code128 barcode and an EAN-13 barcode.

```php
use Picqer\Barcode\Types\TypeInterface;
use Picqer\Barcode\Renderers\SvgRenderer;

function encode(TypeInterface $type, string $code): string
{
    $barcode = $type->getBarcode($code);
    return (new SvgRenderer())->render($barcode, $barcode->getWidth() * 2, 50);
}

echo encode(new Picqer\Barcode\Types\TypeCode128(), '081231723897');
echo encode(new Picqer\Barcode\Types\TypeEan13(), '0049000004632');
```

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

### Explicit background and backend selection

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/jpg-renderer.md

Explicit configuration: forces GD backend, sets foreground and background colors, and renders with custom width and height.

```php
$barcode = (new Picqer\Barcode\Types\TypeCode128())->getBarcode('081231723897');

$renderer = new JpgRenderer();
$renderer->useGd();                       // force GD
$renderer->setForegroundColor([0, 0, 0]);
$renderer->setBackgroundColor([255, 255, 255]);

$jpg = $renderer->render($barcode, $barcode->getWidth() * 3, 40);
```

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

### getBarcode method signature

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/types-code128.md

Method signature for generating a Barcode object from a string. Throws InvalidLengthException for empty/whitespace input, InvalidCharacterException for unsupported characters, and BarcodeException when no start code can be determined. The encoded stream includes start code, data symbols, check character (sum mod 103), STOP (106), and END (107).

```php
public function getBarcode(string $code): Barcode
```

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

### PngRenderer constructor

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/png-renderer.md

Constructor with no parameters. Throws BarcodeException if neither Imagick nor GD is available.

```php
/**
 * @throws BarcodeException
 */
public function __construct()

```

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

### HTML renderer usage

Source: https://github.com/picqer/php-barcode-generator/blob/main/Readme.md

Creates an HTML renderer, sets foreground and background colors, and renders with float width and height. The output is HTML to be used inline in a full HTML document.

```php
$renderer = new Picqer\Barcode\Renderers\HtmlRenderer();
$renderer->setForegroundColor([255, 0, 0]); // Give a color red for the bars, default is black. Give it as 3 times 0-255 values for red, green and blue. 
$renderer->setBackgroundColor([0, 0, 255]); // Give a color blue for the background, default is transparent. Give it as 3 times 0-255 values for red, green and blue. 

$renderer->render($barcode, 450.20, 75); // Final width and height; floats are supported
```

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

### Basic JPEG rendering to file

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/jpg-renderer.md

Basic usage: creates a Codabar barcode, renders it to JPEG, and writes to disk. Width must be an integer multiple of the intrinsic width.

```php
use Picqer\Barcode\Types\TypeCodabar;
use Picqer\Barcode\Renderers\JpgRenderer;

$barcode = (new TypeCodabar())->getBarcode('081231723897');
$renderer = new JpgRenderer();

file_put_contents('barcode.jpg', $renderer->render($barcode, $barcode->getWidth() * 2));
```

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

### Render Code128 as HTML

Source: https://github.com/picqer/php-barcode-generator/blob/main/Readme.md

Encode a string with TypeCode128 and render it as HTML in the browser using HtmlRenderer. The example outputs a barcode for '081231723897'.

```php
<?php
require 'vendor/autoload.php';

// Make Barcode object of Code128 encoding.
$barcode = (new Picqer\Barcode\Types\TypeCode128())->getBarcode('081231723897');

// Output the barcode as HTML in the browser with a HTML Renderer
$renderer = new Picqer\Barcode\Renderers\HtmlRenderer();
echo $renderer->render($barcode);
```

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

### Barcode::__construct

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/barcode.md

Creates a new Barcode instance with the human-readable code that was encoded.

```APIDOC
## Barcode::__construct

### Description
Creates a new Barcode instance with the human-readable code that was encoded.

### Method
`public function __construct(string $barcode)`

### Parameters
- `$barcode` (string) - Required - The code that was encoded (as passed to the type encoder).

### Return
No return value.
```

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

### Basic HtmlRenderer usage

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/html-renderer.md

Basic usage: create an EAN-13 barcode, set foreground color, and render with custom width and height.

```php
use Picqer\Barcode\Types\TypeEan13;
use Picqer\Barcode\Renderers\HtmlRenderer;

$barcode = (new TypeEan13())->getBarcode('0049000004632');
$renderer = new HtmlRenderer();
$renderer->setForegroundColor([0, 0, 0]);

echo $renderer->render($barcode, 450.2, 75);
```

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

### TypeKix class definition

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/types-postal.md

Defines the TypeKix class extending TypeRms4cc with $kix set to true, which skips checksum, start bars, and stop bar.

```php
class TypeKix extends TypeRms4cc
{
    protected bool $kix = true;
}
```

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

### ColorHelper

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/helpers.md

Documentation for the ColorHelper class, providing a method to convert color strings to RGB arrays.

```APIDOC
## ColorHelper

### Description
Provides color conversion for legacy-style inputs.

### Methods

#### getArrayFromColorString

Converts a color string to an RGB array.

**Signature:** `ColorHelper::getArrayFromColorString(string $color): array`

**Parameters:**
- `$color` (string) - Required - The color string (e.g., '#3399ef').

**Returns:**
- (array) - An array of RGB values, e.g., [51, 153, 239].

**Throws:**
- `Picqer\Barcode\Exceptions\UnknownColorException` - If the color string is not recognized.
```

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

### Telepen alpha error handling

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/types-misc.md

Error handling example for Telepen alpha: passing a byte > 126 throws InvalidFormatException with message 'Invalid characters in data'.

```php
try {
    (new Picqer\Barcode\Types\TypeTelepen())->getBarcode("invalid\x80"); // byte > 126
} catch (Picqer\Barcode\Exceptions\InvalidFormatException $e) {
    // 'Invalid characters in data' (src/Types/TypeTelepen.php:80)
}
```

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

### Backend auto-detection logic

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/png-renderer.md

Selects Imagick if loaded, otherwise GD if imagecreate exists, otherwise throws BarcodeException. This logic is from src/Renderers/PngRenderer.php:25–33.

```php
if (extension_loaded('imagick')) {
    $this->useImagick = true;
} elseif (function_exists('imagecreate')) {
    $this->useImagick = false;
} else {
    throw new BarcodeException('Neither the GD library nor the Imagick extension is installed!');
}

```

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

### Barcode Generator API

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/barcode-generator.md

Documentation for the BarcodeGeneratorDynamicHTML class and related generator classes (PNG, SVG, JPG) with their getBarcode methods, parameters, return types, and usage examples.

```APIDOC
## [CLASS] BarcodeGeneratorDynamicHTML

### Description
Generates an HTML representation of a barcode using percentage-based widths and heights for a vector-like quality.

### Class
`Picqer\Barcode\BarcodeGeneratorDynamicHTML` extends `BarcodeGenerator`

### Method
`getBarcode`

### Signature
```php
public function getBarcode(string $barcode, $type, string $foregroundColor = 'black'): string
```

### Parameters
- **$barcode** (string) - Required - Code to encode
- **$type** (string) - Required - One of `BarcodeGenerator::TYPE_*`
- **$foregroundColor** (string) - Optional - Color name or hex string (default: `'black'`)

### Return
- **string** - HTML using percentage-based widths/heights. Place inside a fixed-size container.

### Notes
- Does not accept `$widthFactor` or `$height` parameters; width 200/height 30 defaults are ignored by `DynamicHtmlRenderer`.

## [CLASS] BarcodeGeneratorPNG

### Description
Generates a PNG image of a barcode.

### Class
`Picqer\Barcode\BarcodeGeneratorPNG` extends `BarcodeGenerator`

### Method
`getBarcode`

### Signature
```php
public function getBarcode(string $barcode, $type, int $widthFactor = 2, int $height = 30, array $foregroundColor = [0, 0, 0]): string
```

### Parameters
- **$barcode** (string) - Required - Code to encode
- **$type** (string) - Required - One of `BarcodeGenerator::TYPE_*`
- **$widthFactor** (int) - Optional - Width factor (default: 2)
- **$height** (int) - Optional - Height in pixels (default: 30)
- **$foregroundColor** (array) - Optional - RGB array (default: [0, 0, 0])

### Return
- **string** - PNG image data

### Usage Example
```php
$generator = new Picqer\Barcode\BarcodeGeneratorPNG();
file_put_contents('barcode.png', $generator->getBarcode('081231723897', $generator::TYPE_CODE_128, 3, 50, [255, 0, 0]));
```

## [CLASS] BarcodeGeneratorSVG

### Description
Generates an SVG representation of a barcode.

### Class
`Picqer\Barcode\BarcodeGeneratorSVG` extends `BarcodeGenerator`

### Method
`getBarcode`

### Signature
```php
public function getBarcode(string $barcode, $type, int $widthFactor = 2, int $height = 30, string $foregroundColor = 'black'): string
```

### Parameters
- **$barcode** (string) - Required - Code to encode
- **$type** (string) - Required - One of `BarcodeGenerator::TYPE_*`
- **$widthFactor** (int) - Optional - Width factor (default: 2)
- **$height** (int) - Optional - Height in pixels (default: 30)
- **$foregroundColor** (string) - Optional - Color name or hex string (default: 'black')

### Return
- **string** - SVG data

### Error Handling
- Throws `UnknownTypeException` (a `BarcodeException`) if the type is not recognized.

### Usage Example
```php
try {
    $svg = (new Picqer\Barcode\BarcodeGeneratorSVG())->getBarcode('12345', 'NOT_A_TYPE');
} catch (Picqer\Barcode\Exceptions\BarcodeException $e) {
    error_log('Barcode generation failed: ' . $e->getMessage());
}
```

## [CLASS] BarcodeGeneratorJPG

### Description
Generates a JPG image of a barcode.

### Class
`Picqer\Barcode\BarcodeGeneratorJPG` extends `BarcodeGenerator`

### Method
`getBarcode`

### Signature
```php
public function getBarcode(string $barcode, $type, int $widthFactor = 2, int $height = 30, array $foregroundColor = [0, 0, 0]): string
```

### Parameters
- **$barcode** (string) - Required - Code to encode
- **$type** (string) - Required - One of `BarcodeGenerator::TYPE_*`
- **$widthFactor** (int) - Optional - Width factor (default: 2)
- **$height** (int) - Optional - Height in pixels (default: 30)
- **$foregroundColor** (array) - Optional - RGB array (default: [0, 0, 0])

### Return
- **string** - JPG image data

### Backend Selection
- `useGd()` - Force GD backend even if Imagick is installed.

### Usage Example
```php
$generator = new Picqer\Barcode\BarcodeGeneratorJPG();
$generator->useGd(); // force GD even if Imagick is installed
echo $generator->getBarcode('081231723897', $generator::TYPE_CODABAR);
```
```

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

### UPC-E to UPC-A conversion with UpcEConverter

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/helpers.md

Shows direct conversion between UPC-E and UPC-A forms using UpcEConverter::expand() and compress(). Also demonstrates normalize() for 7-digit input and accessing the human-readable representation.

```php
use Picqer\Barcode\Helpers\UpcEConverter;

$gtin12 = UpcEConverter::expand('01234565');        // 8-digit UPC-E -> GTIN-12
$upcE   = UpcEConverter::compress('001234500005');  // 12-digit UPC-A -> 8-digit UPC-E

$data = UpcEConverter::normalize('0123450');        // 7-digit UPC-E
echo $data->getHumanReadable();                     // '0' + encodedDigits + checkDigit
```

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

### TypeEan13 class definition

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/types-ean-upc.md

Defines the EAN-13 barcode type. Accepts 12 digits (check digit computed) or 13 digits (validated). Example: 0049000004632 / 004900000463.

```php
class TypeEan13 extends TypeEanUpcBase
{
    protected int $length = 13;
    protected bool $upca = false;
    protected bool $upce = false;
}
```

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

### PNG and JPG renderer usage with GD or Imagick

Source: https://github.com/picqer/php-barcode-generator/blob/main/Readme.md

Creates a PNG renderer (also applicable to JPG), sets colors, and optionally selects GD or Imagick backend. The render() method requires width as an integer multiple of the barcode's intrinsic width for reliable scanning.

```php
$renderer = new Picqer\Barcode\Renderers\PngRenderer();
$renderer->setForegroundColor([255, 0, 0]); // Give a color for the bars, default is black. Give it as 3 times 0-255 values for red, green and blue. 
$renderer->setBackgroundColor([0, 255, 255]); // Give a color for the background, default is transparent (in PNG) or white (in JPG). Give it as 3 times 0-255 values for red, green and blue. 
$renderer->useGd(); // If you have Imagick and GD installed, but want to use GD
$renderer->useImagick(); // If you have Imagick and GD installed, but want to use Imagick

$renderer->render($barcode, $barcode->getWidth() * 2, 40); // Final width and height in pixels
```

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

### Telepen numeric error handling

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/types-misc.md

Error handling example for Telepen numeric: passing an odd-length string throws InvalidFormatException with message 'There must be an even number of digits'.

```php
try {
    (new Picqer\Barcode\Types\TypeTelepen('numeric'))->getBarcode('123'); // odd length
} catch (Picqer\Barcode\Exceptions\InvalidFormatException $e) {
    // 'There must be an even number of digits'
}
```

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

### Configure SVG and PNG renderers with TypeCode128

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/configuration.md

Shows the full configuration surface for the library: creating a Code128 barcode, rendering it as an inline SVG with custom foreground/background colors, and as a PNG using the GD backend with an explicit size that is an integer multiple of the intrinsic width. Requires PHP ^8.2 and either ext-gd or ext-imagick for PNG rendering.

```php
use Picqer\Barcode\Types\TypeCode128;
use Picqer\Barcode\Renderers\SvgRenderer;
use Picqer\Barcode\Renderers\PngRenderer;

$barcode = (new TypeCode128())->getBarcode('081231723897');

// SVG: inline + colors
$svg = (new SvgRenderer())
    ->setForegroundColor([255, 0, 0])
    ->setBackgroundColor([0, 0, 255])
    ->setSvgType(SvgRenderer::TYPE_SVG_INLINE)
    ->render($barcode, 450.20, 75);

// PNG: forced backend + explicit size (integer multiple of intrinsic width)
$png = (new PngRenderer())
    ->useGd()
    ->setForegroundColor([0, 0, 0])
    ->render($barcode, $barcode->getWidth() * 3, 50);
```

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

### Barcode::getBarcode method

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/barcode.md

Returns the raw code string passed to the constructor, unchanged.

```php
public function getBarcode(): string

```

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

### Barcode constructor

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/barcode.md

Constructor that accepts the human-readable code string that was passed to the type encoder.

```php
public function __construct(string $barcode)

```

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

### UPC-E usage example

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/types-ean-upc.md

Shows three accepted input forms for UPC-E: 7-digit with auto-computed check digit, 8-digit with validated check digit, and 12-digit UPC-A that is zero-suppressible.

```php
use Picqer\Barcode\Types\TypeUpcE;

$fromUpcE7 = (new TypeUpcE())->getBarcode('0123450');       // 7 UPC-E digits, check digit auto-computed
$fromUpcE8 = (new TypeUpcE())->getBarcode('01234565');      // 8 digits, check digit validated
$fromUpcA  = (new TypeUpcE())->getBarcode('001234500005');  // 12-digit UPC-A (zero-suppressible)
```

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

### Barcode::getBarcode

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/barcode.md

Returns the raw code string passed to the constructor.

```APIDOC
## Barcode::getBarcode

### Description
Returns the raw code string passed to the constructor, unchanged.

### Method
`public function getBarcode(): string`

### Return
`string` - The raw code string.
```

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

### EAN-13 usage example

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/types-ean-upc.md

Shows how to generate an EAN-13 barcode without a check digit; the check digit is computed internally. The barcode is rendered as SVG with a width multiplier of 2 and height 60.

```php
use Picqer\Barcode\Types\TypeEan13;
use Picqer\Barcode\Renderers\SvgRenderer;

$barcode = (new TypeEan13())->getBarcode('004900000463'); // 12 digits -> check digit appended internally
echo (new SvgRenderer())->render($barcode, $barcode->getWidth() * 2, 60);
```

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

### Color conversion with ColorHelper

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/helpers.md

Converts a color string to an RGB array using ColorHelper::getArrayFromColorString(). Throws UnknownColorException for unsupported color names.

```php
use Picqer\Barcode\Helpers\ColorHelper;

$rgb = ColorHelper::getArrayFromColorString('#3399ef'); // [51, 153, 239]
try {
    ColorHelper::getArrayFromColorString('mauve');
} catch (Picqer\Barcode\Exceptions\UnknownColorException $e) {
    // 'Only basic string-based colors are supported in v3.'
}
```

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

### Error handling for missing backends

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/jpg-renderer.md

Error handling: catches BarcodeException thrown in the constructor when neither GD nor Imagick is available.

```php
try {
    $renderer = new JpgRenderer();
} catch (Picqer\Barcode\Exceptions\BarcodeException $e) {
    // 'Neither the GD library nor the Imagick extension is installed!'
    error_log($e->getMessage());
}
```

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

### TypeCode128B class definition

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/types-code128.md

Forced subset B variant. Accepts ASCII 32–127 plus FNC 241–244; rejects characters outside that range. Uses start code 104.

```php
class TypeCode128B extends TypeCode128
{
    protected ?string $type = 'B';
}
```

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

### render

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/dynamic-html-renderer.md

Renders the barcode as HTML that scales to 100% of its container. Width and height parameters are ignored.

```APIDOC
## [GET] /render

### Description
Renders the barcode as HTML that scales to 100% of its container. Width and height parameters are ignored.

### Method
GET

### Endpoint
/render

### Parameters
#### Path Parameters
- **barcode** (Barcode) - Required - Encoded barcode

#### Query Parameters
- **width** (float) - Optional - Ignored (default: 200)
- **height** (float) - Optional - Ignored (default: 30)

### Request Example
{
  "barcode": "<Barcode object>",
  "width": 200,
  "height": 30
}

### Response
#### Success Response (200)
- **string** (string) - HTML markup

#### Response Example
{
  "result": "<div style=\"font-size:0;position:relative;width:100%;height:100%\">...</div>"
}
```

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

### TypeTelepen constructor with mode parameter

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/types-misc.md

Constructor for TypeTelepen. Accepts an optional mode string; 'numeric' (case-insensitive) selects Telepen Numeric, anything else defaults to alpha.

```php
/** @param string $m */
public function __construct($m = 'alpha')
```

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

### Handle invalid characters in Code 39 and Code 32

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/types-code39-family.md

Shows try-catch blocks for InvalidCharacterException when using TypeCode39 with lowercase letters and TypeCode32 with non-digit characters. The first example notes that lowercase is not supported in plain Code 39 and suggests TypeCode39Extended.

```php
try {
    (new Picqer\Barcode\Types\TypeCode39())->getBarcode('abc'); // lowercase not in plain Code 39
} catch (Picqer\Barcode\Exceptions\InvalidCharacterException $e) {
    // 'Char a is unsupported' -> use TypeCode39Extended instead
}

try {
    (new Picqer\Barcode\Types\TypeCode32())->getBarcode('ABC123');
} catch (Picqer\Barcode\Exceptions\InvalidCharacterException $e) {
    // non-digit is not supported for Code 32
}
```

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

### TypeCode128A class definition

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/types-code128.md

Forced subset A variant. Accepts ASCII 00–95 plus FNC characters 241–244; rejects characters with ord() > 95 outside FNC range. Uses start code 103.

```php
class TypeCode128A extends TypeCode128
{
    protected ?string $type = 'A';
}
```

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

### PngRenderer::__construct

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/png-renderer.md

Constructor for the PngRenderer class, which automatically selects the rendering backend (Imagick or GD) and throws an exception if neither is available.

```APIDOC
## PngRenderer Constructor

### Description
Initializes a new PngRenderer instance. Automatically selects the backend (Imagick preferred) or throws an exception if neither GD nor Imagick is available.

### Method
Constructor

### Signature
```php
public function __construct()
```

### Parameters
None.

### Exceptions
- **BarcodeException** - Thrown if neither the GD library nor the Imagick extension is installed.

### Example
```php
$renderer = new \Picqer\Barcode\Renderers\PngRenderer();
```
```

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

### TypePostnet class declaration with $barlen array

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/types-postal.md

Defines the TypePostnet class that implements TypeInterface. The protected $barlen array maps each digit to five bar heights, where 2 represents a long bar and 1 a short bar. This is the starting point for the POSTNET barcode implementation.

```php
class TypePostnet implements TypeInterface
{
    /** @var array<int, array{int, int, int, int, int}> */
    protected array $barlen = [ /* digit -> 5 heights (2=long, 1=short) */ ];

```

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

### TypeCode128C class definition

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/types-code128.md

Forced subset C variant. Requires an even number of digits; optionally lead with char 241 (FNC1) to emit FNC1 code. Throws InvalidLengthException for odd length and InvalidCharacterException for non-digit pairs. Uses start code 105.

```php
class TypeCode128C extends TypeCode128
{
    protected ?string $type = 'C';
}
```

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

### render

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/html-renderer.md

Renders a Barcode object as inline HTML markup.

```APIDOC
## render

### Description
Renders a Barcode object as inline HTML markup, producing a container div with absolutely positioned bar divs. The method accepts optional width and height parameters to control the container dimensions.

### Method
render

### Signature
`public function render(Barcode $barcode, float $width = 200, float $height = 30): string`

### Parameters
- **$barcode** (Barcode) - Required - Encoded barcode
- **$width** (float) - Optional, default `200` - Container width in px; floats supported (values rounded to 3 decimals)
- **$height** (float) - Optional, default `30` - Container height in px

### Return
- **string** - HTML markup with the structure: `<div style="font-size:0;position:relative;width:200px;height:30px;[background-color:rgb(...)]">` containing bar divs with `background-color:rgb(r,g,b);width:Wpx;height:Hpx;position:absolute;left:Lpx;top:Tpx` and `&nbsp;` content.

### Notes
- Container style includes `background-color:rgb(...)` only when a background color is set.
- Bar dimensions are computed as: `$barWidth = round(($bar->getWidth() * $widthFactor), 3)` where `$widthFactor = $width / $barcode->getWidth()`; `$barHeight = round(($bar->getHeight() * $height / $barcode->getHeight()), 3)`; `$positionVertical = round(($bar->getPositionVertical() * $height / $barcode->getHeight()), 3)`.
- Only bars (`isBar()` and `$barWidth > 0`) emit a `<div>`; spaces only advance `$positionHorizontal`.
- Each bar div contains `&nbsp;` so it is rendered even with `font-size:0`.
- Quirk: `top:` is written without a unit when `$positionVertical === 0` (`top:0`), and with `px` otherwise.
```

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

### setBackgroundColor method

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/dynamic-html-renderer.md

Method signature for setBackgroundColor. Accepts an RGB triplet or null; null results in no background style on the container (transparent).

```php
/** @param array{int, int, int}|null $color */
public function setBackgroundColor(?array $color): self
```

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

### Barcode::getBars method

Source: https://github.com/picqer/php-barcode-generator/blob/main/_autodocs/api-reference/barcode.md

Returns an ordered list of bar/space segments, left to right. Renderers iterate this list to draw the symbol.

```php
/** @return BarcodeBar[] */
public function getBars(): array

```
Tokens:
Raw