README

The Barcode Bundle is a flexible and extensible library for generating, processing, encoding, decoding, and formatting barcodes, DataMatrix and QR codes. It is designed to work seamlessly with Symfony applications but can also be used in standalone PHP projects. The library aims to support established standards such as GS1 and ANSI — either out of the box or through third-party and custom extensions.

Introduction
Installation
Quick Start
- Using in Symfony
- Using in Standalone PHP Applications
Configuration
- Symfony Configuration
- Standalone Configuration
Components Overview
Extending the Library
Customization
Examples
Testing
Contributing
Credits
License

1. Introduction

The Barcode Bundle provides a complete solution for working with barcodes and QR codes. It supports:

Generating barcodes and QR codes.
Encoding data into various formats.
Decoding barcodes and QR codes into structured data.
Formatting barcodes for human-readable or standard-compliant outputs.
Extending and customizing components like formatters, encoders, decoders, and processors.

Whether you're building a Symfony application or a standalone PHP project, this library is designed to be modular, extensible, and easy to use.

2. Installation

Requirements

PHP 8.1 or higher.
Symfony 6.0 or later (for Symfony integration).
Composer 2.0 or later.

Install via Composer

To install the library, run:

composer require nkamuo/barcode-bundle:dev-main

For Symfony applications, this will:

Register the Nkamuo\Barcode\BarcodeBundle in config/bundles.php.
Copy the default configuration to config/packages/barcode.yaml.

If the bundle is not automatically registered, add it manually:

// config/bundles.php
return [
    // ...
    Nkamuo\Barcode\BarcodeBundle::class => ['all' => true],
];

3. Quick Start

Using in Symfony

Install the library (see Installation).
Configure the bundle in config/packages/barcode.yaml (see Symfony Configuration).
Use the Barcode Processor:

use Nkamuo\Barcode\BarcodeProcessorInterface;

/** @var BarcodeProcessorInterface $processor */
$processor = $container->get(BarcodeProcessorInterface::class);

// Generate a barcode for Raw-Material
$barcode = $processor->generate([
    'prefix' => 'RM-',
    'standard' => 'CUSTOM'
    ]);
echo $barcode->getValue(); // Outputs: RM-00000001

// Encode the barcode into a QR code
$encoded = $processor->encode($barcode, 'QR', 'PNG');
file_put_contents('barcode.png', $encoded);

// Decode a barcode
$decodedBarcode = $processor->decode('0101234567890128', 'EAN-13');
echo $decodedBarcode->getValue(); // Outputs: 0101234567890128

Using in Standalone PHP Applications

Install the library (see Installation).
Set up the components manually:

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

use Nkamuo\Barcode\BarcodeProcessor;
use Nkamuo\Barcode\Factory\BarcodeFactory;
use Nkamuo\Barcode\Repository\InMemoryBarcodeRepository;
use Nkamuo\Barcode\Formatter\ChainBarcodeFormatter;
use Nkamuo\Barcode\Encoder\ChainBarcodeEncoder;
use Nkamuo\Barcode\Decoder\ChainBarcodeDecoder;
use Nkamuo\Barcode\Generator\ChainBarcodeGenerator;

// Initialize components
$factory = new BarcodeFactory();
$repository = new InMemoryBarcodeRepository();
$formatter = new ChainBarcodeFormatter([...]); // Add formatters
$encoder = new ChainBarcodeEncoder([...]);     // Add encoders
$decoder = new ChainBarcodeDecoder([...]);     // Add decoders
$generator = new ChainBarcodeGenerator([...]); // Add generators

// Create the processor
$processor = new BarcodeProcessor(
    factory: $factory,
    encoder: $encoder,
    decoder: $decoder,
    generator: $generator,
    formatter: $formatter,
    repository: $repository
);

// Use the processor
$barcode = $processor->generate([
    'prefix' => 'FXT',
    'pad_lenth' => 5,
    ]);
echo $barcode->getValue(); // Output: FXT0000012

4. Configuration

Symfony Configuration

The default configuration file is located at config/packages/barcode.yaml. You can customize the following settings:

barcode:
    default_storage: 'in_memory'             # Default storage for barcodes
    enabled_formatters: ['qrcode', 'barcode'] # List of formatters to enable
    processors:
        default:                              # Default processor chain
            encoders: ['basic_encoder']
            decoders: ['default_decoder']
            formatters: ['default_formatter']

Standalone Configuration

For standalone applications, you can configure components manually by instantiating them and passing the required dependencies (see Quick Start).

5. Components Overview

Encoders

Encoders convert BarcodeInterface instances into specific formats like QR codes, Data Matrix, or PNG images.
See the Encoders Documentation for more details.

Decoders

Decoders interpret raw barcode data and convert it into structured BarcodeInterface instances.
See the Decoders Documentation for more details.

Formatters

Formatters provide a way to format barcode data into human-readable or standard-compliant strings.
See the Formatters Documentation for more details.

Generators

Generators create new barcodes based on specific contexts or configurations.
See the Generators Documentation for more details.

Repositories

Repositories manage the persistence and retrieval of barcodes.
See the Repositories Documentation for more details.

Processors

Processors orchestrate the interaction between all components, providing a unified interface for barcode operations.
See the Processors Documentation for more details.

6. Extending the Library

The library is designed to be extensible. You can add custom formatters, encoders, decoders, and processors by implementing the respective interfaces.
Refer to the Extending Documentation for detailed guides on how to extend each component.

7. Customization

You can customize the library by:

Adding custom formatters, encoders, decoders, or generators.
Creating custom processors to handle specific workflows.
Implementing your own repository for barcode storage (e.g., database-backed).

8. Examples

Generate and Encode a Barcode

$barcode = $processor->generate(['type' => 'GTIN', 'value' => '0123456789012']);
$encoded = $processor->encode($barcode, 'QR', 'PNG');
file_put_contents('barcode.png', $encoded);

Decode a Barcode

$decodedBarcode = $processor->decode(
    data: ']d201034531200000111719112510ABCD1234',
    symbol: null, //DataMatrix
    format: null,
    context: ['standard' => 'GS1']
);
echo $barcode->getAttribute('01');// Output: 03453120000011 [GTIN]
echo $barcode->getAttribute('10');// Output:  ABCD1234 [Batch Number]
echo $barcode->getAttribute('17');// Output:  191125 [Expiry Date]

Format a Barcode

$formatted = $formatter->format($barcode, 'LABEL');
echo $formatted;

9. Testing

Run the tests using PHPUnit:

composer install
vendor/bin/phpunit tests/simple

10. Contributing

Contributions are welcome! Please follow these steps:

Fork the repository.
Create a new branch for your feature or bugfix.
Write tests for your changes.
Open a pull request.

Feel free to open issues for bugs or feature requests.

11. Credits

This library leverages the following third-party libraries:

12. License

This library is licensed under the MIT License. See the LICENSE file for more details.

Enjoy using the Barcode Bundle! 😊

nkamuo / barcode-bundle

Maintainers

Details