Qr Code Bundle Laravel Package

Getting Started

First, resolve the identity mismatch. The Composer package is yellowskies/qr-code-bundle, but the repository is AntoineTesson/QRcodeBundle. Before anything else, run composer show yellowskies/qr-code-bundle and read the source/support/homepage fields plus composer.json in the repo root. You are likely consuming a maintained fork or rename, and you need to know which commit history you're betting on.

Second, decide whether you need the bundle at all. This is a Symfony bundle — it ships a Bundle class, a DependencyInjection extension, and a Twig extension. Laravel has none of those concepts, so you cannot composer require it and get a working QR generator. What you actually want is the generator library it wraps. Check require in its composer.json (historically these bundles sit on top of endroid/qr-code or a Bacon/Picqer variant). Install that directly:

composer require endroid/qr-code   # or whatever the bundle's composer.json pins

Where to look first in this repo:

• composer.json → the real generator dependency and the PHP/Symfony constraints
• src/Twig/ → the only genuinely reusable logic: how payload + options map to a rendered image
• src/DependencyInjection/Configuration.php → the defaults (size, margin, error correction, format) worth copying into config/qr.php

First use case: an invoice or receipt that needs a verification URL encoded as a QR, rendered into a PDF. That's the 80% case and it exercises the two things you must get right — payload encoding and output format (SVG for print, PNG for email).

Implementation Patterns

Wrap the generator in one app service, not scattered calls.

// app/Services/QrCode.php
final class QrCode
{
    public function dataUri(string $payload, array $opts = []): string { /* ... */ }
    public function svg(string $payload, array $opts = []): string { /* ... */ }
}

Merge config('qr.defaults') (size, margin, ECC level, format) under the caller's $opts. Every bundle's value is precisely this: centralised defaults. Recreate it in five lines.

Blade directive instead of a Twig function. The Twig extension is the part you throw away. Register a directive or component:

Blade::directive('qrcode', fn ($expr) => "<?php echo app(\App\Services\QrCode::class)->dataUri($expr); ?>");

Route-served images beat data URIs for anything user-facing. A data URI inlines the whole PNG into your HTML, bloats responses, and is blocked or stripped by several email clients. Prefer a cacheable route:

Route::get('/qr/{token}.png', QrController::class)
    ->middleware('signed')
    ->name('qr');

Key the cache on sha1($payload . serialize($options)) and store the bytes — QR generation is cheap but not free, and a 500-row order export will make you notice.

Storage vs regenerate. For anything that must be reproducible (printed tickets, compliance docs), generate once, store in storage/app/qr/, and serve via signed URL. For ephemeral dashboard previews, generate on the fly. Don't mix the two in one code path.

Testing. Never assert on image bytes. Assert on the payload string and the config resolution:

$this->assertSame($url, $this->qr->payloadFor($order));
$this->assertStringStartsWith('data:image/svg+xml', $this->qr->dataUri('test'));

Gotchas and Tips

The bundle is not installable in Laravel. No auto-discovery, no Twig, no services.yaml. If you install it anyway you'll get a Bundle class that nothing instantiates and a Twig extension that nothing calls. Budget the port, don't fight it.

Signal quality is low: 36 stars, 0 dependents, score 0.42. Treat it as documentation, not as a dependency. Read the source, copy the defaults, depend on the underlying generator library — which has its own maintainers and release cadence. If you do adopt the fork directly, pin an exact version in composer.json; there is no ecosystem pressure keeping its API stable.

Image backend requirements. Raster output typically needs GD or Imagick. Check both php -m and your Docker image; SVG output usually needs neither, which is another reason to default to SVG for print and only rasterise when a downstream consumer demands it.

Payload size vs error correction. Higher ECC levels shrink effective capacity. A long signed URL at ECC-H can silently push you into a denser QR that phones struggle to read at small print sizes. Keep payloads short (a short token that redirects, not a full URL with query params), and test-scan at actual print dimensions, not on a 27" monitor.

data: URIs and email. Several major clients strip them. If the QR is inside a notification email, it must be a hosted URL with a real Content-Type.

PDF libraries disagree about SVG. dompdf and snappy handle SVG differently; wkhtmltopdf-era stacks often rasterise poorly. Verify your specific PDF driver before committing to a format, and keep the format switchable via config.

UTF-8 payloads. Non-ASCII content may need explicit byte/UTF-8 mode depending on the underlying generator; otherwise you get a scannable code that decodes to mojibake. Encode URLs, not free-text labels.

Extension points worth knowing in the original. The bundle's DI configuration is the cleanest reference for sane defaults; the Twig extension is the cleanest reference for the options→render pipeline. If you later add barcode support, mirror the same service shape (Barcode::svg()) so the two share caching and routing.

Debugging checklist when a code won't scan: dump the exact payload string first (not the image), confirm the format you think you're producing via Content-Type, then check print DPI/margin. Nine times out of ten the problem is the payload, not the generator.