verschoof/bunq-api-bundle
A Symfony bundle that integrates the bunq banking API, providing configuration and service wiring to help PHP applications connect to bunq accounts, payments, and related endpoints.
Architecture fit. This package is a Laravel wrapper around the bunq-api client library. v2.0.0's only stated change is that the underlying bunq-api lib now uses RefreshSessionMiddleware. Architecturally this is a positive direction: session/token refresh moves out of application code and into the HTTP transport layer, which is the idiomatic Laravel place for cross-cutting request concerns. For teams currently hand-rolling token refresh around the client, this should reduce bespoke code and the class of bugs that comes with it. Confidence in this read is moderate — the release note is one line and there is no changelog, diff, or migration guide in the supplied data.
Integration feasibility. Marked as a major version (2.0.0), which by semver convention signals breaking change, and the change is a dependency-level behavior shift rather than a new feature. Feasibility depends on facts not present in the release note: the bunq-api version floor, PHP/Laravel version constraints, and whether the wrapper's public API changed. Realistically this is a low-to-medium effort upgrade for a small integration and a medium effort one for anything with existing custom refresh logic or a persisted session/device token store.
Technical risk. The material risks are not in the middleware itself but in what it implies:
RefreshSessionMiddleware must read and write a session/device token somewhere. If that store moves (config file → cache → database), existing deployments will break silently on first refresh.GET, dangerous for payment/request-inquiry POSTs. Double-submission of a payment is a financial and compliance incident, not a bug. This is the single highest-severity question in this release.Key questions. Answer these before scheduling the upgrade: (1) Does the middleware retry failed requests after refresh, and is retry suppressed for non-idempotent endpoints? (2) Where is session/device state persisted, and is it shared across processes and hosts? (3) Is there a lock preventing concurrent refreshes? (4) What are the PHP, Laravel, and Guzzle constraint changes? (5) Is there a migration guide, and does it list renamed config keys? (6) Does an expired refresh token now fail differently, and how is re-authorization surfaced to the operator?
Stack fit. The middleware pattern fits Laravel's HTTP kernel, but the fit is only clean if session state lives in a shared store. Single-server, single-worker deployments will work regardless. Deployments using Horizon, multiple queue workers, Laravel Octane, or more than one app server should treat shared, lockable session storage (Redis or database, not file or array) as a prerequisite rather than an afterthought.
Migration path. Pin the current major explicitly in composer.json so the 2.0.0 bump cannot arrive via a transitive composer update. Then: branch → bump to 2.0.0 → resolve dependency conflicts → run the existing test suite → integrate against the bunq sandbox → exercise a full token-expiry cycle deliberately (force expiry rather than waiting) → promote. Because this is a major bump with a one-line release note, the upgrade should be treated as an unverified change until the sandbox run confirms behavior, not as a routine patch.
Compatibility. Confirm PHP and Laravel support matrices against the project's actual versions before committing to a window. Check for conflicts with other packages pinning bunq-api or Guzzle. If the wrapper previously exposed session-handling methods that applications called directly, those call sites are the likely breakage points and need an inventory.
Sequencing. Audit existing token/refresh code first and decide what gets deleted — leaving custom refresh logic in place alongside middleware refresh is a reliable way to produce double-refresh races. Then upgrade in a non-production environment, add regression tests specifically covering refresh-under-concurrency and refresh-during-payment-submission, and only then roll out. Keep the previous pinned version as a documented rollback target; a major version bump with a thin changelog deserves a one-line revert path.
Maintenance. Net positive if it works as advertised: refresh logic becomes the upstream library's problem rather than the team's. The trade-off is a tighter coupling to the bunq-api release cadence — upstream behavior changes now arrive as this package's major versions, and the one-line release note here suggests changelog discipline is thin. Budget for reading upstream diffs, not just this package's notes.
Support. Expect new failure signatures: refresh failures, lock contention, and expired-refresh-token errors that previously appeared as generic auth failures. On-call runbooks need updating so these are diagnosable without reading middleware source. If payment retries are possible, support also needs a reconciliation procedure for duplicate submissions.
Scaling. Refresh is a serialization point. Under load, every worker that hits an expired token competes for the same refresh. Latency impact per request is small in steady state but spiky at expiry boundaries. The scaling answer is a distributed lock plus a token cache with a safety margin before expiry, verified under realistic worker counts.
Failure modes. Ranked by severity: (1) duplicate payment submission via retry after refresh — financial and compliance exposure; (2) thundering-herd refresh invalidating sibling tokens, causing cascading auth failures across the fleet; (3) cache/store outage taking down all API calls because refresh can no longer read state; (4) silent config-key changes from the major bump producing a misconfigured client that fails only at first refresh; (5) re-authorization required with no operator-facing path to trigger it.
Ramp-up. Low for a developer making a straightforward API call through the wrapper. Moderate for anyone who needs to reason about the session lifecycle, concurrency, or the payment-retry question — that knowledge currently lives in upstream source and is not documented in this release. One engineer should own session-lifecycle understanding before rollout, and that understanding should be written down rather than rediscovered during an incident.
How can I help you explore Laravel packages today?