Qr Payment Bundle Laravel Package

Technical Evaluation

Architecture fit. rikudou/qr-payment-bundle is a Symfony bundle — not a Laravel package — that wires the container-agnostic rikudou/qr-payment library into Symfony's service container. For a Laravel codebase the bundle scaffolding is largely irrelevant; what matters is whether the underlying library can be consumed as a bounded, dependency-free utility. The correct architectural placement in a Laravel app is a single infrastructure adapter (e.g. PaymentQrGenerator) that turns invoice/checkout data into a QR payload and image. It must not own payment state, reconciliation, or checkout orchestration — a QR code is a static, one-way payment instruction with no callback, webhook, or settlement signal.

Integration feasibility. Feasible, but only by treating the bundle as optional and the core library as the real dependency. Laravel does not auto-discover Symfony bundles, so any path through the bundle requires manually registering services in a service provider — almost always more effort than value. The recommended route is: drop the bundle, composer require rikudou/qr-payment, wrap the framework-agnostic factory (createCzechQrPayment(), createSlovakQrPayment(), createEuropeanQrPayment()) behind an internal interface, and bind it in AppServiceProvider. Budget a small, time-boxed spike to confirm the core library has no hidden Symfony coupling and that transitive dependencies (Symfony components, QR image rendering) resolve cleanly against the target PHP/Laravel versions.

Technical risk. High relative to the business criticality, for three reasons. First, adoption signals are weak: 3 stars, 0 dependents, low score, single maintainer, WTFPL license with no warranty or support. Second, correctness risk is asymmetric — QR formats must be byte-exact for banking-app consumption; a malformed IBAN, decimal separator, currency code, or diacritic handling turns into a failed payment and a support ticket, and the failure is silent until a real customer scans it. Third, upstream durability is unproven, so we should assume we will own this integration (and possibly a fork) for its lifetime. The WTFPL name reliably triggers legal review even though it is functionally public domain — get sign-off before it lands in any payment-adjacent flow.

Key questions.

• Does it only generate QR codes, or also validate/parse them? (Generation-only is fine for our use case.)
• Which standards are actually covered in the version we would pin: Czech SPAYD/QR Platba, Slovak PAY by square, EPC069-12/SEPA, or all three — and to what spec revision?
• Is the core fully usable without Symfony DI/config, and does it emit a plain payload string (getQrString()) we can persist and test independently of the image renderer?
• What are its PHP, Symfony-component, and QR-renderer version constraints, and do they resolve against our current Laravel footprint?
• Are there tests and golden fixtures against the published spec examples for each standard?
• How are IBAN/BIC validation, amount precision, currency, variable symbol, message length, and UTF-8/diacritics handled?
• Can we fork, vendor, or swap the implementation without touching product code — i.e., is the seam clean enough?

Integration Approach

Stack fit. Treat this as a narrow PHP utility wrapped by a Laravel-native QrPaymentGenerator interface, not as a framework integration. The seam should expose domain-friendly methods (generateForInvoice(Invoice $invoice): QrPayment) and hide the factory, format selection, and image rendering. Bind defaults — our IBAN, currency policy, comment format, error-correction level — in one service provider so controllers, jobs, and PDF generation share identical behavior. Keep Symfony-specific config out of controllers and queued jobs. Drive format selection from a payment-rail/currency field on the model (CZK account → SPD; EUR/IBAN → EPC; SK account → Slovak PAY by square), never from app()->getLocale().

Migration path. Start with a standalone spike (a test command or tinker script) that generates payloads for one real invoice in each target standard and logs getQrString() — the payload is short and human-readable, so malformed fields are visible before you debug images. If it works, wrap behind the interface and add golden fixture tests. If it fails or the constraints fight our stack, replace the implementation with an internal SPAYD/EPC generator without changing any caller. Do not make it a hard dependency in core payment flows.

Compatibility. Verify Composer constraints against the target Laravel and PHP versions before committing, and inspect transitive dependencies — especially Symfony components that may already be pinned by Laravel, and any QR image library. Confirm whether Laravel's own Symfony components satisfy the core library's expectations or whether manual instantiation is required. Pin the version (exact or tight range) and treat upgrades as deliberate, tested events rather than composer update fallout.

Sequencing.

1. Define supported countries/standards and acceptance criteria (which banks, which formats, which fields).
2. Run the compatibility and payload-correctness spike.
3. Build the Laravel adapter, interface, config, and binding.
4. Add fixture-based golden tests per standard and validate real codes against representative banking apps.
5. Persist getQrString() on the invoice/order record; render images on demand.
6. Pilot behind a feature flag on low-risk invoices, with manual bank-details text always shown as a fallback.
7. Decide retain / fork / replace based on pilot results, and document that decision.

Operational Impact

Maintenance. Expect to own the integration and likely the library long-term. Zero dependents and low upstream activity mean no community safety net; WTFPL permits forking but provides no support. Assign an internal owner, pin the version, and document the fork-vs-replace trigger (e.g. no release in N months, or a spec change we need). The seam behind QrPaymentGenerator is the insurance policy — preserve it.

Support. There is no vendor to escalate to. Runbooks must cover: invalid-QR reports, bank-app incompatibility, Composer/PHP upgrade breakage, and the fallback to printed bank details. Support staff need a clear scope statement — which countries, formats, and banks are in coverage, and what to tell a customer whose bank rejects a code. Any incident lands on the internal team.

Scaling. QR generation is stateless and lightweight — no special infrastructure, no credentials, no network calls, so it scales horizontally for free. The realistic scaling concern is support volume from malformed codes, not compute. For batch invoice runs, generate in queued jobs and cache the rendered PNG per invoice; don't re-encode the same payload twice in a request, and don't persist images when the payload plus a render-on-demand is sufficient.

Failure modes. Silent output mismatch that only surfaces when a customer scans in their banking app; invalid IBAN/amount/currency formatting; encoding or diacritic errors in the comment field; QR renderer regression on upgrade; Composer/PHP breakage from transitive constraints; unmaintained upstream; and tampering with a QR payload embedded in a generated PDF or email. Mitigate with golden tests against published spec examples, real bank-app validation before launch, feature flags, payload logging during rollout, and a manual payment-details fallback on every artifact that carries a code.

Ramp-up. Low for a developer to wire a basic generator and get a payload rendering; moderate to get regional standards, encoding, and bank-app behavior right; non-trivial for support and product to learn the country-specific expectations and escalation paths. Given the weak adoption signals, the defensible TPM stance is: pilot only, wrap tightly behind an internal interface, pin and test, and be ready to fork or replace without disturbing product code.