Laravel Payment Laravel Package

Technical Evaluation

overtrue/laravel-payment is a thin Laravel service-provider/facade wrapper around League Omnipay: config-driven gateway construction, a Payment facade, default-gateway precedence, gateway instance caching, and array-to-setter option expansion. 4.0.0 is a platform-modernization major, not a feature release. The package's public surface is explicitly preserved (gateway names, alias, facade, option expansion, default precedence, caching, unchanged factory), so the risk is concentrated in the dependency floor rather than in API churn.

Architecture fit

• Fits any Laravel app that wants Omnipay gateways resolved from config/payment.php via DI + facade. It is glue, not a payment domain layer — it does not own idempotency, webhooks, reconciliation, retries, or PCI scope.
• The real architectural dependency is Omnipay 3.x and the individual gateway drivers, which are separately installed and separately versioned. The wrapper's value is only as good as the driver matrix behind it.
• Requiring Laravel ^13.30 and PHP ^8.3 makes this a leading-edge package: it is adoptable only by teams already on (or ready to move to) the newest Laravel major. For most portfolios this is the binding constraint, not the payment code.

Integration feasibility

• Straightforward if the platform preconditions are met: PHP 8.3+, Laravel 13.30+, Omnipay ^3.2.1, Omnipay Common ^3.5.1, Guzzle 7 adapter ^1.1.
• The hard blocker is transitive: every gateway driver we actually use must declare compatibility with Omnipay 3.2.1 / Common 3.5.1. A single lagging driver (common for smaller regional/acquirer gateways) can stall the whole upgrade or force us to run two payment stacks.
• Because the factory and config semantics are unchanged, the code-level migration is small; the dependency-graph migration is the work.

Technical risk

• Driver availability (high): the single largest schedule and delivery risk. Unverifiable from these notes; requires a per-gateway compatibility audit before commitment.
• Test evidence (medium-high): 17 tests / 48 assertions using a dummy gateway. That validates wiring, not payments. No sandbox or contract tests against real gateways, so purchase/authorize/capture/refund/void/3DS/webhook semantics are entirely inherited from Omnipay drivers and effectively untested on our side.
• Unsuppressed upstream deprecations on PHP 8.4+ (medium): the oldest allowed transitive dependencies emit warnings by design. In apps that convert deprecations to exceptions, or that run strict CI, this becomes build noise or build failure. The release notes explicitly decline to suppress them — an intentional nudge to upgrade transitive pins.
• Silent misconfiguration (low-medium): array options still expand into setter arguments, and a single array argument must be wrapped in an outer array. This is a documented footgun that fails at runtime, not at boot.
• Nullable gateway names + deferred provider (low-medium): resolution moves out of boot into first use, and empty gateway names are now tolerated rather than rejected. Net effect: dependency and config errors surface at payment time rather than deploy time unless we add our own checks.
• Maintainer concentration (medium): single-maintainer OSS wrapper over a slow-moving upstream. Mitigated by the small, replaceable surface — the wrapper is a few hundred lines and could be forked or inlined.

Key questions

1. Which gateways do we actually transact on, and does each driver support Omnipay ^3.2.1 / Common ^3.5.1 / Guzzle adapter ^1.1 today, with a credible release date if not?
2. Is Laravel ^13.30 within our platform roadmap and timeframe, or does this release sit outside our support window entirely?
3. What is our actual Omnipay usage surface (authorize/capture/refund/void/webhooks/3DS/tokenization) and do we have sandbox contract tests for it, or are we relying on the package's dummy-gateway suite?
4. Do any of our configs rely on gateway names being non-nullable, or on nested array option expansion?
5. What is our exposure if this package is abandoned — is it already isolated behind an internal PaymentGateway interface, or is Payment:: called ad hoc across the codebase?
6. Do we run deprecation-strict CI, and if so, who owns pinning transitive dependencies upward?

Integration Approach

Stack fit

• Target: Laravel 13.30+, PHP 8.3 (or 8.4/8.5 with latest dependency pins), Omnipay 3.2.1+, driver-per-gateway.
• This is a "modern platform only" package. Treat it as an enabler of a broader Laravel 13 upgrade, not a standalone initiative. If we are not moving to Laravel 13, 4.0.0 is a no-op for us — pin 3.x and revisit.

Migration path

• Upgrade is effectively atomic on the PHP/Laravel axis but should be staged on the gateway axis. The chain is: PHP 8.3 → Laravel 13.30 → Omnipay 3.x + drivers → package 4.0.
• Recommended: keep the package's public contract (facade, gateway names, config keys) untouched and change only the dependency graph, so that any regression is attributable to a driver rather than to our code. The preserved-BC guarantee in the release notes is what makes this feasible.
• Where a driver lags, isolate that gateway behind a temporary separate integration rather than downgrading the whole stack.

Compatibility

• Config keys, default precedence, gateway names, and the facade are preserved — existing config/payment.php should carry over unchanged.
• Explicitly audit for: configs with null/empty gateway names (now permitted, previously failing loudly), and any option array that relied on nested expansion (must now be wrapped in an outer array).
• Verify strict-type and static-analysis passes; CI is claimed green under strict validation and lint, but our own rulesets are stricter.

Sequencing

1. Gateway/driver compatibility matrix — the go/no-go gate. Do this before any engineering commitment.
2. Spike branch: PHP 8.3 + Laravel 13.30 + Omnipay 3.2.1 + package 4.0 against a sandbox account for the primary gateway only.
3. Build our own sandbox contract tests (purchase, authorize, capture, partial refund, void, webhook/callback) — do not rely on the package's dummy-gateway coverage.
4. Add a startup/health-check that resolves each configured gateway, converting deferred-provider and nullable-name failures back into deploy-time failures.
5. Migrate gateway-by-gateway; canary the primary gateway on low-value traffic.
6. Retain a documented rollback: pin previous major + previous Laravel until the last gateway is proven.

Operational Impact

Maintenance

• Small dependency surface and a small wrapper codebase — low ongoing maintenance burden provided we own the transitive pins. The 4.0.0 notes make this explicit: the oldest allowed transitive dependencies will emit deprecations on PHP 8.4+, unsuppressed.
• Single-maintainer project. Recommend wrapping the facade behind an internal interface from day one so the package is replaceable without a codebase-wide refactor.

Support

• Community/GitHub only; no vendor SLA. Acceptable for a glue layer, not acceptable as the sole owner of payment-critical behavior.
• Upgrade guides exist (README + PR #18), which is a positive maintenance signal — 4.0.0 indicates the project is actively tracking Laravel releases.

Scaling

• The wrapper itself adds negligible runtime cost; gateway caching (preserved) avoids repeated instantiation. Scaling characteristics are those of Omnipay and the acquirer: connection pooling, retry/backoff, timeouts, and gateway-side rate limits are ours to own.
• Because the provider is deferred, cost moved off application boot — a small win for large apps with many configured gateways.

Failure modes

• Driver drift: a driver requiring Omnipay 2.x forces either a second stack or an abandoned gateway. Detect at CI, not in production.
• Late failure: deferred provider + nullable gateway names mean misconfiguration surfaces at first charge attempt. Mitigate with a boot-time/health-check gateway resolution.
• Silent option misconfiguration: array expansion semantics produce runtime errors or wrong setter calls; the outer-array wrapping rule is easy to miss. Add config schema validation.
• Deprecation noise: unsuppressed upstream warnings can break deprecation-strict CI or flood logs on PHP 8.4+. Mitigate by pinning transitive dependencies upward rather than suppressing.
• Untested payment paths: the 48 assertions cover wiring only; refunds, partial captures, 3DS and webhooks have no coverage here. Our own sandbox tests are the control.

Ramp-up

• Low for the package: engineers need a few hours to learn facade/gateway/config conventions.
• Moderate-to-high for the domain: Omnipay driver behavior, gateway quirks, and payment lifecycle semantics are the real learning curve, and this package does not abstract them away.
• Plan for one engineer to own the gateway compatibility matrix and the sandbox contract suite; that person, not the package, is the operational dependency.