Weave Code
Structarmed Laravel Package
boundwize/structarmed
StructArmed is a dev-only PHP architecture guard: define layers and dependency rules, start from presets (PSR-4/1/12, MVC, DDD), then tune or skip checks in PHP. Run it in CI to catch boundary violations before they become conventions.
🛡️ Configurable PHP architecture guards — define your layers and rules, then keep them enforced
Frequently asked questions about Structarmed
- How do I enforce DDD layer dependencies (Domain → Application → Infrastructure) in Laravel using StructArmed?
- Define layers in `structarmed.php` using `layer()` and enforce dependencies with `ruleset()`. For example, restrict the Domain layer to have no dependencies, allow Application to depend on Domain, and Infrastructure to depend on Application. Use presets like `Preset::DDD()` for a starting point, then customize as needed.
- Can StructArmed work with Laravel 9+ and PHP 8.1+?
- Yes, StructArmed requires PHP 8.1+ and is fully compatible with Laravel 9+. It’s framework-agnostic but works seamlessly with Laravel’s directory structure (e.g., `app/`, `src/`). Install it as a dev dependency with `composer require --dev boundwize/structarmed`.
- How do I skip specific paths or classes from StructArmed checks?
- Use `skipPaths()` in your `structarmed.php` config to exclude directories like `tests/` or `vendor/`. For specific classes, use `skipClassViolation()` in custom rules. This is useful for legacy code or known edge cases that don’t fit your architecture rules.
- Will StructArmed slow down my CI/CD pipeline for large Laravel projects?
- StructArmed defaults to parallel analysis for speed, but large codebases may benefit from disabling parallel mode with `--disable-parallel`. Alternatively, limit analysis to critical paths using `skipPaths()` or run it incrementally during development.
- How can I integrate StructArmed with PHPUnit or GitHub Actions?
- For PHPUnit, use the `StructArmedExtension` to fail tests on violations. In GitHub Actions, add a step to run `vendor/bin/structarmed analyse` and check the exit code. Generate JSON reports for detailed violation logs, which can be parsed in CI workflows.
- Does StructArmed support Laravel-specific features like Facades or Blade templates?
- StructArmed is PHP-agnostic and doesn’t natively handle Laravel Facades or Blade templates. However, you can exclude paths (e.g., `resources/`) or use `skipPathsForRuleset()` to avoid false positives. Custom rules can also address specific Laravel quirks if needed.
- How do I start enforcing rules gradually without breaking existing code?
- Generate a baseline with `structarmed analyse --generate-baseline` to record current violations. Then, enforce rules incrementally by starting with lightweight presets (e.g., `PSR4`, `PSR12`) and adding stricter rules (e.g., `DDD`, `MVC`) over time. This avoids sudden build failures.
- What if StructArmed flags a false positive for a legitimate dependency?
- False positives often occur with complex layer patterns or custom rules. Use `skipClassViolation()` to exempt specific classes or refine your rules. Test rules incrementally and document exceptions in your `structarmed.php` config for clarity.
- Are there alternatives to StructArmed for Laravel architecture enforcement?
- Yes, alternatives include **PHPStan** (with custom rules), **Psalm**, or **Architecture Tests** (via Pest or PHPUnit). StructArmed stands out for its declarative PHP-based configuration and preset-driven approach, making it easier to define and enforce layered architectures like DDD or MVC without writing complex test cases.
- How do I customize or extend StructArmed’s presets for my Laravel project?
- Extend presets by chaining methods like `withPresets()` and overriding rules with `replaceRule()` or `rule()`. For example, combine `Preset::PSR12()` with custom layer rules. Document your configuration in `structarmed.php` and share presets with the community to reduce maintenance effort.
Weaver
How can I help you explore Laravel packages today?