Laravel Daraja Laravel Package

Technical Evaluation

Architecture fit. starnerz/laravel-daraja is a Laravel service-provider + facade wrapper over Safaricom's Daraja (M-Pesa) REST APIs — STK Push, C2B, B2C, transaction status, and related endpoints. It sits at the outbound integration boundary of a Laravel application and speaks JSON over Guzzle. That makes it a good fit for a monolith or modular Laravel app that needs M-Pesa without hand-rolling an HTTP client, signing, and error mapping. It is not an abstraction layer over multiple payment providers — adopting it is a deliberate commitment to Daraja's semantics (shortcodes, passkeys, callbacks, IP allowlists), which should be reflected in how the surrounding payment domain is modelled.

Integration feasibility. v5.2.0 is a permissive, non-breaking release. The requirement moves from ^7.x to ^7.8 || ^8.0, so applications already on Guzzle 8 become installable at all; applications on Guzzle 7 need no action. There are no code, config, or API changes — the only other deltas are a security contact address and a documentation domain move. For a TPM this is close to the ideal shape of a release: it removes a resolver-level blocker without changing runtime behaviour, and it is a one-line constraint bump to adopt.

Technical risk. Low but not zero, and the risk is concentrated in the Guzzle 8 claim:

• "Nothing in the package changes" is an assertion about the package, not about Guzzle. Guzzle 8 is a major version; handler stack composition, middleware, exception types, and stream/promise behaviour are the usual breakage surfaces. If this package only performs simple synchronous JSON calls, exposure is minimal; if it registers middleware, retries, or inspects Guzzle-specific exceptions, a real behaviour difference could exist despite an unchanged codebase.
• CI coverage is narrow by construction. Guzzle 7 is exercised on Laravel 12 and Guzzle 8 on Laravel 13, on PHP 8.3/8.4. That is a reasonable proxy but it means the Guzzle 8 path is validated only in tandem with a newer framework, not against the Laravel versions most adopters run today. Guzzle 7 coverage is likewise pinned to one Laravel major.
• The Guzzle floor moved to 7.8. Applications still on Guzzle 7.4–7.7 (older Laravel 8/9 projects) now fall below the floor. This is a silent narrowing for legacy consumers even though the headline is a widening.
• Payments context amplifies any regression. Failures here are customer-visible and financially material, and the package handles credentials and callbacks — so a "minor" release still deserves staging validation rather than immediate production rollout.
• Single-maintainer concentration. Vendor continuity, security responsiveness, and the durability of the new docs domain/redirects are governance concerns, not code concerns.

Key questions.

1. Does the package call Guzzle directly or go through Laravel's Http facade? Is any middleware, retry, or Guzzle-specific exception handling involved?
2. What is the supported Laravel/PHP version matrix, and is there a stated EOL policy? Is Laravel 10/11 still tested?
3. Is the Guzzle 8 path tested against any currently-GA Laravel major, or only the forthcoming Laravel 13?
4. Are CI tests running against the Daraja sandbox or fully mocked? What is the actual test coverage of response/error paths?
5. Who owns laraveldaraja.com, and what guarantees exist that the redirect from starnerz.github.io/daraja-docs/ persists?
6. Who monitors [email protected], and is there a published disclosure SLA?
7. Do any other dependencies in our tree pin Guzzle ^7, which would make the widened constraint moot (or, conversely, is our Guzzle 8 adoption currently blocked on exactly this package)?

Integration Approach

Stack fit. Target Laravel 10/11/12 on PHP 8.3/8.4 with composer require starnerz/laravel-daraja:^5.2. The widened constraint aligns with where the ecosystem is heading: apps that have already moved to Guzzle 8 (typically because another dependency forced it) can now resolve this package instead of being deadlocked. Apps on Guzzle 7 are untouched; the resolver keeps them on 7.x.

Migration path. Effectively a no-op upgrade:

1. Bump the constraint to ^5.2 and run composer update starnerz/laravel-daraja --with-dependencies.
2. Review the published config diff — expect none, but confirm no new keys were introduced between our pinned version and 5.2.0.
3. No application code changes, no endpoint or credential changes, no callback URL changes.
4. If we are jumping from below 5.1.0, read the intervening changelogs rather than assuming this release is the only delta.

Compatibility checks before merge.

• Verify no transitive dependency still pins guzzlehttp/guzzle:^7.0 if we intend to take Guzzle 8; the package's constraint is necessary but not sufficient.
• Confirm our current Guzzle version is ≥ 7.8 if we remain on 7.x.
• Confirm Laravel's own HTTP client constraint doesn't conflict with Guzzle 8 in our framework version.

Sequencing.

• Merge the constraint bump on its own branch, no functional changes bundled.
• Deploy to staging against Daraja sandbox credentials; exercise one happy path and one failure path per endpoint we actually use (typically STK Push, callback receipt, and a query/status call).
• Canary to production behind an existing feature flag if the payment flow is flaggable; otherwise release during a low-volume window.
• Rollback is trivial: re-pin to the previous 5.1.x and reinstall from the prior lockfile. Keep the old composer.lock until the release has been stable for a full business cycle.

Adoption of Guzzle 8 itself should be a separate decision. This release makes Guzzle 8 possible, not advisable. Take the package bump now; schedule the Guzzle major separately, with its own testing, so the two changes never share a blast radius.

Operational Impact

Maintenance. Ongoing cost is minimal. Pin the version, let Renovate/Dependabot surface future releases, and review each one — this package's release notes are unusually clear about scope, which lowers review effort. Two small housekeeping items: update internal runbooks/wiki links to laraveldaraja.com rather than relying on the redirect, and record [email protected] as the disclosure channel in our vendor registry (replacing any personal address previously noted).

Support. Support model is community/single-vendor (starnerz / EazySoft Africa) with no commercial SLA. The move to a role-based security address is a genuine improvement in governance — it survives maintainer turnover — but it is still one small team. Mitigate by keeping our integration surface thin: our own adapter around the package, config in env, and no direct dependence on package internals, so a swap to a hand-rolled client or an alternative package is a contained effort rather than a rewrite.

Scaling. The package is a thin HTTP client and holds no local state, so it does not constrain scale on its own. Throughput is bounded by Daraja's rate limits, Safaricom-side latency, and our own queueing discipline. Concurrency should be handled by queue workers with bounded retries and backoff; connection reuse matters more than the Guzzle major version. Guzzle 8 does not change our capacity profile.

Failure modes to design for (independent of this release).

• Daraja timeouts and 5xx — need timeouts, retries with jitter, and a dead-letter path, not infinite retry.
• Lost or delayed callbacks — callback endpoints must be idempotent and reconcile against a status query.
• Duplicate STK pushes / double debits — idempotency keys on our side, not the package's.
• Credential and passkey expiry/rotation — alerting, not silent failure.
• Callback source validation (IP allowlisting, shared-secret checks) — an application responsibility the package will not cover.
• Guzzle exception types surfacing into domain code if the package doesn't normalise them — worth verifying during staging, particularly under Guzzle 8.
• Dependency-resolution deadlock — the exact failure this release fixes; keep constraints loose enough to avoid re-creating it.

Ramp-up. Low. A Laravel-fluent engineer can integrate and ship within a day; the learning curve is M-Pesa domain knowledge (shortcodes, passkeys, C2B validation vs. confirmation URLs, sandbox vs. production credentials, go-live approval), not this package. Budget onboarding time for the Daraja certification/go-live process rather than for the library.

TPM recommendation. Adopt v5.2.0 in the next routine dependency cycle. It is a widening, non-breaking change that unblocks Guzzle 8 without obliging anyone to take it. Treat Guzzle 8 migration as a separately scheduled, separately tested item; use the staging validation to confirm whether the package normalises Guzzle exceptions; and open follow-ups on the version-support policy, test strategy (sandbox vs. mocked), and the bus-factor mitigation around a single-maintainer payments dependency.