Archetype Laravel Package

Product Decisions This Supports

The core decision this informs: whether to build developer-facing code manipulation (generation, codemods, refactoring) in-house or buy the AST plumbing and spend the team's time on the product layer instead.

• Scaffolding and code generation features. If the roadmap includes "generate a model/action/DTO/controller from a template," Archetype's Maker + fluent file API handles the parse → construct → pretty-print loop. This is the same layer that powers Laravel Blueprint, which is the strongest external validation available for this package.
• Automated upgrade and migration codemods. The package's sweet spot is scripted, repeatable edits across a PHP codebase — Laravel major-version bumps, namespace renames, adding/removing class constants, property and method insertion. If a roadmap item is "reduce upgrade pain for our users" or "ship an upgrade assistant," this is a credible build-on primitive.
• Internal platform and DevEx tooling. Custom Artisan commands that modify existing source rather than just create new files — wiring service providers, injecting config, enforcing conventions across a large repo. It is an engineering-enablement dependency, not a customer-facing one, so the blast radius of a bad outcome is contained to build-time.
• Build vs. buy call on the parser layer. The alternative is writing against nikic/php-parser directly. That's the honest comparison: Archetype is a convenience layer (fluent query builder, node insertion, format-preserving printing) over php-parser. The buy decision is roughly "a few weeks of engineering to get to parity" versus the maintenance and upgrade risk of a 271-star, single-maintainer package.
• Where it should not drive roadmap. The 1.0 release explicitly cut Schema, Project, and Generators as incomplete or broken. Any plan that assumes a schema-driven project generator exists should be rejected up front — that capability is gone by design, not pending.

When to Consider This Package

Good fit when:

• You are on PHP 8.1–8.4 and Laravel 10–13, and can consume nikic/php-parser ^5. The 2.0.1 CI matrix verifies twelve PHP × Laravel combinations, plus macOS and PHPStan — that is real evidence, not assumption, and it is the single best maturity signal here.
• You need to edit existing files in place while preserving surrounding formatting, not just emit fresh files from templates. Format-preserving printing is the differentiated capability.
• Your tooling is internal or developer-facing, where generated output can go through code review as a normal PR.
• You want a commercial-friendly license with no procurement friction (MIT, and LICENSE.md now exists — it was missing until 2.0.1).
• The team is small enough that a thin abstraction over php-parser is cheaper than owning the AST traversal and node-identity logic.

Look elsewhere or defer when:

• You need documentation as a first-class asset. The project's own 1.0 release notes say docs "are still not near as good as they should be," and known pretty-printing bugs persisted into 1.0. Budget for a spike to learn the API from source and tests, not docs.
• You need a support contract, SLA, or a multi-maintainer guarantee. 271 stars and zero listed dependents means adoption is largely invisible; the maintainer-risk conversation is real even though statamic/cms is named as the largest consumer and was validated byte-identically against 2.0.0.
• You are pinned to a package that needs php-parser 4 (Pest 3+ being the common case). Archetype 1.x will not resolve alongside it. That is an upgrade, not a blocker — but it is a scheduled task, not a one-liner.
• Your target is a long-horizon platform. The deliberate PHP ^8.1 upper bound exists because PHP 9 removes dynamic properties and the AST node-identity mechanism depends on them. Composer refusing to install is the intended behavior, but it does mean a PHP 9 migration will require an Archetype-compatible replacement, not just a version bump.
• You need to generate non-PHP artifacts, or you need runtime reflection/introspection rather than source rewriting. Different problem, different tool.

Risk mitigations worth committing to before adoption: wrap it behind a narrow internal adapter interface so a future swap to raw php-parser is contained; pin ^2.0; and treat the 1.x → 2.x break as the one upgrade to plan for now rather than later.

How to Pitch It (Stakeholders)

To executives (30 seconds): This is a free, MIT-licensed library that lets our code write and modify other code. It is what powers Laravel Blueprint, and Statamic — a large commercial Laravel package — is its biggest consumer and was explicitly regression-tested against this release. It saves us the several weeks of engineering it would take to build PHP source editing ourselves. It ships at build time, not in production, so the downside if it disappoints is a contained tooling delay, not a customer-facing incident. Cost: zero license, plus an estimated one-to-two-week spike to prove it on a real use case.

To engineering leadership: Mature enough to bet a tooling roadmap on, with eyes open. The 2.0.1 release is exactly the kind of release you want to see from a small dependency: no API changes, a declared php requirement where none existed, a missing license file added, seven PHP 8.4 deprecation fixes, a real bug fix (->throw() had silently matched nothing since 2.0.0; getReflection() was catching Exception where it needed Throwable), and CI rebuilt against a pinned Laravel skeleton because Laravel 11 deleted the files the old suite depended on. That is a maintainer cleaning house rather than adding surface area. It is also a single-maintainer project with modest public adoption signals, so the recommendation is adopt behind an adapter, not adopt and spread.

To the engineering team: You get a fluent query-and-transform API over nikic/php-parser, format-preserving output, and a working Maker pattern for generation. You inherit two real costs: thin documentation you will learn from tests and source, and a dependency chain on php-parser 5 that you should pin deliberately. Start with one vertical slice — a single codemod or generator — and measure whether the abstraction earns its keep versus going direct to php-parser.

The ask: a time-boxed spike on one concrete use case, with a go/no-go gate at the end. Success looks like working tooling in days rather than weeks; failure looks like fighting the docs, in which case the fallback to raw php-parser is a small, well-understood rewrite because the domain is the same.