Php File Manipulator Laravel Package

Product Decisions This Supports

• Build vs. buy for codebase introspection. Archetype wraps nikic/php-parser with Laravel-aware queries (LaravelFile::models(), controllers(), serviceProviders(), custom commands_root / controllers_root). Any roadmap item that needs to ask questions of the codebase — architecture linting, dependency audits, generated docs, upgrade/codemod tooling, scaffolding commands, "which controllers bypass this policy" style governance reports — is a build-vs-buy call this package lets you settle cheaply instead of hand-rolling AST traversal.
• Internal tooling roadmap. Teams routinely under-scope the parser plumbing in these features. Adopting Archetype converts a recurring 2–4 week engineering tax per tool into a dependency. This release strengthens that case: the wrapper is now CI-verified rather than merely believed to work.
• Version-floor decisions. v2.0.1 declares php: ^8.1 for the first time and supports Laravel 10–13. That makes it a constraint input to your platform roadmap: adopting it means PHP 8.1+ is non-negotiable, and Laravel 13 is already covered (relevant if statamic/cms 6 is in your stack).
• Upgrade sequencing. The 1.x line pins nikic/php-parser ^4.11, which cannot coexist with php-parser 5 — Pest 3 and newer included. If Composer is refusing to resolve the package, that's the cause, and it's a concrete argument for scheduling the 1.x → 2.x move rather than deferring it.
• Third-party dependency risk register. This release is itself a data point: v2.0.0 shipped a port whose CI matrix hadn't run since before May 2024, and ->throw() had silently matched nothing since. That's a bus-factor / maintenance-health signal worth logging even as you adopt.

When to Consider This Package

Adopt when:

• You need static, source-level answers about a Laravel app's structure and want them in PHP with Laravel idioms, not raw php-parser.
• You're on PHP 8.1–8.4 and Laravel 10–13, and can accept that envelope.
• You're building internal tooling, not a customer-facing product — output is "byte-identical to 2.0.0" per the maintainers, so behaviour is stable, but it is not a supported commercial product.
• Statamic is in play: statamic/cms is the largest consumer and this release was explicitly validated against Statamic 5 (Laravel 12) and Statamic 6 (Laravel 13). If you run Statamic 4 or 3.4, note they pin ^1.0.3 and are unaffected by this release — you gain nothing here.
• You can absorb the 2.x upgrade now (drop-in from 2.0.0; no changes to your own code from 1.x either, only dependency resolution).

Look elsewhere when:

• PHP 9 is on your horizon. The ^8.1 upper bound is deliberate: PHP 9 removes dynamic properties, which the AST node-identity mechanism relies on. Composer will decline the install rather than let you ship a package that fatals — good behaviour, but it means the package has a known, unaddressed expiry. If your platform plan reaches PHP 9, budget for a fork or replacement.
• You need runtime introspection (container bindings, resolved routes) rather than static analysis — this reads source, not a booted app.
• You need vendor SLA, security response commitments, or a support contract.
• Your codebase depends on generated or heavily dynamic constructs that static analysis handles poorly; validate on a representative slice first.
• You're still on PHP 7.4/8.0 or Laravel 6–9 — 1.x supports it but is a dead-end line, and the php-parser pin will increasingly block your other upgrades.

Caveat to carry into any adoption: a class map pointed at a removed php-parser node for the whole of 2.0.0, and ->throw() matched nothing without erroring. Silent wrong answers are the failure mode here. Whatever you build, add a regression test asserting your queries return non-empty on known-good input — don't trust an empty result set.

How to Pitch It (Stakeholders)

To executives: Archetype is a small open-source Laravel package that lets our own tooling read and query our codebase's structure — models, controllers, service providers — without us writing and maintaining a parser. This release is maintenance-only: no API changes, nothing that can break existing usage, and it fixes several defects introduced in 2.0.0 while adding CI coverage across twelve PHP/Laravel combinations, macOS, and PHPStan. It is now verified against Statamic, its largest consumer. Cost is a Composer dependency; the alternative is bespoke tooling we own forever. The one strategic caveat: it will not run on PHP 9 without upstream work, so if we adopt it we should track that.

To engineering: Drop-in upgrade if you're on PHP 8.1+; from 1.x it's worth doing because 1.x pins php-parser 4 and blocks Pest 3 and anything else needing php-parser 5. No changes to our code. Fixes we care about: ->throw() maps correctly again after being silently dead since 2.0.0, and getReflection() now catches Throwable so an un-autoloadable parent class skips one file instead of killing the whole query — that affected models(), controllers(), and serviceProviders(), which is most of what we'd use. Also clears PHP 8.4 deprecations and fixes a config default where commands_root and controllers_root both pointed at the controllers directory. Known limit: PHP 9 removes dynamic properties, which the node-identity mechanism depends on; the Composer constraint blocks that install intentionally. Given the 2.0.0 regression went unnoticed, treat empty query results as suspect until we've got our own assertions in place.