Parser Reflection Laravel Package

Product Decisions This Supports

• Build vs. buy for static analysis infrastructure. If you are considering a custom PHP linter, architectural-boundary checker, or dependency-graph tool, this package is the "buy" option for the hardest half of the problem: turning source files into reliable, native-shaped reflection objects. Your team then builds only your domain rules on top. That typically converts a multi-month parser/reflection effort into a few weeks of rule authoring.
• Feature viability for "analyze without executing" capabilities. Any roadmap item that requires knowing a class's methods, properties, signatures, attributes, or constants without bootstrapping the framework or autoloading user code — pre-deploy code audits, PR-time architecture checks, migration/codemod tooling, API surface diffing, doc generation, IDE/editor integrations — is unblocked by this dependency. It answers "can we do this safely?" with yes.
• CI/CD and platform investment. Enables a pre-merge quality gate that inspects code statically instead of running it: cheap, hermetic, no database, no secrets, no fixtures. This is a roadmap argument for shifting some correctness checks left, out of integration tests.
• Upgrade and modernization programs. Because it reflects source rather than loaded classes, it can audit code that does not yet run on your target PHP version — useful for planning framework/PHP upgrades, inventorying deprecated API usage, and scoping codemod work before committing engineering time.
• Public API / SDK surface governance. For libraries and internal platforms, it supports deciding to ship API-compatibility checks (breaking-change detection on public classes, methods, signatures) as a productized capability for internal consumers.
• Use cases to prioritize: static analyzers and custom PHPStan/Rector-style rules, code generators and scaffolder templates, documentation and changelog generation, plugin/extension discovery and validation, dead-code and unused-public-API detection, architectural conformance ("does the Domain layer import Infrastructure?").
• Use cases to explicitly not pursue: anything needing runtime behavior, actual values, side effects, or dynamic/eval-constructed classes. This package reads syntax, not semantics — do not roadmap features that assume it can tell you what code does.

When to Consider This Package

Adopt when:

• Your requirement is structural introspection — names, signatures, visibility, modifiers, attributes, defaults, docblocks, hierarchy — not runtime behavior.
• You must analyze code that is unsafe, expensive, or impossible to load: untrusted/vendored code, code with heavy constructor side effects, code targeting a different PHP version, or a codebase too large to bootstrap per analysis run.
• You want drop-in compatibility with PHP's native \Reflection* API — the classes extend the native ones, so existing reflection-consuming code and third-party libraries can accept these objects with minimal change.
• You already depend on nikic/php-parser (directly or via PHPStan/Rector), so the AST layer is not new surface area for your team.
• Your runtime baseline is PHP 8.5+ and you can track a fast-moving upstream. Version 5.0.0 requires PHP ≥ 8.5 and nikic/php-parser ^5.9, and the project tracks new PHP reflection semantics aggressively.

Look elsewhere or wait when:

• You need real values, execution, or side effects — invoke(), setAccessible(), and similar methods fall back to loading the class, which defeats the purpose. Use native reflection, or run the code in a sandbox.
• You need type inference or dataflow analysis rather than declaration lookup. This gives you declarations; PHPStan/Psalm give you inferred types. Use them instead of rebuilding inference on top of this.
• Your environment is stuck on PHP 8.2–8.4. Version 5 dropped support; you would be pinned to an older major with a different compatibility story — a real maintenance liability.
• You need a supported, large-ecosystem dependency. Signals are thin: ~101 stars, effectively zero dependents, single-maintainer project. Budget for reading source and pinning versions rather than expecting community answers.
• You need exact fidelity with native reflection edge cases. There are documented deliberate divergences (e.g., scope classes resolved statically and never autoloaded; a parameter docblock written after the parameter is dropped) and known follow-ups. If byte-for-byte parity is a hard requirement, validate against a native-reflection oracle in your tests before committing.
• You only need to enumerate classes/methods once and can tolerate bootstrapping. Native reflection is simpler and free.

How to Pitch It (Stakeholders)

For executives: This is a small, free (MIT), open-source building block that lets our tooling inspect PHP code without running it. It is not a product on its own — it is the component that makes capabilities like pre-merge architecture checks, breaking-change detection for our APIs, automated documentation, and upgrade planning cheap to build instead of a research project. The trade-off is dependency risk: it is a low-adoption, single-maintainer project that moves fast and requires PHP 8.5+. Recommendation: adopt it behind our own thin abstraction layer, pin versions, and treat it as an internal implementation detail rather than a platform commitment — so we capture the build-vs-buy savings while keeping the exit cheap.

For engineering: Treat it as "native Reflection* API, backed by an AST instead of the autoloader." Classes extend the native reflectors, so most existing reflection code and third-party consumers work unchanged. It is safe by construction — no include, no constructors, no static initializers — which makes it viable in CI on untrusted or not-yet-runnable code. Two engineering constraints to accept up front: (1) it reflects declarations, not behavior or inferred types — it complements PHPStan/Rector, it does not replace them; any method requiring object manipulation silently falls back to loading the class, so keep those paths out of hot analysis code. (2) It is a fast-moving dependency with documented divergences from native reflection and a small maintainer base. So: wrap it in an internal adapter interface, add a golden-file test suite that compares our wrapper's output against native reflection on our own codebase to catch parity drift on upgrade, pin the version, and review each major bump as a deliberate task rather than letting it float. Budget roughly one to two engineer-weeks to spike one real rule end-to-end (e.g., "Domain must not depend on Infrastructure") to validate the approach before committing roadmap items on top of it.