Structarmed Laravel Package

Product Decisions This Supports

• Build vs. buy for architecture enforcement. StructArmed is a dev-only Composer dependency that turns layer/dependency conventions into executable checks, so the "do we build our own architectural linting into CI?" question collapses to a config file plus a CI step. That frees engineering time for the actual architectural boundaries rather than the tooling that polices them.
• Feature gating and roadmap sequencing. It ships presets for PSR-4/PSR-15, MVC, and DDD, plus a YAGNI preset that flags unused interfaces, unused abstract classes, unused traits, and classes that are only extended but never instantiated. For a PM, YAGNI is a concrete way to budget removal work: which abstractions we paid for but nobody uses, and where we can safely collapse or abstract-ify classes instead of carrying speculative seams.
• Technical-debt and "modernization" initiatives. Because violations are reported with file, line, class, and layer, output can be triaged into backlog items ("Domain must not depend on Infrastructure") rather than vague refactor tickets. It gives a defensible, enumerable definition of done for an architecture cleanup epic.
• Onboarding and knowledge transfer. New hires and contractors inherit conventions implicitly. A checked-in structarmed.php is living documentation of the intended layering, which shortens ramp-up and reduces review nitpicking in PRs.
• Monolith-to-modular / modular monolith bets. If the roadmap involves carving a Laravel app into bounded contexts, defining layers and allowed dependencies up front is the cheap way to test whether the target architecture is even enforceable before committing to a multi-quarter restructuring.
• Team scaling and review bandwidth. It shifts boundary enforcement from senior reviewer attention to automated checks, which matters when headcount grows or when contributions come from outside the core team.
• Custom rules as policy. Native-PHP custom rules (e.g. ContractMustBeImplementedRule using UsedInterfaceAwareRuleInterface) let you encode product-specific policies — "everything in Contracts must be implemented or referenced" — and evolve them as the product's seams change.

When to Consider This Package

Adopt when:

• You have an explicit or aspirational layering scheme (MVC, DDD, hexagonal, modular monolith) and violations currently surface only in code review or in production coupling incidents.
• Your stack is PHP with a real Composer workflow and CI; the package is dev-only, MIT, and installs in three commands (require --dev, init --preset, analyse).
• You want rules expressed in PHP rather than a bespoke DSL — custom rules are plain classes over ClassNode, so a senior engineer can own the rulebook without a new language to learn.
• You're already investing in static analysis (PHPStan level max is used on the project itself) and want architecture checks as the next rung on the same ladder.
• You need incremental adoption — presets give a baseline, and rules/paths can be skipped so a legacy codebase can be brought under guard gradually instead of all at once.
• You want visualization cheaply: the community StructArmed Explorer renders structarmed.php as an interactive layer-dependency graph with no installation, useful for architecture reviews and stakeholder walkthroughs.

Look elsewhere or wait when:

• Vendor and ecosystem risk is unacceptable. 60 stars, zero dependents, and a pre-1.0 version line (0.19.x) mean no third-party signal that the API is stable or the project outlives its maintainer. It is effectively a single-maintainer dependency; a bus-factor review is mandatory.
• You need SLAs, commercial support, or security-response guarantees. There is none here.
• Your boundaries are already enforced by an established tool (Deptrac, PHPArkitect, PHPStan custom rules) and migrating rulebooks has real cost. Switching buys configurability and the YAGNI preset, not a category leap — justify on concrete pain, not novelty.
• You have no meaningful layering to enforce (small app, single team, short horizon). The overhead of maintaining a ruleset exceeds the value of the violations it catches.
• YAGNI rules will misfire on libraries or SDKs. Usage detection only sees scanned paths, so intentionally public extension points will be flagged as unused. If you publish packages, scope or skip those paths before enabling the preset.
• The team cannot commit to acting on failures. A guard that is routinely bypassed or ignored in CI is worse than none — it teaches the team that red is normal.

Adoption plan a PM should insist on before purchase-in-spirit (it's free, so the cost is team time):

1. Run init --preset matching your architecture and diff the report against reality — treat the first run as a discovery exercise, not a gate.
2. Baseline: skip known-legacy paths, enable blocking CI on new violations only.
3. Assign one owner for the ruleset and review it quarterly alongside the roadmap.
4. Pin the version; treat minor bumps as reviewable changes given pre-1.0 semantics.

How to Pitch It (Stakeholders)

For executives (one paragraph): StructArmed is a free, MIT-licensed PHP tool that turns our architecture conventions into automated checks in CI. It costs no license fee and installs as a development-only dependency, but it converts architectural intent — which today lives in senior engineers' heads and code-review comments — into something machine-enforced on every pull request. The business case is reduced coupling, faster onboarding, and a defensible way to scope and close technical-debt work, including identifying abstractions we built that nobody uses. The risks are maturity and maintainer concentration: the project is small (60 GitHub stars, no dependent packages, pre-1.0), so we should adopt it behind a pinned version, with a named internal owner for the ruleset, and with no assumption of vendor support. We recommend a scoped pilot on one codebase with new-violation-only gating before any broader rollout.

For engineering leadership:

• Dev-only dependency, MIT license, zero runtime footprint in production.
• Three-command quick start; presets for PSR-4/PSR-15, MVC, and DDD, with a YAGNI preset for dead abstractions.
• Rules are native PHP classes over ClassNode, so we own and extend policy without a new DSL; marker interfaces (UsedInterfaceAwareRuleInterface, UsedTraitAwareRuleInterface, ExtendedClassAwareRuleInterface) keep analysis cost proportional to what rules actually need.
• Violations carry file, line, class, and layer — directly triageable into tickets.
• Actively released with CI, Codecov, and PHPStan level max badges; performance work is ongoing (caching, parallel workers), which matters for large repos.
• Known constraints to design around: pre-1.0 API churn, single-maintainer bus factor, no commercial support, and YAGNI false positives on intentionally public extension points — mitigate with pinned versions, path skips, and a quarterly ruleset review.

What we're asking for: approval for a timeboxed pilot (one repo, one quarter, one named owner), success measured by new architecture violations blocked in CI and a reduction in review comments about layering — not by stars or adoption metrics.