README

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

Decode an already uploaded file on button click:

use Mapo89\QrDecoder\QrDecoder;

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

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 info@postler.de instead of using the issue tracker.

mapo-89 / laravel-qr-decoder

Maintainers

Details