Recursion Context Laravel Package

Product Decisions This Supports

• Build vs. buy vs. inherit. The practical answer is "inherit." This library is plumbing beneath sebastian/comparator and therefore PHPUnit; most Laravel teams already receive it transitively as a dev dependency. The product decision is not whether to adopt it, but whether to rely on it directly in our own test tooling — a much smaller commitment.
• Platform upgrade sequencing. This is the most consequential PM-level signal in the package. Major version 8.x requires PHP 8.4+, 7.x supports PHP 8.3, 6.x supports PHP 8.2. Since PHPUnit's dependency chain will pull the major that matches our PHP floor, this package effectively becomes a canary for "which PHP minor is our test stack pinned to." That should feed directly into the roadmap item for PHP/Laravel runtime upgrades and the CI matrix.
• Developer tooling investment. Where it earns its keep is test and debug infrastructure: cycle-safe var_export-style output for failure diffs, custom PHPUnit constraints for deeply nested DTO/object graphs, debug panels that serialize request state, and assertion helpers for bidirectional Eloquent relationships. If we have a recurring "our test diffs hang or explode on circular models" complaint, this is the cheap fix.
• Scope discipline / dependency hygiene. Explicit PM guidance: this belongs in require-dev only. Adding it to production require is a red flag in code review and a signal that someone is doing deep variable traversal in app logic, which belongs in symfony/var-dumper or our own normalizers instead.
• Bus-factor and vendor concentration. Stars (~6.6k) reflect the PHPUnit ecosystem halo, not independent adoption — dependents count is effectively zero at the direct-consumer level. It's a single-maintainer utility with a tiny API surface. Low risk, but it should be classified as "critical-path dev infrastructure we do not control," which argues for keeping our own test helpers thin and swappable rather than tightly coupled to Context.

When to Consider This Package

Adopt (directly, as --dev) when:

• We are writing test-only utilities that must walk nested object graphs and circular references — comparison constraints, snapshot exporters, fixture inspectors.
• Our PHP floor is aligned with the major we'd install (8.4 → v8, 8.3 → v7, 8.2 → v6), and we're willing to bump majors alongside PHP upgrades.
• We want a ~1-class, zero-config API that a mid-level engineer can read in five minutes, rather than maintaining bespoke cycle-detection code.
• The alternative is hand-rolled recursion guards in test helpers — which is exactly the kind of subtle, flaky code we should not own.

Look elsewhere when:

• The need is production runtime serialization, logging of request payloads, or API error output. Use symfony/var-dumper, Laravel's own dd/dump plumbing, or explicit JsonSerializable/resource normalizers. This package is not designed for that and will create a runtime dependency on a test tool.
• We need array cycle detection. It tracks objects via spl_object_id(); arrays and scalars are handled by native recursion. If the data model is array-heavy, this doesn't solve the problem.
• We are on an older PHP minor and can't move. Pinning a legacy major means adopting an unmaintained branch — a poor trade for a package this small; write the ~30-line guard yourself instead.
• We'd be introducing it as a new direct dependency on a stack that already gets it through PHPUnit. In that case, add a test helper and move on; don't over-formalize.
• The requirement is general-purpose debugging UX. That's a different product surface with different expectations.

How to Pitch It (Stakeholders)

To executives: No purchase, no license cost, no vendor negotiation — BSD-3, maintained by the author of PHPUnit, and already present in our dependency graph through the test suite. The only decision in front of us is timing: this library's current major requires PHP 8.4, so it's a concrete forcing function for the PHP upgrade already on the roadmap. Framing: a zero-cost reliability improvement for engineering, with one scheduling dependency attached.

To engineering leadership: Treat it as test infrastructure, not application architecture. It removes a class of flaky, hard-to-debug test failures caused by circular object graphs (common with bidirectional Eloquent relations and mocked DTOs) at the cost of one dev dependency we already have. Constraint to communicate clearly: dev-only, version-locked to our PHP floor, and the Context must be reset between independent operations — misuse produces phantom "recursion detected" results that will burn support time if undocumented.

To the engineering team: Use it behind a thin internal helper (safeExport(), a DeepEquals constraint) so we can swap it out if maintenance lapses. Don't call it from controllers, jobs, or anything that ships. Verify the PHP floor in CI before bumping the major, and pin majors deliberately rather than accepting whatever Composer resolves.