Laravel Arkitect Laravel Package

Product Decisions This Supports

• Enforcing modular monolith boundaries without a rewrite. If the roadmap includes splitting a Laravel app into modules or eventual services, Arkitect lets you codify "the Billing module may not import from the Reporting module" as an executable rule today, so the seam stays clean until extraction is actually funded.
• Build vs. buy for architecture governance. The alternative is hand-rolled PHPStan rules, Deptrac config, or a custom Artisan command. Arkitect is a thin Laravel-aware wrapper over phparkitect/phparkitect, so the honest comparison is "buy" only if the Laravel presets and rule syntax save real engineering days; otherwise treat it as a reference implementation. v0.8.1 widened the core constraint to ^0.3.19 | ^0.4.0 | ^0.5.0, which matters for this decision: the wrapper is tracking upstream rather than pinning you to a stale analysis engine, so adopting it does not quietly freeze your rule capabilities.
• Quality gate decisions in CI. Because rules run as tests, it becomes a cheap, reversible gate: adopt a rule, measure violation count, ratchet down over sprints, delete the rule if it proves noise. That is a good vehicle for incremental tech-debt paydown tied to a roadmap milestone. Upgrading the underlying engine is now a Composer constraint change rather than a fork — a low-friction escape hatch if a rule type you need lands upstream.
• Architecture Decision Records that actually bind. ADRs decay into wiki pages. Pairing an ADR with an Arkitect rule makes the decision enforceable and reviewable in PRs — a concrete deliverable for platform/architecture workstreams.
• Onboarding and team-scaling decisions. Rules encode "how we write Laravel here," which is directly useful when deciding to add a second squad to a codebase, or when evaluating an acquisition/integration of an inherited Laravel app (rules give you a fast, quantified read on structural health).
• Not a product differentiator. Low stars, zero dependents, single maintainer — infrastructure hygiene, not a feature. It should never appear on a roadmap slide; it appears in engineering-enablement budgets and definition-of-done.

When to Consider This Package

Consider it when:

• The app is a modular monolith or heading that way, and namespace/folder boundaries exist but are only socially enforced.
• You have ≥5 engineers or multiple squads committing to the same app/ tree, where drift is a function of headcount rather than discipline.
• You have a specific, named architectural rule you can state in one sentence (e.g., "controllers must not touch Eloquent directly," "nothing in app/Domain may reference Illuminate\Http").
• You are doing incremental legacy modernization and need a baseline-plus-ratchet mechanism instead of a big-bang refactor.
• Your CI already runs PHPUnit/Pest and you want architecture checks in the same run, with the same failure UX, rather than introducing a parallel toolchain.
• You want the option to move with upstream phparkitect — v0.8.1's support for 0.3.19 through 0.5.0 means new upstream rule capabilities are reachable without waiting on the wrapper.

Look elsewhere (or skip) when:

• Small team, single-digit services, high trust. Social convention and code review are cheaper than maintaining rule config; the ROI is negative.
• You already run Deptrac or PHPArkitect directly. Arkitect is largely a Laravel-flavored convenience layer; running both is duplication. The widened core constraint in v0.8.1 narrows — but does not eliminate — the gap with a direct phparkitect install: if you are already on core 0.4/0.5 with your own config, the wrapper's remaining value is Laravel presets and test-suite integration, nothing more.
• You need runtime or deployment-time enforcement. This is static, test-time analysis. Container bindings, DI graph correctness, and cross-service contracts are out of scope — that is PHPStan/Larastan or contract testing.
• Supply-chain conservatism is a hard requirement. One maintainer, no dependents, low stars. v0.8.1 is a healthy maintenance signal (the wrapper is keeping pace with upstream), but it is a compatibility bump, not a governance change: still no release cadence commitment, no LTS, no second maintainer. Treat as a dev-only dependency you can fork; do not let critical CI depend on it without pinning and a named internal owner.
• Your architecture is genuinely undecided. Codifying rules before the boundary is stable bakes in churn. Wait for the ADR, then encode it.

How to Pitch It (Stakeholders)

To executives (one paragraph): Architectural drift is the slow, unglamorous tax that makes Laravel features take three sprints instead of one. This package lets us write our architecture rules down as automated tests, so violations fail the build in minutes rather than surfacing as a six-week refactor a year later. It is MIT-licensed, dev-only, ships in days not quarters, and is trivially removable — the cost of trying is a few engineer-days against a materially reduced risk of an expensive "we need to restructure the codebase" conversation. The latest release is a maintenance update that keeps it current with the underlying analysis engine, which is exactly the signal we want before adopting: the tool is being maintained, not abandoned. The trade-off to acknowledge is maturity — small community, single maintainer — so we adopt it as a pinned internal tool with an owner, not a load-bearing platform bet.

To engineering leadership: It runs inside the existing test suite — no new CI system, no runtime dependency, no production footprint. Value is concentrated in two places: enforcing module boundaries so a monolith can stay modular, and giving refactors a measurable ratchet (violation counts go down per sprint, visible in the PR). v0.8.1 broadens compatibility to phparkitect 0.3.19–0.5.0, meaning the rule engine can advance via a Composer constraint rather than a fork or an upstream PR to the wrapper — worth noting when we scope the effort. It complements, not replaces, Larastan and Deptrac; we should confirm overlap before adopting both.

To the engineering team: You get to express "controllers never talk to models directly" or "everything in app/Support is final" as a failing test with a readable message, instead of a comment in a PR that gets ignored at 5pm on a Friday. Rules are code, so they get reviewed, versioned, and deleted when they stop earning their keep. The 0.8.1 bump means you are not locked to an old phparkitect; pin the wrapper, keep the core current, and you inherit new rule types as they land.

Recommended first move: one rule, one sprint. Pick the single boundary most likely to be violated, add it as a non-blocking check, measure the violation count, and decide on blocking status at the next planning cycle. If the count is zero and stays zero, you learned something cheap; if it climbs weekly, you have a quantified case for a platform investment.