Paypal Fake Laravel Package

Technical Evaluation

puntodev/paypal-fake is a test-double companion to puntodev/paypal, providing an in-process fake of the PayPal API so the Laravel test suite can exercise payment flows without hitting sandbox endpoints. It is a require-dev dependency: it never ships to production, so the blast radius of this release is confined to developer environments, CI, and test correctness — not runtime revenue paths. That framing should drive the whole decision.

2.0.0 content analysis. The changelog contains no features, fixes, or behavioral changes. Every entry is either a Dependabot/CI chore or one of two constraint bumps:

• php: ^8.5 (was implicitly 8.4-compatible)
• puntodev/paypal: ^7.0 (was ^6.x per the 1.0.2 line)

This is a pure compatibility gate, not a capability release. The package's major number is being used to track the upstream SDK's major number, which is a healthy convention but means "upgrade the fake" is never an isolated decision — it is always a sub-task of "upgrade the PayPal SDK."

Architecture fit. Good, and idiomatic for Laravel. A fake bound into the container via a service provider is the standard pattern (cf. Http::fake, Bus::fake), keeps tests hermetic and fast, and removes network flakiness and sandbox credential management from CI. The tradeoff is the classic test-double hazard: assertions validate our model of PayPal, not PayPal. Fidelity risk is therefore the primary architectural concern, and a major-version bump on the upstream SDK is exactly the moment fidelity is most likely to silently degrade.

Integration feasibility. Mechanically trivial — a one-line composer.json edit. Practically, it is gated on two independent prerequisites that must both be satisfied before the bump can merge:

1. PHP 8.5 available in every environment that runs tests (CI runner image, Docker/devcontainer base, each engineer's local PHP, and any shared staging box used for test runs).
2. puntodev/paypal already on ^7.0, which implies the application code has absorbed whatever breaking changes v7 carries.

If either is unmet, Composer cannot resolve and the branch is red. There is no partial adoption path.

Technical risk. Rated medium, concentrated in scheduling and fidelity rather than in the package itself:

• Platform currency risk (high likelihood, low impact). PHP 8.5 is very new. Requiring it for a test-only library force-upgrades the runtime for the whole team. If PHP 8.5 images are unavailable on the CI provider or the deploy target still pins 8.4, we are blocked regardless of our appetite.
• Lockstep coupling (certain, low impact). We can never run fake 2.x against SDK 6.x or fake 1.x against SDK 7.x. Mixed-version states will produce confusing test failures rather than clean errors.
• Fidelity drift (medium likelihood, high impact). The v7 SDK likely changed request/response shapes, auth handling, or webhook payload structure. If the fake's fixtures were updated in tandem (probable, given the constraint bump, but unverifiable from these notes), tests may pass against fakes that no longer match the live API. This is the risk that actually reaches customers.
• Maintainer concentration (structural). Single-maintainer project (@marianogoldman), small star/fork footprint, releases driven by Dependabot. Low supply-chain surface, but no SLA and a real bus-factor of one.

Key questions for the maintainer / our own team

1. Does 2.0.0 update the recorded fixtures and endpoint behaviors to match PayPal SDK v7, or is it only a composer.json constraint bump? (Determines whether fidelity risk is real or theoretical.)
2. Is the 1.0.x line still receiving security patches, and for how long? If not, staying on 1.0.2 accrues quiet risk.
3. Which PayPal endpoints and webhook event types does the fake actually cover, and does that set match what we call in production?
4. What in our application breaks under puntodev/paypal v7? We do not yet have that answer, and it is the true cost driver.
5. Do we have — or can we cheaply add — a nightly contract test against the real PayPal sandbox that would catch fake-vs-reality divergence?

Integration Approach

Stack fit. Native Laravel: service provider registration, container binding, config-published fake credentials, compatibility with Pest/PHPUnit and with Http::fake layering. Nothing bespoke to learn. The only unusual property is that its version constraint is a proxy for our runtime version, which couples a test utility to platform upgrade planning — worth calling out explicitly in the ADR so future maintainers do not treat it as a routine dev-dependency bump.

Migration path. Three viable options; recommend Option B.

Pin 1.0.2 explicitly rather than using a floating constraint, so the eventual upgrade is a deliberate commit and not an ambient composer update surprise during an unrelated PR.

Compatibility. Two hard gates (PHP 8.5, SDK ^7.0) plus one soft gate: does the fake's API surface cover the v7 endpoints we consume? Verify the soft gate by diffing our PayPal call sites against the package's supported method list before committing to the epic.

Sequencing (each step independently verifiable, each revertible):

1. Inventory — enumerate every PayPal call site and every test that touches the fake. Confirm the fake covers all of them. (0.5 day)
2. Platform readiness — prove PHP 8.5 is buildable: CI image, devcontainer, composer.json platform config, and any other service pinned to 8.4. (1–2 days, mostly waiting on infra)
3. SDK v7 upgrade on application code — read the v7 changelog, apply changes, keep tests on fake 1.x if possible during this step to isolate failures (may not be possible if constraints conflict; if so, steps 3 and 4 merge).
4. Fake 2.0 bump — update require-dev, run the full suite, triage every failure as our bug vs fake behavior change.
5. Fidelity check — replay a representative set of flows (create order, capture, refund, webhook) against the real sandbox and diff against fake output. (This is the step that protects production; do not skip it.)
6. Rollout — merge, update onboarding docs, notify team of the PHP 8.5 local requirement.

Do not schedule steps 3–4 in the same week as a revenue-critical payment release.

Operational Impact

Maintenance. Near-zero ongoing cost in steady state — a require-dev entry with grouped weekly Dependabot PRs and no runtime surface. The real maintenance burden is the coupling: every future puntodev/paypal major will force a matching fake major plus a PHP floor bump. Budget roughly one upgrade epic per year, half a day to two days each, gated mostly on infrastructure readiness rather than code.

Support. No commercial support, no LTS, no published deprecation policy, single maintainer. Acceptable for a test utility that fails loudly in CI; unacceptable if we ever let it leak into a production require block. Add a CI assertion / code-review rule that puntodev/paypal-fake never appears in require.

Scaling. Effectively unbounded and non-issue. The fake is in-memory and per-process; test runtime scales with test count, not with payment volume. No concurrency, rate-limit, or data-volume concerns. The one scaling-adjacent risk is organizational: if multiple services or repos each pin different fake/SDK versions, engineers will see divergent test behavior for identical code. Standardize the version across the repo estate via a shared internal baseline.

Failure modes (ranked by customer impact):

• Silent false positive — highest severity. Fake accepts a payload PayPal would reject (field renamed, type changed, header required in v7). Tests go green; production payment or refund fails. Mitigation: nightly sandbox contract test on the money paths, plus alerting on 4xx from PayPal in production.
• Blocked pipeline — highest likelihood. PHP 8.5 missing from CI or a teammate's local env after merge; the whole suite stops for everyone. Mitigation: land platform readiness before the constraint bump; publish the local PHP requirement in the PR description and onboarding docs.
• Mixed versions across team. Stale vendor/ directories produce spurious failures that look like real regressions. Mitigation: lockfile discipline, composer install in a clean CI job on every PR.
• Abandonment. Maintainer stops shipping; the fake drifts from the live API and quietly becomes a liability. Mitigation: it is a small, single-purpose package — forking is cheap; keep the fork decision documented and revisit only if releases stall beyond a PayPal API cycle.
• Unrelated breakage during upgrade. Step 3 and step 4 land together and failures are indistinguishable. Mitigation: isolate the SDK bump from the fake bump where Composer permits; otherwise commit them as separate, individually-described commits.

Ramp-up. Low for day-to-day use — an engineer familiar with Laravel testing conventions can adopt the fake in an afternoon; the README plus existing test examples are sufficient. The upgrade carries a modest, transient learning cost: PHP 8.5 features/deprecations and the puntodev/paypal v7 changelog. Assign one engineer as the PayPal-integration owner to absorb that knowledge once rather than distributing it across the team.

Recommendation. Do not take 2.0.0 on its own merits — it delivers no functionality and its sole effect is to raise our platform floor. Pin 1.0.2 now and open a single tracked epic, "PayPal SDK v7 + PHP 8.5 upgrade," that bundles steps 1–6 above. Trigger that epic only when a business driver appears (SDK v7 requirement, PHP 8.4 end-of-life, or a security advisory), and require the sandbox fidelity check in step 5 as its exit criterion.