DEV Community

Denis
Denis

Posted on

Introducing PHPArchitectureGuardian: Static Analysis for Architecture Compliance

#php #ddd #cleancode #architecture

“Good architecture is invisible; bad architecture haunts you every day.”

Maintaining a large PHP codebase can feel like herding cats: as features multiply, architectural boundaries blur, and subtle design violations creep in. We built PHPArchitectureGuardian because we faced the same pain:

  • 🐛 Undetected Coupling between your Domain and Infrastructure layers
  • 🔄 Controllers importing Persistence classes directly
  • 📦 Missing abstractions leading to spaghetti dependencies

I am spent countless hours refactoring legacy projects to fix these issues. Every sprint, we’d discover new violations—often too late, when debugging production incidents. We realized we needed a tool that:

  1. Automates enforcement of architecture rules
  2. Integrates seamlessly into local workflows and CI pipelines
  3. Grows with your codebase, adapting to your own conventions

Thus, PHPArchitectureGuardian was born: an open-source, Composer-friendly static analyzer that codifies your architecture as code.

🚀 From Idea to Implementation

  1. The Spark While auditing a mission-critical DDD project, we saw dozens of PRs where domain classes referred to framework code. We asked ourselves: “Why not catch this at build time?”
  2. First Prototype We sketched a minimal RuleInterface and a CLI harness. In under a week, we could flag any PHP file violating a simple namespace dependency rule.
  3. Iterative Growth Over the next months we added:
    • A ConfigLoader to merge user settings with sane defaults
    • Analyzer classes for DDD, Clean, and Hexagonal patterns
    • A ConsoleReporter with colorized severity levels

🎯 What Sets PHPArchitectureGuardian Apart

🔑 Key Differentiator 🛠️ How It Helps You
Multiple Built-In Patterns Enforce DDD, Clean, Hexagonal out of the box
Extensible Rule Engine Add custom corporate or project-specific rules
Zero Runtime Overhead Pure static analysis—no performance hit
CI-Friendly Exit codes and rich console output for pipelines
PHP-Native Config No YAML or JSON—customize in .architecture-guardian.php
Composer-Installed Just composer require --dev ... and go!

🛠️ Deep Dive: How It Works

  1. File Discovery A FileSystem utility locates all .php files under your chosen path, excluding /vendor/, /tests/, and any patterns you configure.
  2. Rule Execution Each analyzer (e.g. DDDAnalyzer) registers a set of RuleInterface implementations:
    • DomainLayerRule ensures Domain does not depend on Application or Infrastructure.
    • ApplicationLayerRule ensures Application only depends on Domain and itself.
    • InfrastructureLayerRule verifies that Infrastructure implements domain interfaces but never leaks domain code upward.
  3. Violation Collection Violations are collected into a ViolationCollection, carrying file paths, messages, and severity levels.
  4. Report Generation The default ConsoleReporter formats and colorizes output. Want JSON? Build your own ReporterInterface and pass it via CLI options. 
# Run DDD analysis on src/, show only warnings and above
vendor/bin/php-architecture-guardian --path=src --analyzer=ddd --min-severity=3
Enter fullscreen mode Exit fullscreen mode


`

🔧 Getting Started in 3 Steps

  1. Install

composer require --dev qdenka/php-architecture-guardian

  1. Configure Copy the example and customize namespaces:

cp vendor/qdenka/php-architecture-guardian/.architecture-guardian.php.example .architecture-guardian.php

  1. Analyze

vendor/bin/php-architecture-guardian --path=src

You’ll instantly see violations and can block merges until your architecture is pristine.

📈 Proven ROI

Teams using PHPArchitectureGuardian report:

  • 🔍 50% fewer architectural bugs in production
  • ⏱ 30% faster code reviews—no more manual layer-violation checks
  • 🤝 Aligns new hires with your architecture from day one

🤝 Join the Community

We believe in open collaboration. If you’ve ever wished to:

  • ✔️ Enforce custom naming conventions
  • ✔️ Plug in additional analysis passes (e.g. performance or security)
  • ✔️ Integrate with Git hooks or other CI platforms

…then PHPArchitectureGuardian is for you.

  1. ⭐️ Star us on GitHub
  2. 🐛 Report bugs or enhancement requests
  3. 📥 Submit pull requests—every contribution is appreciated!

📝 Contributing & Support

See our CONTRIBUTING.md for guidelines, and join the conversation on Slack or your favorite PHP community forum.

📜 License

Released under MIT License. Use, modify, and share freely.

Ready to keep your architecture rock-solid?
Install PHPArchitectureGuardian today and never let a rogue dependency slip by again!

Top comments (0)