Mercadopago Fake Laravel Package

Technical Evaluation

Package role. puntodev/mercadopago-fake is a test-double for the puntodev/mercadopago SDK: it substitutes the MercadoPago HTTP client so integration code can be exercised in CI without hitting the live payments API. Blast radius is confined to the test suite and local development — it should never appear in a production dependency graph. That framing should govern how much rigor the upgrade decision deserves relative to other platform work.

Architecture fit. The package sits cleanly in the Laravel testing layer — a service-container binding / facade swap registered from a service provider, with fixture-driven responses. It does not impose architectural constraints on application code beyond "your MercadoPago interactions go through the SDK." Fit is good where teams already inject the SDK rather than calling HTTP directly; teams with hand-rolled Guzzle calls to MercadoPago endpoints get no benefit.

Breaking changes in 2.0.0. Two hard constraints, both version gates rather than API changes:

• PHP 8.5+ required. Projects on PHP 8.4 and below are stranded on 1.0.2.
• puntodev/mercadopago ^8.0 required — the fake is now version-locked to the SDK major, so SDK and fake must upgrade together.

Integration feasibility. Mechanically trivial (composer require --dev), but gated by platform readiness. The realistic blocker is not this package — it is whether the PHP runtime in CI, local dev containers, and any staging-like environments can move to 8.5, and whether the application can absorb mercadopago ^8.0 at the same time. Because the fake tracks the SDK's contract, upgrading one without the other is not a supported state.

Technical risk.

• Version-gate lock-in: pinning to a brand-new PHP minor means a single CI image change becomes a prerequisite for all MercadoPago test coverage upgrades. If PHP 8.5 adoption is deferred (common — waiting for the first patch releases and for Laravel/other dev-tool support), the team is frozen on 1.0.2.
• Dual-branch drift: 1.x must keep serving PHP 8.3/8.4 users. If 1.x stops receiving parity updates, the fake gradually diverges from the real API, producing green tests over broken production behavior — the worst failure mode for a test double.
• Coupled major versions: mercadopago ^8.0 almost certainly changed request/response shapes or client construction. Fake responses that were accurate for 7.x may be silently wrong for 8.x if fixtures were not regenerated.
• Bus factor: small maintainer base, community-maintained, no vendor SLA. Acceptable for a dev-only dependency; not something to build a compliance story around.
• Transitive constraints: ^8.0 may conflict with other dev tooling pinned to older SDK versions in a monorepo.

Key questions.

1. Is 1.x still supported with bug and API-parity fixes, and for how long? Is there a stated support window?
2. Does 2.0.0 ship regenerated fixtures reflecting mercadopago 8.0's actual request/response contracts, or did only the version constraint change?
3. What is the PHP 8.5 adoption status across our CI images, local dev containers, and any shared libraries that must compile against it?
4. Does mercadopago ^8.0 itself require PHP 8.5, or is that constraint specific to the fake? (Determines whether this is one decision or two.)
5. Is there a published compatibility matrix (PHP × SDK × fake) we can pin against?

Integration Approach

Stack fit. Dev-only Composer dependency, installed with --dev, excluded from production autoload. In Laravel it registers a provider that binds a fake client into the container; in PHPUnit/Pest it is typically activated per-test or per-suite. No runtime footprint in deployed artifacts, no queue, cache, or storage implications.

Compatibility matrix to pin.

Record this matrix in the repo README so the constraint is discoverable rather than rediscovered during a failed composer update.

Migration path. Treat as a three-step platform change, not a package bump:

1. Get PHP 8.5 into the CI image and dev container (and confirm Laravel, PHPUnit/Pest, static analysis, and any extensions are 8.5-ready). This is the long pole.
2. Upgrade puntodev/mercadopago to ^8.0 and fix real integration-code breakage — this is application work with actual production relevance and deserves its own PR and review.
3. Swap the fake to ^2.0 and re-run the MercadoPago test suite, diffing any fixture/assertion changes.

Sequencing and safety. Do steps 1–3 on a branch, not incrementally on main. Keep 1.0.2 available as a rollback by pinning explicitly ("puntodev/mercadopago-fake": "1.0.2") rather than allowing a floating constraint. Do not allow * or unbounded constraints on either the SDK or the fake — they are now a matched pair. If the team cannot reach PHP 8.5 within the current planning horizon, the correct decision is to stay on 1.0.2 deliberately and note the support-window risk, not to force the runtime upgrade for a test dependency.

Where to start. Do a spike in a throwaway branch: PHP 8.5 image + SDK ^8.0 + fake ^2.0, run the MercadoPago test suite, and count how many tests fail because fixtures changed versus because application code changed. That number sizes the whole effort.

Operational Impact

Maintenance. Low ongoing effort — the package is a dev dependency with no deploy-time surface. The recurring cost is dependency hygiene: the project uses a weekly grouped Dependabot PR cadence with majors excluded, so the 2.0.0 bump will not arrive automatically. Someone must own the deliberate major upgrade, and that owner needs to be identified now or the pin silently ages.

Support. Community open source, single visible maintainer, no SLA, no vendor escalation path. Acceptable given the blast radius is limited to test reliability. Mitigation: keep the pin explicit and keep a known-good version recorded so a broken upstream release cannot disrupt CI mid-sprint.

Scaling. No production scaling dimension. The relevant scale question is CI matrix size: if the team runs parallel test jobs across multiple PHP versions, the fake must be version-constrained per matrix cell (1.0.2 for ≤8.4 legs, 2.0.0 for 8.5 legs) or the matrix legs must be collapsed to a single PHP version. Collapsing is simpler and is the recommended target state.

Failure modes to monitor.

• Silent divergence (highest severity): fake returns a shape the real API no longer produces; tests pass, production integration breaks. Counter with a small, scheduled contract check — a handful of opt-in tests against the real MercadoPago sandbox — so the fake is periodically validated against reality.
• Stranded branch: 1.x stops receiving updates and the team cannot move to PHP 8.5. Counter by tracking the upstream support statement as a standing risk item with a review date.
• Fixture rot after the SDK major: 8.0 response shapes differ and assertions were written against 7.x. Counter by treating fixture diffs as reviewable changes, not mechanical approvals.
• CI image surprise: PHP 8.5 lands but an extension or dev tool lags, blocking the whole chain. Counter by validating the toolchain before committing to the upgrade.

Ramp-up. Low for engineers — the API surface is small and the usage pattern (bind a fake, assert on SDK calls) is familiar Laravel testing idiom. The real ramp-up cost is organizational: someone must understand the three-way version coupling (PHP × SDK × fake) well enough to make the pin decision and to recognize that a failing MercadoPago test after an SDK bump might mean the fake is stale, not that the code is wrong. Budget a short write-up in the repo capturing the compatibility matrix, the upgrade sequence, and the rollback pin; that document is what prevents the next engineer from attempting a partial upgrade.