Skqrpayment Laravel Package

Technical Evaluation

Architecture fit This is a single-purpose peripheral utility, not an architectural component. It occupies one narrow slot in the payment stack: converting an order's payment details (IBAN, amount, variable symbol, message) into a Slovak Pay by Square (BySquare) payload and, typically, a QR image. It does not initiate payments, talk to a PSP, handle webhooks, reconcile settlements, or manage refunds — all of that remains your responsibility. Treat it as a serialization library at the edge of the domain, analogous to a PDF or barcode generator.

Concretely, it belongs behind a boundary:

• Domain layer owns the concept of a payable order (amount, currency, IBAN, reference).
• Adapter layer wraps rikudou/skqrpayment and returns a payload string / image.
• Presentation layer renders the QR at checkout or on an invoice.

If the library is called directly from controllers or Blade templates, you will inherit its data model and API surface in your application code — avoid that.

Note the important distinction: this is Slovak BySquare, a binary format (LZMA-compressed, Base32Hex-encoded), not the Czech "QR Platba"/SPD text URI format. They are not interchangeable, and mixing them up in a SK/CZ dual-market product is the most likely integration failure.

Integration feasibility High in the mechanical sense: Composer install, MIT license, no service provider required for plain-PHP use, no network calls, no credentials, no external services. Wrapping it in a Laravel service provider and a QrPaymentGenerator interface is an afternoon of work.

The real feasibility questions are environmental, not API-shaped:

• Compression dependency. BySquare requires LZMA. If the package ships a pure-PHP LZMA implementation (likely, since ext-lzma is rarely enabled), expect meaningful CPU and memory cost per generation — acceptable at checkout, unacceptable on a hot listing page.
• QR rendering dependency. Usually delegated to a QR library (endroid/qr-code, bacon/bacon-qr-code, or similar). Version conflicts with a QR library you already use are the most probable install-time friction.
• PHP version floor. Recent release date (2025-10-10) suggests modern syntax (typed properties, possibly enums/readonly). Verify it satisfies your platform's PHP constraint and, more importantly, that your platform satisfies its constraint.
• Extensibility. Whether QR rendering is decoupled from payload generation determines how much of the library you must accept as-is.

Technical risk

Key questions to raise with the maintainer or in a spike

1. Does it require ext-lzma, or bundle a pure-PHP implementation — and what are the measured time/memory costs for a typical payload?
2. Which BySquare spec version does it target, and is that documented in the README?
3. Does it validate IBAN (mod-97), amount precision, currency, and the message charset, or does it trust the caller?
4. Is there an official test-vector suite in the repo, derived from the published spec?
5. Is QR image generation built in, and is the renderer swappable?
6. What is the release cadence and issue-response history over the last 24 months?
7. Does it support the full feature set (standing orders, direct debit, multiple payments per code) or only single payment orders?

Integration Approach

Stack fit Good for Laravel/PHP monoliths or services already rendering documents (invoices, order confirmations, emails). It is framework-agnostic, which is a feature: bind it in a service provider, keep it out of the framework's event/queue machinery, and it will survive a Laravel major-version upgrade. It fits poorly if your checkout is a separate SPA or mobile client that would need the payload generated server-side and cached — plan for an API endpoint that serves a pre-rendered image or payload rather than generating on demand.

Migration path Greenfield rather than migration: with 0 dependents there is no incumbent to move off. The practical migration risk is the Czech-to-Slovak trap described above. If you already emit Czech SPD QR codes for a CZ market, do not attempt to reuse that code path for SK orders — they are different formats, different encodings, and require different scanners.

For an in-house alternative: the BySquare spec is public, and the payload format itself is small. The LZMA compression step is the only genuinely non-trivial part, which is exactly the argument for consuming this library rather than reimplementing it. A reasonable hedge is to wrap it such that a fork or a replacement can be dropped in without touching callers.

Compatibility Verify, in order:

1. PHP constraint intersection with your runtime.
2. QR library version conflict against anything already in composer.lock.
3. Whether image output requires GD or Imagick, and whether your containers have it.
4. Memory limit headroom if LZMA is pure-PHP (memory_limit of 128M is common and may be tight under concurrency).

Sequencing

1. Spike (1–2 days). Install in a throwaway branch. Generate payloads for three real order scenarios: normal payment, minimum amount, long/edge-case message.
2. Interoperability gate (the critical step). Scan the generated codes with at least three Slovak banking apps across iOS and Android (Tatra banka, Slovenská sporiteľňa, VÚB, ČSOB, mBank). Confirm the pre-filled IBAN, amount, and message match exactly. Do not proceed past this gate on the strength of unit tests alone. This is the only reliable ground truth.
3. Adapter + snapshot tests. Implement QrPaymentGenerator with the library behind it. Capture the generated payload string as a golden-file test so any dependency upgrade that changes output fails loudly.
4. Caching. Persist the generated payload/image on the order at creation or first render; never regenerate per page view.
5. Laravel wiring. Service provider binding, config entry, feature flag.
6. Observability. Log generation failures and, if possible, track a "customer reports QR not working" support tag for the first quarter.
7. Rollout. Behind a flag for SK orders only; keep the previous manual-payment-instructions path available as a fallback.

Operational Impact

Maintenance Low-effort under normal conditions — the domain changes slowly and the library is small. The risk is not churn but abandonment. With one maintainer, 37 stars, and zero dependents, plan for the realistic scenario where you become the de facto maintainer. MIT licensing makes forking legally trivial; the operational cost is owning the LZMA and spec-compliance knowledge. Budget for a periodic (semi-annual) review of the BySquare spec against the library's implementation, and pin the version rather than tracking ^.

Support Community-only: GitHub issues, no SLA, no commercial backing. Response times are unverifiable from the metrics available and should be assumed to be best-effort. Escalation path is a fork. This is acceptable for a document-generation utility and unacceptable if the QR code is the only way a customer can pay — which argues strongly for retaining a manual bank-transfer fallback in the UI.

Scaling The workload is CPU-bound and per-order, not per-request, if you cache correctly. Volume profile is modest: one generation per order, amortized to zero. The genuine scaling concern is burst concurrency — a flash sale producing hundreds of orders per minute, each triggering compression and image rendering, inside PHP-FPM workers with bounded memory. Mitigations: pre-generate asynchronously in a queue job at order creation, cap concurrency on the generation path, keep the QR render off any synchronous user-facing request, and monitor worker memory.

Failure modes to instrument

• Silent invalidity — payload generated, bank app rejects it. Highest business impact, lowest detectability. Mitigate with the manual-interop gate at launch and a support-ticket tag for early detection.
• Memory exhaustion during compression under load; surfaces as 500s at checkout, which is revenue-affecting.
• Charset mangling in the payment message field — diacritics or over-length strings producing a rejected or garbled reference.
• IBAN validation gaps letting a malformed IBAN through to a scanned-but-unusable code.
• Dependency upgrade drift silently altering payload bytes; caught by golden-file tests if you invest in them.
• Spec revision making previously valid codes non-compliant; caught only by external monitoring, not by tests.

Ramp-up A competent PHP developer is productive with the library in under a day — the API is simple and the README covers the happy path. The real ramp-up is domain knowledge: the BySquare encoding, the LZMA/Base32Hex pipeline, Slovak IBAN and symbol conventions, and the banking-app interoperability quirks. That knowledge is not in the library's docs and is not commonly held outside the SK/CZ market. Expect 1–2 weeks for one engineer to reach genuine confidence, most of it spent on the interop gate rather than on code. Document the verification procedure — which apps, which devices, which scenarios — because it will need to be repeated after every dependency bump.