Structarmed Laravel Package

Technical Evaluation

Architecture fit

• StructArmed is a dev-only static analysis CLI, not a runtime package. It has no service provider, no container bindings, and no request-path footprint. That makes it architecture-neutral: it can be adopted in a Laravel monolith, a modular monolith, or a package-heavy Laravel app without touching composer.json autoload or bootstrap.
• Its mental model — layers plus directional rules — maps cleanly onto the way most Laravel teams already think about boundaries (Http → Actions/Services → Models), and onto the "modular monolith" pattern where each domain namespace becomes a layer.
• It sits alongside, not inside, the existing quality stack. Pint/CS-Fixer handle style, PHPStan/Larastan handles type and correctness, Pest/PHPUnit handles behaviour; StructArmed is the only one of that set whose express purpose is dependency direction and abstraction hygiene. That is a genuine gap in a default Laravel toolchain.
• The YAGNI preset (unused interfaces, traits, abstract-only classes) is directly useful for a codebase that has accumulated speculative abstractions — a common outcome of fast Laravel feature work.

Integration feasibility

• Installation is one composer require --dev, one init --preset, one config file, one CI step. Effort is measured in hours, not sprints.
• The config is native PHP returning a fluent Architecture::define() object, which means layers can be computed, looped, and shared across teams rather than being a bespoke DSL. This is a strong fit for teams that already maintain phpstan.neon and rector.php.
• --fix support (including YAGNI rules) materially lowers the cost of adoption on a legacy codebase — you can converge rather than freeze the rule set at "what currently passes."
• Parallel workers and an analysis-result cache indicate the author has thought about large repositories, which is the usual adoption blocker for architecture linters.

Technical risk

• Pre-1.0 churn. The package is at 0.19.x with a very high release frequency and schema-affecting changes across minors (new marker interfaces in 0.16.0, new preset semantics). Pin exact versions and treat upgrades as changes requiring review.
• Bus factor of one. Every changelog entry sampled is authored by the same contributor. There is no vendor, no paid support, and no evidence of a maintainer bench. This is the single largest risk and should drive the adoption decision more than any technical characteristic.
• Thin adoption signal. 60 stars, zero dependents, low composite score. There is no downstream validation — no large OSS project proving the rule set survives contact with real codebases. You will be an early adopter and will find the rough edges.
• Dynamic-dispatch blind spots are worse in Laravel than in generic PHP. Class names resolved through the container, app(), facades, ::class strings in config arrays, and event/listener discovery are all patterns where a string-based analyser can produce false positives or false negatives. The YAGNI rules are explicitly scoped to "scanned paths only," which means extension points intended for external consumers will be flagged unless skipped.
• Tool overlap and ownership ambiguity. If the team already runs Deptrac, PHPArkitect, or PHPStan architectural rules, adding a third dependency graph analyser creates two sources of truth for the same policy.

Key questions to resolve before committing

1. What is the PHP version floor, and does it match the oldest Laravel version we support?
2. Does the config support a baseline / ignore file, and can a violation budget be ratcheted down over time, or is it pass/fail only?
3. What report formats are emitted — console, JSON, SARIF, JUnit? Can violations be surfaced inline in GitHub PRs?
4. Are results deterministic and platform-stable across Linux CI and macOS/Windows developer machines?
5. How does it handle Laravel container resolution, facade roots, and ::class string references — are there documented skip strategies?
6. Is there a documented, versioned rule/config API stability policy, or should we assume breaking changes on every minor?
7. Memory and wall-clock behaviour on a repository of our size with parallel workers enabled.
8. Who is the internal owner if the upstream maintainer steps away, and is a fork viable under MIT?

Integration Approach

Stack fit

• Declare in require-dev only; never in require. Keep it out of production images.
• Place structarmed.php at repository root alongside phpstan.neon and pint.json, and add it to CODEOWNERS for the architecture guild.
• Model layers against existing PSR-4 roots rather than inventing new namespaces: App\Http → Controllers, App\Actions / App\Services → Application, App\Models → Persistence, App\Support / App\Contracts → Shared, with vendor and test paths skipped.
• Start with Preset::PSR4() and a Laravel-appropriate MVC/DDD preset if available; add Preset::YAGNI() only after the layer rules are stable, because YAGNI produces the highest false-positive volume.

Migration path

1. Spike (1 week, one engineer). Run analyse read-only on the largest service directory. Record violation count, runtime, and a sample of false positives. Gate: fewer than ~5% of findings judged incorrect.
2. Advisory CI. Add a non-blocking job on pull requests and a weekly full-repo run. Publish the violation count as a dashboard metric.
3. Ratchet. Introduce a baseline or path-skip strategy so the build is green, then lock the rule set: new violations fail, existing debt is tracked.
4. Blocking gate. Promote to required status check on protected branches once the false-positive rate is understood and the skip list is stable.
5. Auto-remediation. Run --fix on a scheduled branch for the safe subset (YAGNI removals, abstract promotion) and land via normal PR review — never auto-merge.
6. Custom rules. Only after stages 1–5. Custom RuleInterface implementations are cheap to write but are now maintained code owned by us.

Compatibility

• Verify the package's php-parser/AST dependency range does not conflict with PHPStan/Larastan or Rector in composer.lock; these tools commonly share the parser and a version skew will block installation on the whole dev toolchain, not just this package.
• Confirm operation under the same PHP version matrix as CI. The project claims Windows/macOS/Linux support; validate on the CI image actually used.
• Pin to an exact minor (0.19.*) with a Renovate/Dependabot rule that opens a PR rather than auto-merging, and require a green analyse run as the upgrade test.

Sequencing dependencies

• Baseline/ignore capability must exist before the blocking gate, or the first PR after adoption will be a mass-exemption exercise.
• Layer definitions must be agreed by domain owners before custom rules, otherwise rules encode a boundary nobody signed off on.
• YAGNI must come after the team has a review norm for removing public surface, otherwise it will be disabled on day two.

Operational Impact

Maintenance

• Treat the config file as production code: versioned, reviewed, owned, and changed only with an ADR. Rule changes alter what "correct" means for every team simultaneously.
• Expect a release roughly weekly. Budget a recurring ~1 hour/month for upgrade review and a CI verification run; escalate to a half-day if a minor bump touches config semantics.
• Track upstream issues and the release notes for anything labelled fix: in the analyser or parallel worker — those are the changes most likely to alter results silently.

Support

• Assume no external support. Document it internally as "community OSS, internally supported." Name a primary and secondary owner.
• Because the license is MIT, keep the fork option live: verify the package builds and its test suite passes from a source checkout before you depend on it in a gating CI job. That is a one-evening exercise that converts an existential risk into a routine one.
• Do not let the tool become load-bearing for a compliance or audit requirement without the fork path validated.

Scaling

• Analysis cost grows with source volume and rule count, and the YAGNI/usage-tracking marker interfaces explicitly add analysis passes. Enable usage-aware rules only where needed.
• Use the cache in CI (keyed on lockfile and source hash), and prefer analysing changed paths on PRs with a nightly full run. This mirrors how PHPStan is normally operated and keeps PR feedback under a few minutes.
• Watch parallel worker memory on large monoliths; a worker crash mid-run previously produced unhelpful output (addressed in 0.16.6), so treat worker failure as a known failure class and assert on exit codes rather than parsing console text.

Failure modes and mitigations

• False positives blocking deploys — highest-probability incident. Mitigate with a mandatory advisory period, a documented skip mechanism, and an explicit "break-glass" label that disables the gate for a PR with reviewer sign-off.
• False negatives from dynamic dispatch — Laravel container resolution and string class names mean the graph is incomplete; rules will pass on code that is architecturally wrong. Position StructArmed as a tripwire, not a proof, and keep human review of new cross-layer dependencies.
• Cache staleness producing phantom passes — always run a full uncached analysis on the main branch nightly.
• Config drift where layer definitions no longer match reality and everyone learns to ignore output. Mitigate by scheduling a quarterly layer review tied to the domain map.
• Rule sprawl from enthusiastic custom rules. Cap it: every custom rule needs an owner, a rationale, and a test.

Ramp-up

• For application developers: near zero. Violations are human-readable and the fix is usually "inject the interface, move the call." A one-page internal guide plus the CI message is sufficient.
• For rule authors: a half-day. The ClassNode / RuleViolation API is small, and the marker-interface pattern for usage flags is well documented, but it requires comfort with AST-level reasoning and the tool's layer model.
• For the platform/DevEx engineer running it: 2–3 days including the dependency-conflict check, CI wiring, cache setup, and baseline strategy.
• Recommended enablement: one internal brown-bag demo using a real violation from our own codebase, plus a short ADR recording why this tool was chosen over Deptrac/PHPArkitect and what we will measure (violations per layer per month, mean time to remediate, percentage of PRs with zero new violations).

TPM verdict

• Worth a time-boxed spike and an advisory-only CI job. The capability — enforceable, configurable layer and abstraction rules in native PHP with --fix — is real and fills a gap the standard Laravel toolchain leaves open.
• Do not make it a blocking gate, or a dependency of any compliance control, until (a) the false-positive rate is measured on our codebase, (b) a baseline/skip strategy is confirmed, and (c) the fork path has been validated. The pre-1.0 versioning, single-maintainer concentration, and zero dependents are the deciding factors, not the feature set.