Object Reflector Laravel Package

Product Decisions This Supports

• Build vs. buy for test tooling. This is a "buy" decision with a near-zero price: a small, single-purpose, BSD-3 library that removes the need to maintain hand-rolled ReflectionClass/ReflectionProperty helpers across the test suite. With ~6.3k stars and adoption inside PHPUnit itself, it is the conservative choice over bespoke code.
• Test strategy: behavior-first, with a sanctioned escape hatch. Rather than forcing public getters onto domain objects purely to make them testable (an API design decision driven by tests), teams get a contained, read-only way to assert internal state where behavior is genuinely not observable — cache hydration, queue payload integrity, lazy-load state, third-party objects.
• Unblocking legacy modernization. During migrations and strangler-fig refactors, this lets teams write characterization tests and verify state in code they cannot yet refactor. It is a temporary enabler for migration work, and should be tracked as such.
• Investing in debuggability / support triage. Useful for internal tooling, dump helpers and incident investigation where standard dump()/dd() cannot reach private and inherited properties. This reduces time-to-diagnosis, which is a support-cost lever rather than a roadmap item.
• Roadmap constraint to record explicitly: this is an engineering enablement dependency, not a product feature enabler. It belongs in the tooling/maintenance budget, and its only roadmap coupling is the PHP version upgrade plan — the package's major versions are tightly bound to PHP runtimes, so every PHP upgrade becomes a small, scheduled maintenance task with a version pin to verify.

When to Consider This Package

Consider adoption when:

• The need is exclusively dev/test/local — it is installed as require-dev and never runs in production request paths.
• You have concrete test cases where native ReflectionClass is insufficient or where existing manual reflection code is duplicated across the suite (inherited, private, protected, trait-declared properties).
• You need read-only introspection only.
• Your PHP runtime matches a supported major version, and the team accepts version pinning as part of the PHP upgrade checklist.
• You can wrap it behind one internal helper (e.g. App\Support\PropertyInspector or a test trait) and add a static-analysis rule to block usage outside tests.

Look elsewhere / decline when:

• Only public properties are needed — Laravel/Symfony's native reflection is sufficient and adds no dependency.
• Anyone wants it in production or service-layer code — reflection carries meaningful runtime overhead and this is a dev tool.
• You need to mutate object state — this library is read-only; use ReflectionProperty::setValue() directly.
• The runtime is on a PHP version the current major no longer supports, and pinning an older major creates a stale-dependency burden the team won't own.
• The underlying motivation is over-encapsulation — if the only reason to reflect is that a service exposes no way to verify its output, the better product decision is to fix the seam, not to institutionalize reflection.
• You require a commercial SLA or vendor-backed support; this is single-maintainer, community-supported.

How to Pitch It (Stakeholders)

For executives (one paragraph): We're proposing a small, free, permissively licensed developer tool that helps our engineers test and debug complex code faster. It's used inside PHPUnit — the framework our test suite already depends on — so it's about as validated as a utility library gets. It ships only in development and testing environments: it has no production footprint, no performance impact on customers, no new security surface, and no external dependencies to monitor. The cost is effectively zero; the benefit is less custom test plumbing to maintain and faster diagnosis of tricky defects. The one thing we must budget for is a small version-pin check each time we upgrade PHP.

For engineering: Add as require-dev, pin the major version to our PHP runtime, and immediately wrap it in a single internal helper so no application code imports it directly. Replace ad-hoc ReflectionClass boilerplate in tests incrementally, starting with the messiest legacy suites. Add a PHPStan/CI rule that fails if the namespace appears outside tests/. Policy: assert behavior first; reflect only when behavior isn't observable — and treat every new use as a signal to ask whether the object's public seam should change instead. Track it as a migration aid with an owner, not as a permanent architectural fixture.