Structarmed Laravel Package

Technical Evaluation

Architecture Fit

StructArmed is a static architecture enforcement tool designed to validate PHP/Laravel projects against predefined architectural rules (e.g., layer isolation, PSR standards, DDD, MVC). It aligns well with Laravel’s modular, layered architecture (e.g., App/, Domain/, Infrastructure/), making it ideal for enforcing:

• Layer dependencies (e.g., Domain → Application → Infrastructure).
• PSR compliance (PSR-1, PSR-4, PSR-12, PSR-15).
• Custom business rules (e.g., "Controllers must not depend on Domain entities").
• Legacy migration via baselines.

Key Strengths:

• Declarative configuration: Define rules in structarmed.php (e.g., layer(), ruleset(), presets).
• Preset-driven: Prebuilt rules for DDD, MVC, PSR standards, and Laravel-like structures.
• Customizable: Override or extend rules via replaceRule() or rule().
• CI/CD integration: Fail builds on violations or generate baselines for gradual adoption.

Potential Gaps:

• No runtime enforcement: Only static analysis (violations are detected post-code-writing).
• Laravel-specific features: Limited native support for Laravel’s service container, Facades, or Blade templates (though custom rules can mitigate this).
• Performance overhead: Parallel analysis is default, but large codebases may require tuning (--disable-parallel).

Integration Feasibility

Laravel Compatibility:

• High: StructArmed is PHP-agnostic but works seamlessly with Laravel’s directory structure (e.g., app/, src/, database/).
• Dependencies: Requires PHP 8.1+ (Laravel 9+ compatible). No Laravel-specific dependencies.
• Tooling Integration:
  • PHPUnit: Fail tests on violations via StructArmedExtension.
  • CI/CD: JSON reports for tools like GitHub Actions or GitLab CI.
  • IDE: Static analysis tools (PHPStan, Psalm) can leverage rule constants for better autocompletion.

Migration Path:

1. Initial Setup:
   • Install as a dev dependency (composer require --dev boundwize/structarmed).
   • Generate a baseline (structarmed analyse --generate-baseline).
2. Incremental Enforcement:
   • Start with lightweight presets (e.g., PSR4, PSR12).
   • Gradually add stricter rules (e.g., DDD, MVC).
3. Customization:
   • Define layers via layer() or layerPattern() (e.g., Domain, Application).
   • Enforce layer isolation with ruleset().
   • Skip legacy paths or known violations.

Example Laravel Integration:

// structarmed.php
use Boundwize\StructArmed\Architecture;
use Boundwize\StructArmed\Preset\Preset;

return Architecture::define()
    ->layer('Domain', 'app/Domain/')
    ->layer('Application', 'app/Application/')
    ->layer('Infrastructure', 'app/Infrastructure/')
    ->ruleset([
        'Domain'       => [],          // Domain has no dependencies
        'Application'  => ['Domain'],  // App can depend on Domain
        'Infrastructure' => ['Application'], // Infra can depend on App
    ])
    ->withPresets(Preset::PSR12(), Preset::DDD())
    ->skipPaths(['tests/', 'vendor/']);

Technical Risk

Key Questions for TPM:

1. Architecture Goals:
   • Are we enforcing layer isolation (e.g., DDD), PSR compliance, or both?
   • Should rules be strict (fail builds) or advisory (baseline + warnings)?
2. Tooling Integration:
   • Will violations be checked in CI/CD (e.g., GitHub Actions) or pre-commit (e.g., Laravel Pint hooks)?
   • Should StructArmed replace or complement existing tools (e.g., PHPStan, Pest)?
3. Customization Needs:
   • Do we need Laravel-specific rules (e.g., "Controllers must extend BaseController")?
   • How will we handle legacy code (baselines vs. refactoring)?
4. Performance:
   • What’s the max acceptable analysis time in CI?
   • Should we cache results between runs (configurable via cacheDirectory)?
5. Team Adoption:
   • How will developers debug violations (e.g., IDE integration, CLI flags)?
   • Will we train teams on reading rule outputs?

Integration Approach

Stack Fit

StructArmed is language-agnostic but optimally fits Laravel’s modular, layered architecture. Key alignments:

• Directory Structure: Maps naturally to Laravel’s app/, src/, or custom namespaces.
• Dependency Management: Composer-based (no Laravel-specific dependencies).
• Tooling Ecosystem:
  • PHPUnit: Native extension for test-time enforcement.
  • CI/CD: JSON reports for integration with tools like SonarQube.
  • IDE: Rule constants enable static analysis tooling (PHPStan/Psalm).

Laravel-Specific Considerations:

• Facades/Helpers: May require skipPaths() to avoid false positives.
• Blade Templates: Exclude resources/views/ from ruleset checks.
• Service Container: Custom rules can enforce container binding patterns (e.g., "Only App\Services\* can be bound to Illuminate\Contracts\*").

Migration Path

Example Migration Timeline:

1. Week 1: Install StructArmed, generate baseline, enforce PSR12.
2. Week 2: Define layers (Domain, Application), enforce DDD presets.
3. Week 3: Add custom rules (e.g., "Controllers must not call DB::raw()").
4. Week 4: Integrate with CI/CD; require compliance in PRs.

Compatibility