Laravel Arkitect Laravel Package

Technical Evaluation

Architecture fit. mortexa/laravel-arkitect is a dev-time test utility, not a runtime dependency. It slots into the test layer of a Laravel application and lets engineers express architectural invariants (e.g., "controllers must not depend on Eloquent models," "all App\Services\* classes must implement an interface," "no dd()/dump() in app/") as assertions that fail CI. From a TPM perspective this is a governance tool: the blast radius is limited to the test suite and CI pipeline, which makes it low-risk to trial and cheap to remove. It is not a library that will leak into production code paths or force application code changes.

Release v0.8.1 — what changed and why it matters. The 0.8.1 release is a dependency-compatibility widening only: the constraint on phparkitect/phparkitect moves to ^0.3.19 | ^0.4.0 | ^0.5.0. No new features, no deprecations, no breaking API changes to the Laravel-facing surface. Two things are worth recording from it. First, it is a positive maintenance signal — the maintainer is actively tracking upstream, which was an open question in the prior assessment. Second, it makes explicit what the assessment previously only implied: this package is a thin Laravel adapter over phparkitect/phparkitect, and the rule engine, rule DSL, and rule-evaluation performance we are actually betting on belong to the upstream project, not this one. That reframes two of our risks: the engine-maturity risk is inherited rather than owned here, and our dependency graph is now two-deep.

Integration feasibility. Straightforward in principle: a composer require --dev install, Laravel package auto-discovery, and a new test suite (PHPUnit or Pest) targeting a dedicated tests/Architecture directory. Feasibility hinges on three things we must validate in a spike: (1) the supported Laravel/PHP matrix — the package must support our current LTS and the next major we plan to adopt; (2) PHPUnit 10/11 and Pest 2/3 compatibility, including ParaTest/parallel test execution; (3) whether rule evaluation is reflection-based and cheap enough to run on every PR. The recent release (2025-05-06) and MIT license are positive signals, but 121 stars and 0 dependents mean we would be an early adopter with essentially no public precedent to lean on. v0.8.1 improves the picture on (1) and (2) by demonstrating the maintainer keeps the transitive graph current, but it does not resolve them — we still need our own matrix check.

Technical risk.

• Competitive overlap. Pest 2+ ships native arch() architecture testing, and PHPArkitect, Deptrac, and PHPStan custom rules cover adjacent ground. The low opportunity score (32.87) reflects a crowded, partly commoditized space. We need a clear feature delta (Laravel-specific presets, richer rule DSL, baselining/suppression) to justify a third-party dependency over native arch(). Note the overlap is now literal: the engine underneath this package is the same engine we would use if we adopted PHPArkitect directly.
• Two-deep dependency with a pre-1.0 upstream. v0.8.1 spans upstream 0.3.19 through 0.5.0, which tells us the upstream rule DSL has churned across minor versions while still pre-1.0. Our exposure is therefore not just "will this package be abandoned" but "will upstream 0.6/1.0 change rule semantics faster than the wrapper tracks it," and which upstream version we actually resolve to.
• Wrapper vs. direct use. Because the package is an adapter, "adopt the wrapper" and "adopt PHPArkitect directly with a small Laravel bootstrap" are close substitutes. The wrapper's value is convenience (auto-discovery, Laravel-idiomatic rule ergonomics, test-runner glue); its cost is a second maintainer and a second version constraint. The 0.8.1 constraint widening materially reduces the "wrapper lags upstream" failure mode, but does not eliminate it.
• Bus factor. Single-maintainer package with a small user base, now sitting on a second small-maintainer project. Mitigation is unchanged and still cheap: fork/vendor or fall back to upstream directly. Rules are declarative, so the exit cost is bounded.
• Rule engine maturity. Unknown edge-case behavior on large codebases (monorepos, heavy use of traits, facades, dynamic class resolution), and no public battle-testing to point to. v0.8.1 gives us no new evidence here — the constraint widening is version plumbing, not performance or correctness work.
• Version coupling. A dev dependency still creates constraint conflicts with PHPUnit/Pest when we upgrade the test stack; we now also carry a phparkitect constraint axis.

Key questions to resolve before adoption.

1. What does this package do that Pest's native arch() does not, and is that delta durable across Pest releases? (Unchanged — still the gating question.)
2. What Laravel/PHP/PHPUnit/Pest versions does 0.8.1 actually support, and what is the maintainer's stated support policy?
3. Which phparkitect version do we resolve to today, and does the wrapper's rule API surface differ across the 0.3/0.4/0.5 branches it now permits?
4. Does it support baselining or suppression so we can adopt incrementally without a flag-day cleanup?
5. How does it behave under parallel test execution and on a large monorepo (runtime, memory)?
6. Is the rule API — wrapper and upstream — stable enough to commit architectural rules to a shared internal standard, or will rules need rewriting each minor version?
7. Given the adapter architecture, what is the cost of using phparkitect directly, and does the wrapper's convenience justify a second dependency in our supply chain?

Integration Approach

Stack fit. Appropriate for a Laravel 10/11/12 codebase on PHP 8.1+ running PHPUnit or Pest in CI (GitHub Actions, GitLab CI, Bitbucket Pipelines). It is a developer experience and architecture governance capability, best owned by a platform engineering / DevEx function rather than a single product team. It complements — does not replace — static analysis (PHPStan/Larastan) and code review; it enforces structural rules that linters cannot express.

Migration path (phased, reversible).

1. Spike (1 sprint, timeboxed). Install on a scratch branch, port our top 5 architectural invariants, benchmark runtime on the largest service, and compare capability-for-capability against three options: Pest arch(), phparkitect used directly, and a hand-rolled static-analysis rule. Produce a one-page recommendation: adopt / adopt-upstream-directly / adopt-with-fork / decline. The 0.8.1 release adds the "upstream directly" option to the comparison at near-zero extra cost, since it is the same engine.
2. Pilot (one team, one service). Introduce an arch test suite running in report-only mode (non-blocking) for two weeks to surface noise and false positives.
3. Enforce. Flip the suite to blocking on PRs, document the rule catalogue, and add an ADR explaining why each rule exists.
4. Standardize. Roll out to additional services via a shared internal package or a documented template so rules are consistent across teams.

Compatibility considerations. Pin the package version explicitly and pin phparkitect explicitly rather than relying on the widened range — a ^0.3.19 | ^0.4.0 | ^0.5.0 constraint is permissive enough that a transitive resolution could shift rule behavior under us. Add both to the dependency-upgrade checklist alongside Laravel/PHPUnit/Pest majors. Confirm coexistence with Pest arch() if teams have already adopted native rules — dual systems create confusing duplicate failures, so pick one as the source of truth per repository. Ensure the arch suite is excluded from coverage thresholds and from production composer install --no-dev builds.

Sequencing. The critical-path decision is the Pest arch() comparison in the spike; if the delta is marginal, the correct TPM call is to decline and standardize on native Pest architecture tests, avoiding a third-party dependency entirely. If the delta is material (e.g., Laravel-aware presets, baselining, or a rule DSL that maps cleanly to our architectural standards), proceed to pilot — and at that point also decide wrapper vs. upstream-direct. The 0.8.1 release does not change this decision tree; it only makes the upstream-direct branch cheaper to evaluate. Do not run the pilot and the framework comparison in parallel — it doubles the evaluation cost for a low-stakes decision.

Operational Impact

Maintenance. Effectively zero runtime maintenance; the cost is rule maintenance. Architectural rules are policy, and policies drift — someone must own the rule catalogue, review additions, and retire rules that no longer reflect reality. The package itself needs version bumps roughly on the Laravel release cadence, and we now must also track phparkitect releases and the wrapper's support for them; the 0.8.1 release is an example of that chore being done upstream for us, which is the good case. Budget ~0.1 FTE for a platform engineer to own this across the org.

Support. No commercial support and a single-maintainer project sitting on a second single-maintainer project; internal ownership is mandatory. Establish a documented fallback: use phparkitect directly, adopt Pest arch(), or fork the wrapper under our org. Because rules are declarative and the engine boundary is now clearly identified, migration cost is measured in days, not weeks — this remains the key mitigation, and 0.8.1 strengthens it by confirming the boundary.

Scaling. Reflection-based rule evaluation is fast per class but grows linearly with codebase size. On large monorepos, measure suite runtime and consider running architecture tests as a separate, sharded CI job or only on changed modules. Parallel-test compatibility must be validated before org-wide rollout.

Failure modes.

• False positives blocking unrelated PRs → mitigate with report-only pilot, baselining, and a documented exception process.
• Rule drift where the suite encodes an outdated architecture → mitigate with an ADR per rule and a quarterly review.
• Package abandonment → mitigate with the fork/upstream-direct/migrate contingency above; now a two-vendor exposure rather than one.
• Upstream churn — phparkitect is pre-1.0 and its rule DSL has already moved across 0.3→0.5 → mitigate by pinning an exact phparkitect version, treating upstream minors as reviewable changes, and avoiding rules that lean on unstable upstream features.
• Dependency conflict during a PHPUnit/Pest upgrade → mitigate by pinning (wrapper and upstream) and including both in the upgrade runbook.
• Duplicate enforcement alongside Pest arch() or a direct PHPArkitect setup → mitigate by designating one source of truth per repo.

Ramp-up. Low for any engineer already comfortable with PHPUnit/Pest — roughly half a day to read the docs and write first rules, one to two days to onboard a team meaningfully. The real ramp-up cost is architectural literacy: teams must agree on what the rules should be before they can encode them. Treat the rule-writing exercise as a forcing function for documenting the target architecture, and expect the first two weeks to be spent on consensus rather than tooling.

Net effect of v0.8.1. Maintenance-positive, decision-neutral. It resolves the "is the maintainer still active and tracking upstream" concern and clarifies the dependency layering, but it does not change the competitive-overlap verdict, the engine-maturity evidence gap, or the gating Pest arch() comparison. Recommendation stands: run the timeboxed spike, add upstream-direct to the comparison, and be prepared to decline.