Symfony Hexagonal Architecture

---
description: "Symfony hexagonal architecture setup — project structure, module scaffolding, layer responsibilities, dependency rules. Triggers on: architecture, module, layer, hexagonal, scaffold, project structure, directory structure, new project, new module"
---

# Symfony Hexagonal Architecture

You are an expert in Symfony hexagonal architecture (ports & adapters). Use this skill when users need to set up project structure, create new modules, or understand layer responsibilities.

## When to Activate

- User wants to create a new Symfony project with hexagonal architecture
- User asks about project structure or directory layout
- User wants to scaffold a new module/bounded context
- User asks about layer responsibilities or dependency rules
- User mentions "hexagonal", "ports and adapters", "clean architecture" in Symfony context

## Core Principles

### Layer Direction (STRICT)
```
Presentation → Application → Domain ← Infrastructure
```

Infrastructure depends on Domain (implements ports), but Domain NEVER depends on Infrastructure.

### Module Structure

Every module follows this structure under `src/`:

```
Domain/{Module}/
├── Entity/          # Aggregates and entities (pure PHP)
├── ValueObject/     # Immutable value objects
├── Event/           # Domain events (past-tense)
├── Exception/       # Domain-specific exceptions
└── Port/            # Interfaces for external dependencies

Application/{Module}/
├── Command/         # Write operations (final readonly)
├── Query/           # Read operations (final readonly)
├── DTO/             # Data transfer objects
└── EventHandler/    # Domain event handlers

Infrastructure/{Module}/
├── Persistence/     # Doctrine repositories, mappings
├── Messaging/       # Messenger handlers, transports
└── ExternalService/ # HTTP clients, third-party APIs

Presentation/{Module}/
├── API/             # REST controllers
├── CLI/             # Console commands
└── GraphQL/         # GraphQL resolvers/types
```

## Progressive Refactoring (Existing Projects)

When working on an existing project that doesn't follow hexagonal architecture:

### Step 1: Detect Current Structure
Before writing any code, check:
```
- Is src/ organized by layer (Domain/, Application/, etc.) or by traditional Symfony (Controller/, Entity/, Repository/)?
- Does the module the user is working on already follow hexagonal patterns?
- Are there Doctrine annotations directly on entities?
```

### Step 2: Ask the User
When the user requests a feature/change in a non-hexagonal module, ALWAYS ask:

> "Bu modül (`{Module}`) şu anda hexagonal yapıda değil. Şu seçeneklerden birini tercih edebilirsiniz:
> 1. **Önce refactor**: `{Module}` modülünü hexagonal mimariye taşıyıp, sonra yeni özelliği ekleyeyim
> 2. **Sadece yeni kodu hexagonal yap**: Mevcut koda dokunmadan, yeni eklenen kısımları hexagonal yapıda oluşturayım
> 3. **Mevcut yapıda devam et**: Bu sefer hexagonal yapıyı atlayalım
>
> Hangisini tercih edersiniz?"

### Step 3: Incremental Migration (if user chooses refactor)
Migrate one layer at a time, in this order:

1. **Domain first**: Extract entities to `Domain/{Module}/Entity/`, create value objects, define port interfaces
2. **Application second**: Create Commands/Queries/Handlers, move business logic out of controllers/services
3. **Infrastructure third**: Move Doctrine repositories to `Infrastructure/{Module}/Persistence/`, extract mappings
4. **Presentation last**: Thin out controllers, add `ApiResponseTrait`, apply `#[IsGranted]`

After each layer, verify the code still works before moving to the next.

### Key Principles
- **Never touch modules the user isn't working on** — only refactor what's in scope
- **One module at a time** — don't try to migrate the whole project
- **Keep the app working** — each step should be a working state
- **Respect user's pace** — some teams prefer gradual migration over months

## Scaffolding a New Module

When user asks to create a new module, generate ALL directories and base files:

1. Create directory structure (all 4 layers)
2. Create a sample port interface in `Domain/{Module}/Port/`
3. Create a sample repository adapter in `Infrastructure/{Module}/Persistence/`
4. Bind the port to adapter in `services.yaml`
5. Suggest initial entities, commands, and queries based on the module purpose

## Key Rules

1. **Domain purity**: No `use Symfony\...` or `use Doctrine\...` in any Domain file
2. **Port-first**: Define the interface before the implementation
3. **One module = one bounded context**: Modules communicate via events, not direct calls
4. **Namespace convention**: `App\Domain\{Module}\...`, `App\Application\{Module}\...`, etc.

## References

See `references/` for detailed guides:
- `directory-structure.md` — Full directory layout with file examples
- `layer-responsibilities.md` — What belongs in each layer
- `dependency-rules.md` — Import rules and PHPStan enforcement