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.

Table of Contents

1. Introduction
2. Installation
3. Quick Start
   • Using in Symfony
   • Using in Standalone PHP Applications
4. Configuration
   • Symfony Configuration
   • Standalone Configuration
5. Components Overview
   • Encoders
   • Decoders
   • Formatters
   • Generators
   • Repositories
   • Processors
6. Extending the Library
7. Customization
8. Examples
9. Testing
10. Contributing
11. Credits
12. 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

1. Install the library (see Installation).
2. Configure the bundle in config/packages/barcode.yaml (see Symfony Configuration).
3. 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

1. Install the library (see Installation).
2. 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:

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

Feel free to open issues for bugs or feature requests.

11. Credits

This library leverages the following third-party libraries:

• chillerlan/php-qrcode
• picqer/php-barcode-generator
• endroid/qr-code

12. License

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

Enjoy using the Barcode Bundle! 😊