Reflection Laravel Package

Product Decisions This Supports

• Build vs. buy is already settled: this is "adopt the platform," not "add a dependency." illuminate/reflection is a first-party subtree split of laravel/framework (MIT, ~35k stars on the monorepo, released on the framework cadence). The real decision is how much of our product surface we let touch it — not whether to procure it.
• Feature enablement: container-aware discovery and dispatch. Use it where a feature needs to answer "can this class be instantiated, and what does it need?" — dynamic job/handler registration, command and policy discovery, middleware pipelines, plugin-style extension points, and auto-generated API docs from controller method signatures. That is a recurring, high-cost-to-hand-roll capability.
• Roadmap signal: prefer framework primitives over bespoke reflection. Any roadmap item that touches DI diagnostics, attribute-driven configuration (#[Inject], custom attributes), or "resolve this class the way the container would" should be scoped against Reflector first; only build custom reflection when we've documented a concrete gap.
• De-risking decision: wrap, don't sprawl. Keep direct Reflector calls behind a thin internal adapter (e.g., App\Support\ClassInspector). That preserves the productivity win while containing upgrade churn across Laravel majors, where internal APIs are explicitly not covered by semver.
• Ignore the prior "36 stars / high-risk third-party" read. That assessment was measuring the split package's own Packagist page, not its provenance. Dependents: 0 is a metadata artifact of subtree splits — every laravel/framework install transitively contains this code. We should correct the record internally so the package isn't re-litigated.

When to Consider This Package

Adopt (use directly, behind an adapter) when:

• You are on Laravel and need container-semantics-aware instantiation — constructor injection, contextual bindings, default-value inference — rather than raw ReflectionClass plumbing.
• You are building framework-adjacent tooling: discovery/registry systems, documentation generators reading method signatures, or extension points that must respect @inject / #[Inject].
• You want one consistent answer to "is this resolvable?" across modules, instead of three teams writing three reflection helpers.
• You need signature introspection with defaults (getParameters(withDefaults: true)) for CLI prompts, generated request objects, or config defaults.

Look elsewhere when:

• The need is deep structural inspection — docblocks, PHP attributes, property types, generics-like annotations. Drop to native ReflectionClass / ReflectionMethod; Reflector is a high-level wrapper and will feel lossy.
• The work is plain DI resolution at a single call site. Use Container::make() / app(); there is no product value in routing through reflection.
• You are not on Laravel (or on a version pin that predates the API you need). The value proposition is Laravel conventions; without them, use symfony/property-access or core Reflection*.
• Your use case requires a stable, publicly documented API contract with LTS guarantees. This is an internal utility class, effectively final; treat it as unversioned and isolate it.
• Someone proposes hot-path reflection (per-request loops over many classes). Cache results — reflection is not free and this package adds overhead on top.

How to Pitch It (Stakeholders)

To executives: "This isn't a new vendor — it's part of the Laravel framework we already run in production, under MIT, maintained by the same team, shipped on the same release train. It gives our engineers the standard Laravel way to inspect and instantiate classes, which is the machinery behind auto-discovery, plugin registration, and generated API documentation. Cost is zero, procurement is zero, and the risk is a coupling risk rather than a supply-chain risk — which we manage by keeping it behind one internal wrapper. Net: we ship discovery and auto-configuration features faster, and we don't accumulate three homegrown reflection utilities to maintain."

To engineering: "Use Illuminate\Support\Reflector as the default for anything that needs container semantics — canBeInstantiated(), getConstructor(), getParameters(withDefaults: true) — and keep native ReflectionClass for deep inspection and attributes. Two hard rules: (1) no direct Reflector calls in domain code, go through App\Support\ClassInspector so a Laravel major can't break us in fifty places; (2) cache reflection results, never re-reflect in a loop. Also note make()/resolve() don't touch the container unless you pass it — that's the most common bug we'll hit."

To product/design partners: "This unlocks capabilities rather than features: the app can discover and wire up new handlers, commands, and integrations without a developer editing a registry file each time. Practically, that's faster iteration on extensibility and fewer 'you forgot to register it' defects."