Structarmed Laravel Package

Product Decisions This Supports

• Enforce architectural consistency in Laravel/PHP projects by converting architectural guidelines (e.g., DDD, MVC, PSR standards) into automated, executable checks. Reduces technical debt from ad-hoc conventions.
• Accelerate onboarding for new developers by codifying layer dependencies (e.g., "Domain cannot depend on Infrastructure") and coding standards (e.g., PSR-12 visibility rules).
• Shift-left quality gates: Integrate architecture validation into CI/CD pipelines (via CLI or PHPUnit extension) to catch violations early, reducing merge conflicts and rework.
• Roadmap for "architecture-first" development:
  • Phase 1: Adopt presets (e.g., Preset::DDD()) to baseline current violations, then iteratively fix them.
  • Phase 2: Customize rules (e.g., ruleset() for layer isolation) to align with domain-specific needs (e.g., "API layer must only depend on HTTP").
  • Phase 3: Embed checks in PR workflows to prevent regressions (e.g., skipClassViolation() for intentional exceptions).
• Build vs. Buy:
  • Buy: Avoid reinventing wheel for architecture enforcement (e.g., custom static analysis tools).
  • Build: Extend StructArmed with custom presets/rules for unique domain logic (e.g., "Service layer must use only Domain entities").
• Use Cases:
  • Legacy modernization: Gradually enforce DDD/MVC layers in monolithic apps via baselines.
  • Microservices: Validate cross-service dependencies (e.g., "OrderService cannot call PaymentService directly").
  • Team alignment: Standardize coding practices across distributed teams (e.g., PSR-12 visibility rules).

When to Consider This Package

• Adopt StructArmed if:

  • Your Laravel/PHP project has growing complexity (e.g., 5+ layers, mixed conventions) and needs executable architecture rules.
  • You’re migrating to DDD, Hexagonal, or Clean Architecture and want to enforce layer boundaries automatically.
  • Coding standards (PSR-1/12/15) are inconsistently followed, and you want to fail fast in CI/CD.
  • Your team frequently debates "Where should this class live?" or "Why does this service depend on a repository?"
  • You need lightweight static analysis without heavy tools like PHPStan/Psalm (StructArmed focuses on architecture, not type safety).

• Look elsewhere if:

  • Your project is small or monolithic with no clear layers (StructArmed’s value is highest in layered architectures).
  • You need deep code quality analysis (e.g., cyclomatic complexity, mutation testing) → use PHPStan, Psalm, or PHPMD.
  • Your team resists tooling or lacks buy-in for architectural constraints.
  • You’re using non-PHP backends (StructArmed is PHP-specific).
  • You need real-time IDE feedback (StructArmed is CLI/PHPUnit-focused; pair with PHPStan for IDE integration).

How to Pitch It (Stakeholders)

For Executives/Stakeholders:

*"StructArmed is a guardrail for our codebase’s architecture, turning our team’s hard-won conventions into automated checks. Think of it like a spellcheck for software design—it catches violations like:

• ‘Why is our OrderService directly calling the Database layer?’
• ‘This controller is 500 lines long—does it belong in the Domain?’
• ‘We’re missing return types on 30% of our methods.’

By integrating this into our CI pipeline, we’ll:

• Reduce technical debt from ad-hoc layer violations.
• Speed up onboarding—new devs won’t waste time guessing where classes ‘should’ live.
• Catch design flaws early, before they become expensive to fix.

It’s low-risk (MIT license, MIT contributor) and high-leverage—we can start with PSR standards, then layer in DDD/MVC rules as we scale. The CLI fits into our existing workflow, and the PHPUnit extension lets us fail builds before tests even run."*

For Engineering Teams:

*"StructArmed lets us enforce our architecture rules without manual reviews. Here’s how we’ll use it:

1. Baseline: Run structarmed analyse with Preset::DDD() to see current violations. We’ll fix critical ones immediately, baseline the rest for a smooth migration.
2. Layer Enforcement: Define rules like:

   ->ruleset([
       'Domain'   => ['Domain'],       // Domain can only depend on itself
       'Infrastructure' => ['Domain'] // Infrastructure can depend on Domain
   ]);
   

   This stops ‘Domain leaking into Infrastructure’ bugs before they’re written.
3. CI Integration: Add to phpunit.xml to block merges with violations:

   <extensions>
       <bootstrap class="Boundwize\StructArmed\PHPUnit\StructArmedExtension"/>
   </extensions>
   

4. Custom Rules: Extend it for our needs, e.g., ‘Service methods must have return types’ or ‘API controllers must be <200 lines’.

Why now?

• Our src/ directory is growing messy with mixed layer responsibilities.
• Onboarding new devs takes longer because conventions aren’t documented or enforced.
• We’re investing in DDD—this ensures we don’t accidentally violate layer boundaries.

Effort: ~2 hours to configure, then zero ongoing maintenance—it just works in the background."*