Object Enumerator Laravel Package

Product Decisions This Supports

• Build vs. buy for object-graph inspection: The decision is "consume existing capability," not "add a dependency." This package already ships inside every Laravel project running PHPUnit or Pest (via sebastian/comparator → phpunit/phpunit), so the real product question is whether to use a capability we already pay for — not whether to procure one.
• Quality-gate investment: Unlocks custom test assertions and pre-release checks around retained references, unexpected collaborators, cyclic graphs, DTO/service graph shape, and clone/serialization safety. A PM can frame this as reliability work that catches state and memory bugs before customers do, at effectively zero licensing cost.
• Developer-experience roadmap: Enables small internal productivity investments — a Tests\Support\ObjectGraphAssertions trait or a CI-only artisan inspector — rather than product-facing features. This is a candidate for a sprint-filler ticket, not a roadmap line item.
• Dependency and platform governance: Package majors track PHP support (v7.0.0 drops PHP 8.2, v8.0.0 drops PHP 8.3), so this becomes an input to PHP/PHPUnit upgrade planning. Note the release-note wording is ambiguous as to whether that's a minimum-version floor or a hard ceiling — verify against composer.json before scheduling any runtime upgrade.
• Scope discipline: This is infrastructure, not a differentiator. The PM decision is whether to expose it in test strategy and internal tooling — explicitly not whether to build a customer-facing feature on it.

When to Consider This Package

Adopt (or rather, formally sanction) when:

• A named caller exists — a specific assertion helper, leak-triage check, clone/serialization audit, or internal inspector command. "It might be useful" is not a use case; without a call site, stop here.
• You need identity-level, cycle-safe enumeration of every object reachable from a nested value — including non-public properties — and Arr:: helpers, data_get, json_encode, spl_object_id set comparison, or VarDumper genuinely can't answer the question.
• You want to avoid owning and maintaining bespoke recursive traversal code across complex Laravel service graphs, DTOs, or container-resolved objects.
• You accept the permanent constraint: dev/test-only, zero production call sites.

Look elsewhere when:

• You only need simple array traversal (Laravel Arr / data_get) or human-readable output (dump/dd/VarDumper). This package returns a flat list of objects — it is not a debugger.
• You need deep cloning, serialization, or ORM persistence semantics. Wrong tool entirely.
• PHPUnit's transitive copy already satisfies the need — which it usually does. Adding a direct constraint risks a resolution conflict during the next PHPUnit major bump.
• Your inputs are large: a fully hydrated Eloquent aggregate or a thousand-entry service container will burn time and memory. There is no depth cap, predicate, or result limit.

Promote to an explicit require-dev only when you ship a real call site — at that point declaring it converts an implicit transitive dependency into a protected one. Wrap before first use, not after: one Support\ObjectGraph helper or test trait with intent-named methods (assertGraphHasOnly, assertNoLeakedObjects). The wrapper is the exit ramp.

How to Pitch It (Stakeholders)

For executives: "This is a zero-cost, low-risk capability from the PHPUnit ecosystem — 6,500+ stars, active maintenance, BSD-licensed, and already installed in our codebase as a transitive dependency. It improves engineering quality by letting us catch retained-reference and object-graph bugs earlier in the cycle, without funding custom traversal code or adding a production dependency. It does not touch customer-facing features and carries no framework-upgrade tax. Recommendation: sanction it as a pre-approved, dev-only capability and revisit only when a concrete use case lands. This is an engineering-efficiency decision, not a product investment."

For engineering: "sebastian/object-enumerator gives us safe recursive enumeration of referenced objects — including circular references — through non-public properties. It ships transitively with PHPUnit, so step one is an inventory (composer show), not an install. Use it for custom graph-shape assertions, memory-leak triage, clone/serialization audits, and CI-only artisan diagnostics. Three rules: it stays require-dev with zero production call sites; it goes behind a single wrapper (the class is final and exposes one method, so the wrapper is both our ergonomics and our exit ramp); and we scope-limit inputs before enumerating, because there's no depth cap and large graphs will OOM. Do not confuse it with dump() — it enumerates objects, not values, and lazy-loaded proxies will show up as objects. Verify the major version's PHP floor against our CI matrix at every upgrade; let PHPUnit drive the version and don't pin independently."