- How do I install sprain/swiss-qr-bill in a Laravel application?
- Install it with Composer as a normal dependency, since the package is framework-agnostic and not tied to Laravel's release cycle. In Laravel, bind a thin adapter or service class in the container that maps your invoice and company data into the library's DTOs and returns the generated PDF. Keep the library's classes out of your controllers and domain models so the QR-bill renderer stays a replaceable output adapter. Pin an exact version and confirm the PHP constraint matches your production runtime.
- Which Swiss Payment Standards version does sprain/swiss-qr-bill target?
- The library implements the Swiss QR-bill specification, but you should confirm the exact Swiss Payment Standards version it targets before going live, because the standard is revised periodically. Check the package changelog and release history, then validate output against the current official specification and validator. Treat this as a compliance requirement rather than a one-off install task, and re-check it on every upgrade.
- Does the library validate QR-IBAN, IBAN, QRR and SCOR references?
- The library builds the QR payload including creditor and debtor details, IBAN or QR-IBAN, reference type, amount and currency, but you should not assume every rule is enforced for you. Write your own validation for the reference type pairing, since QRR references require a QR-IBAN while SCOR references use a regular IBAN. Add unit tests covering valid and deliberately invalid inputs so a malformed bill fails loudly instead of being generated silently. Confirm the actual validation behaviour by inspecting the source for the version you pin.
- Can I generate Swiss QR-bill PDFs in a queued Laravel job?
- Yes, this fits well in a queued job. Map your invoice data into the library's request objects inside the job, generate the PDF, store it in object storage, and attach the stored file to emails or a customer portal. Verify that the required PHP extensions and fonts are present on both web and queue worker containers, since missing fonts or PDF dependencies can produce broken or non-scannable output. Keep the generated file as the artifact so you never need to render the same bill twice.
- Are there PHP version or extension requirements I need to check for Laravel?
- Check the composer.json PHP constraint against your production Laravel version, and confirm any PDF or font dependencies used for rendering are installed on every environment. Run the package in a container that mirrors production rather than relying on a local success. If your queue workers use a separate image, test generation there too, because rendering problems often only appear in the worker environment.
- Can I use sprain/swiss-qr-bill outside of Laravel?
- Yes, it is a framework-agnostic Composer package under the MIT license, so it works in plain PHP, Symfony, or any PSR-compatible application. In Laravel you simply add a service wrapper for dependency injection and configuration. This portability is useful as an escape hatch: if you later swap renderers, only the adapter changes and your billing domain stays untouched.
- How do I test that generated QR bills actually scan at a Swiss bank?
- Do not accept 'a PDF was produced' as a passing test. Build golden-file and acceptance tests with representative invoices covering QR-IBAN, regular IBAN, QRR, SCOR and edge cases like maximum reference lengths or unusual addresses. Then run real scans with bank mobile apps and check the output against an official validator. Keep a written validation checklist for finance or operations to sign off before rollout.
- Is sprain/swiss-qr-bill actively maintained and safe for production use?
- The package is a small, focused library with modest ecosystem signals, so verify its release and tag history before adopting it. Review the latest release date and recent commits, and confirm the project tracks revisions to the Swiss QR-bill standard. Security risk is low because the library needs no network access or payment credentials, but correctness and maintenance risk are higher. Assign an owner to review releases quarterly and keep a documented fallback if upstream stalls.
- Does the package handle payment state, reconciliation, or payment initiation?
- No, and you should not use it for that. It is a document renderer: map invoice and payment data into it, get a PDF or image back, and keep all payment state, reconciliation and ledger logic in your own domain. This keeps compliance-sensitive rendering isolated from billing logic and makes the library easy to replace. Treat the output as a compliance-sensitive artifact that should be archived for audit.
- How do I roll out QR-bill generation without breaking existing invoice processes?
- Put the new generator behind a feature flag and run it in parallel with your current manual or third-party process on a sample of invoices. Validate those outputs with bank scanners and reference validators, then switch over by market or customer segment. No database migration is inherently required, so rollback is simply reverting to the previous path. Add logging and observability around generation failures so silent invalid output is caught quickly.