Hexagonal Architecture (Ports & Adapters)

When to use

• The user wants domain logic that does not import framework, ORM, or HTTP classes so it can be tested and reused in isolation.
• The user needs to swap a database, message queue, or third-party client without changing business logic.
• The user wants to unit-test use cases by substituting in-memory fakes for databases and external services.

When NOT to use

• Do not force a hexagonal core when the team deliberately builds framework-native (active-record, controllers-with-logic) and accepts the coupling.
• Do not impose ports and adapters on a thin CRUD script that has no business rules and will never swap infrastructure.

Core guidance

• Express ports as interfaces owned by the core — Declare each port as an interface that lives with the domain, and let adapters in the infrastructure layer implement it.
• Point every dependency toward the core — Let the domain core depend on nothing outward; adapters and framework code depend on the core's ports, never the reverse.

Quick recipe

1. Declare a driven port interface in the domain for each outbound need, e.g. interface OrderRepository with save(Order $order): void, typed only in domain terms. (verify: The interface lives with the domain and references no framework or ORM type)
2. Write a concrete adapter in the infrastructure layer that implements the port, e.g. EloquentOrderRepository implements OrderRepository, mapping domain objects to rows. (verify: The adapter satisfies the interface and no domain class references the adapter)
3. In the composition root, bind the port to the adapter (e.g. $container->bind(OrderRepository::class, EloquentOrderRepository::class)) and inject the port into the core. (verify: Swapping the binding to an in-memory adapter runs the core unchanged)

Best practices

• Split ports into driving (inbound, called by controllers and CLI to invoke the core) and driven (outbound, implemented by persistence and clients the core calls)
• Keep framework, ORM, and transport types (requests, Eloquent models, HTTP clients) out of the domain; translate them to plain domain objects in the adapter
• Bind each port to a concrete adapter in one composition root (the container config or bootstrap), never by having the core reach for a concrete class

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Ports with an anemic core behind them — Wrapping getters and setters in ports while the real logic lives in adapters produces the ceremony of hexagonal with none of its benefit. Fix: Put the actual business rules in the domain core so the ports guard meaningful behavior, not a pass-through data holder.
2. Leaking infrastructure types through a port — Declaring a port method that returns or accepts a framework type (an Eloquent model, a PSR request) drags infrastructure back into the core. Fix: Type ports only in domain terms — entities, value objects, and DTOs the core owns — and map to and from framework types inside the adapter.
3. Sharing one persistence model as the domain model — Reusing the ORM entity as the domain entity ties the core's shape to the database schema and its lazy-loading behavior. Fix: Keep a plain domain model and translate it to and from the persistence model inside the driven adapter, even when the two look similar today.

Version notes

• Pure domain modeling with PHP 8.1 features (PHP >=8.1) — PHP 8.1 enums, readonly properties, and first-class enum interfaces let the domain core express value objects and state without any framework dependency.
• Property hooks refine adapter mapping in PHP 8.4 (PHP >=8.4) — From PHP 8.4, property hooks let an adapter expose a domain-shaped view over stored data without a hand-written getter, keeping the mapping code in the adapter thin.

Security

• Not applicable — no I/O, auth, or untrusted input.

Testing

• Activation and decision behavior are verified in eval/scenarios/architecture/hexagonal.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Related: architecture/cqrs, architecture/dependency-inversion, php/value-objects