clean-architecture_skill

Overview

This skill provides practical implementation patterns for Clean Architecture, Hexagonal Architecture (Ports & Adapters), and Domain-Driven Design in PHP 8.3+ with Symfony 7.x. It shows how to structure domain, application, adapter, and infrastructure layers so business logic stays framework-agnostic and testable. Use it to build maintainable enterprise backends, refactor legacy code, or introduce DDD tactics in Symfony projects.

How this skill works

The skill defines a clear layered directory layout and concrete examples for value objects, entities, repository ports, commands, handlers, controllers, and adapters. It explains inward-only dependency rules, how to write immutable value objects, how to model aggregates and domain events, and how to bind ports to adapters via Symfony DI. Examples include in-memory test doubles and Doctrine adapters so you can test core logic without framework dependencies.

When to use it

• Architecting new enterprise PHP applications with Symfony 7.x
• Refactoring legacy PHP code to modern, testable patterns
• Implementing Domain-Driven Design (entities, value objects, aggregates)
• Designing modular systems with swappable infrastructure adapters
• Building test suites that run without Symfony/Doctrine

Best practices

• Follow the dependency rule: dependencies must point inward; domain has no framework references
• Make value objects immutable (readonly) and validate at construction time
• Model rich domain entities with behavior and factory methods, avoid anemic models
• Keep repository interfaces small and focused (Interface Segregation)
• Provide in-memory adapters for fast unit tests and bind real adapters via DI

Example use cases

• Create an Email value object with validation and equality checks used across services
• Implement a User aggregate with domain events and encapsulated business rules
• Write CreateUserCommand and handler to orchestrate domain creation and persistence
• Add a Doctrine adapter that implements the UserRepositoryInterface and a matching in-memory test double
• Expose application handlers through Symfony controllers and request DTOs with validation