Archetype Laravel Package

Technical Evaluation

Architecture fit

ajthinking/archetype is not a scaffolding framework in the artisan make:* sense — it is an AST-level code manipulation library built on nikic/php-parser. Its value to a TPM is as internal engineering enablement: scripted, repeatable edits to PHP source (class/method/property/constant creation, insertion and removal, node query-and-replace), rendered back with format-preserving pretty printing so diffs stay minimal and reviewable.

That places it squarely in the developer toolchain layer, not the request path. The first architectural decision is therefore containment: either it lives in a require-dev/build-time capacity (custom Artisan generators, refactoring utilities, upgrade scripts), or it becomes a runtime dependency because a product feature generates PHP for end users. Those are different risk profiles and should be decided explicitly, not discovered later. The natural alternative — stub files plus string replacement — is simpler and dependency-free but breaks down exactly where Archetype earns its keep: modifying existing code (Laravel 11+ skeletons, service provider registration, config edits) without collateral formatting churn.

Integration feasibility

High. Composer install, Laravel service provider auto-discovery, a publishable config. The 2.x line is verified in CI across twelve PHP × Laravel combinations (PHP 8.1–8.4; Laravel 10, 11, 12, 13) and checked against real Statamic 5/6 installs producing byte-identical output to the prior release. The hard external constraint is the nikic/php-parser ^5.0 pin, which is ubiquitous enough to be a low-collision dependency but is still a major-version constraint we do not control.

Technical risk

• PHP 9 hard ceiling. The AST node-identity mechanism depends on dynamic properties, which PHP 9 removes. The maintainer correctly declared php ^8.1 with a deliberate upper bound, so Composer will refuse the install rather than ship a fatal — good behaviour, but it means Archetype is a blocker on any PHP 9 migration timeline and needs to be tracked as such now.
• Bus factor. 271 stars, effectively a single primary maintainer, with ecosystem pull concentrated through Statamic (its largest consumer). Low activity is acceptable for a mature, narrow library; abandonment is survivable because MIT + small surface area makes an internal fork tractable.
• Documentation debt. The 1.0 release notes state the docs are "still not near as good as they should be," and release notes carry most of the operational knowledge. Expect source reading, not doc reading.
• Residual formatting bugs. Format-preserving printing is the core differentiator and also the least deterministic part; the project has acknowledged incomplete tests around it. Every transform needs a diff assertion, not just a semantic one.
• Version floor matters. 2.0.1 fixed a ->throw() node mapping that had matched nothing since 2.0.0, a getReflection() bug where one unloadable parent class or trait killed an entire query, PHP 8.4 deprecations, and incorrect commands_root/controllers_root config defaults. Anything below 2.0.1 is not a defensible baseline.

Key questions

1. Is Archetype generating code for developers (internal tooling) or for customers (product feature)? The latter pulls a dev-shaped library into production.
2. What is our PHP 9 horizon, and who owns the fork/migration decision when it arrives?
3. Do we have three or more concrete transforms that stubs + str_replace genuinely cannot handle? If not, the dependency is not yet justified.
4. Can we accept a single-maintainer dependency, or does procurement require a named internal owner and a vendored fallback?

Integration Approach

Stack fit

Strong for Laravel 10–13 on PHP 8.1–8.4. The dependency graph is shallow (nikic/php-parser plus Laravel support), and the package is explicitly tested against a pinned Laravel application skeleton rather than assumed compatible. The 1.x line is a dead end: it pins php-parser ^4.11 and cannot coexist with Pest 3 or anything else on v5.

Migration path

• Greenfield: ^2.0.1 only. Treat 2.0.0 as unsafe due to the throw and reflection bugs.
• From 1.x: upgrade to 2.x. No application-code changes are required; the only breaking change is the php-parser major. The trigger to move is usually Composer refusing to resolve Archetype because something else needs php-parser v5 (Pest 3 being the common case). Run composer why nikic/php-parser before and after to confirm exactly one major resolves.
• From 2.0.0: drop-in, provided PHP 8.1+.

Compatibility guardrails

Pin ^2.0.1. Hold PHP at ^8.1 with an explicit upper bound mirrored in our own composer.json so the PHP 9 conflict surfaces in CI, not in an incident. Add a CI check that fails if the resolved php-parser major changes. Publish and version-control the config, correcting commands_root/controllers_root if we touch either.

Sequencing

1. Spike (time-boxed, one engineer). One real transform against our own codebase — not a tutorial example. Success criterion is a clean diff and a passing test suite afterwards.
2. Adapter layer. Wrap Archetype behind our own small service (e.g. PhpSourceEditor) so call sites express intent, not AST node types. This is what makes the PHP 9 fork or a replacement library a contained change rather than a rewrite.
3. First Artisan command. Pick a low-blast-radius generator or an upgrade-style refactor command. Ship with --dry-run backed by ->preview().
4. Golden-file test harness. Fixture input, expected output file, byte-for-byte comparison. This is the only reliable defence against formatting drift and silent no-matches.
5. Broaden. Only after steps 1–4 hold in CI for a release cycle.

Operational Impact

Maintenance

The package is in a stable, maintenance-oriented posture: changelog, semver releases, Dependabot configured, and a maintainer who responded to a two-year CI gap with a correctness-and-evidence release rather than feature churn. That is a good signal. The offsetting reality is that the ecosystem's maintenance is effectively subsidised by Statamic; if Statamic migrates off, our risk increases without any visible change on our side. Mitigation: named internal owner, version pin, and a documented fork procedure.

Support

Thin. Documentation is the weakest dimension, with operational detail living in release notes and source. Budget internal enablement rather than assuming vendor-style support; there is no commercial backing.

Scaling

Parsing is per-file, in-process, and CPU-bound — fine for tens to low hundreds of files. Bulk operations across a large monorepo need chunking, idempotency checks, and ideally parallel workers. The scaling limit is rarely throughput; it is the cost of reviewing large automated diffs and the blast radius of a bug that rewrites many files incorrectly in one run.

Failure modes to design against

• Silent no-match. A query that matches nothing can, in older versions, append the node at end-of-file instead of doing nothing. Every operation must assert a match count before committing.
• Partial or non-idempotent writes. Enforce a clean git working tree, dry-run first, write atomically, and make each command re-runnable.
• Whole-query abort from one bad file. Fixed in 2.0.1 (Throwable rather than Exception), but the lesson generalises: process files independently and report per-file outcomes.
• Formatting drift. Byte-level fixture tests plus a Pint/CS pass after transforms.
• Silent semantic gaps. Node lookup by name or class map can match nothing for newer syntax; tests should cover the syntax we actually write, not just the happy path.

Ramp-up

Moderate. A competent Laravel engineer becomes productive in a few days, but the fluent query builder has real idioms — higher-order where clauses, ->stmts without parentheses, closure-based insertStmt with a BuilderFactory — that are learned from source and release notes. Budget senior time for the first non-trivial transform and treat that engineer as the owner; the risk with this library is not that it fails loudly, but that a junior developer writes a transform that appears to work and quietly mangles a file.