git:20261005.042befb to git:20261005.2187271

15 added, 12 removed. Audit A to A.

---

name: ports-and-adapters

description: Implement Hexagonal Architecture (Ports and Adapters) in Symfony; separate domain logic from infrastructure with clear boundaries

capabilities: [read, search]

tags: [architecture]

# projected by `bun run build` — do not edit by hand

allowed-tools:

- Read

- Glob

- Grep

---

# Ports And Adapters (Symfony)

## Use when

- - Refining architecture/workflows/context handling in Symfony projects.

- - Planning and executing medium/complex changes safely.

+ - Domain rules must not depend on Doctrine, HTTP, or a vendor SDK.

+ - An infrastructure dependency (storage, payment, mail provider) must be swappable or faked.

+ - Structuring a bounded context into Domain, Application and Infrastructure layers.

## Default workflow

- 1. Establish current boundaries, constraints, and coupling points.

- 2. Propose smallest coherent architectural adjustment.

- 3. Execute in checkpoints with validation at each stage.

- 4. Summarize tradeoffs and follow-up backlog.

+ 1. Model the domain in plain PHP: entities and value objects without ORM attributes.

+ 2. Declare ports as interfaces inside the domain, such as a repository interface.

+ 3. Write use cases in the application layer as commands and handlers that depend only on ports.

+ 4. Implement adapters in infrastructure (Doctrine repository, API client) and map entities outside the domain, with XML mapping.

+ 5. Bind each port to its adapter in the service configuration; controllers live in infrastructure.

## Guardrails

- - Use existing project patterns by default.

- - Avoid broad refactors without explicit need.

- - Keep decision log clear and auditable.

+ - Nothing under `src/Domain/` imports Symfony, Doctrine or vendor SDK classes.

+ - Dependencies point inward: infrastructure knows the domain, never the reverse.

+ - Do not add the layers to a CRUD module with no business rules.

+ - Test the domain with plain unit tests and the adapters with integration tests.

## Progressive disclosure

- Use this file for execution posture and risk controls.

- Open references when deep implementation details are needed.

## Output contract

- - Architecture/workflow changes.

- - Checkpoint validation outcomes.

- - Residual risks and next steps.

+ - The layer layout and the port interfaces.

+ - The adapters and their service bindings.

+ - Domain unit tests that boot no kernel.

## References

- `reference.md`