Laravel QR Decoder

A cross‑platform Laravel package for decoding QR codes from PNG images using Python (zxing-cpp).

This package wraps a Python decoder inside a virtual environment and exposes a clean Laravel API. It works on Windows and Linux using OS‑specific wrapper scripts.

Features

• ✅ Cross‑platform (Windows & Linux)
• ✅ Python isolated via venv
• ✅ No global Python dependencies
• ✅ Secure execution via Symfony Process
• ✅ Works with logos / low‑contrast QR codes

Requirements

• PHP >= 8.2
• Laravel >= 11
• Python >= 3.13

Installation

Install the package (local / path repository)

// composer.json
{
  "repositories": [
    {
      "type": "path",
      "url": "packages/laravel-qr-decoder"
    }
  ]
}

composer require mapo-89/laravel-qr-decoder

Publish config

php artisan vendor:publish --tag=config

Configure Python path

Edit config/qr-decoder.php:

return [
    'python_path' => base_path('python/qr-decoder'),
    'timeout' => 10,
];

Run the installer (recommended)

php artisan qr-decoder:install

This command will:

• Create a Python virtual environment in the configured path
• Install all required Python dependencies
• Work on Windows and Linux

Usage

This package does not provide controllers or views. It exposes a single service (QrDecoder) that can be used inside your application’s controllers, APIs, jobs or commands.

Example Use Cases

1. Decode an already uploaded file on button click:

use Mapo89\QrDecoder\QrDecoder;

$result = app(QrDecoder::class)->decode(
    storage_path('app/qr_uploaded_file.png')
);

2. Upload a file and decode immediately:

public function uploadAndDecode(Request $request, QrDecoder $decoder)
{
    $request->validate([
        'qrpng' => ['required', 'file', 'mimes:png', 'max:5120'],
    ]);

    // Store temporarily
    $path = $request->file('qrpng')->store('qr-decoder');
    $fullPath = storage_path('app/private/' . $path);

    try {
        $result = $decoder->decode($fullPath);
    } catch (\Throwable $e) {
        $result = null;
        // Handle error if needed
    } finally {
        if (file_exists($fullPath)) {
            @unlink($fullPath);
        }
    }

    return response()->json(['result' => $result]);
}

Note: The controller should live in your application, not in this package. If you need a UI, build it in your application or in a separate package that depends on this one.

Dependency Injection

public function decode(QrDecoder $decoder)
{
    return $decoder->decode($path);
}

Configuration

return [
    'python_path' => base_path('python/qr-decoder'),
    'timeout' => 10,
];

Directory Structure

laravel-qr-decoder/
├── src/
│   ├── QrDecoder.php
│   ├── QrDecoderFacade.php
│   └── QrDecoderServiceProvider.php
│
├── python/
│   ├── decode_qr.py
│   ├── requirements.txt
│   ├── run_qr_decoder
│   ├── run_qr_decoder.bat
│   └── venv/
│
├── config/
│   └── qr-decoder.php
│
├── composer.json
└── README.md

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Manuel Postler
• All Contributors

License

The MIT License (MIT). Please see License File for more information.

Laravel Package Boilerplate

This package was generated using the Laravel Package Boilerplate.