Hexagonal Architecture Knowledge Base
Quick reference for Hexagonal Architecture (Ports & Adapters) patterns and PHP implementation guidelines.
Core Principles
Hexagonal Architecture Overview
┌─────────────────────────────┐
│ PRIMARY ACTORS │
│ (Users, External Apps) │
└──────────────┬──────────────┘
│
┌──────────────▼──────────────┐
│ DRIVING ADAPTERS │
│ (Controllers, CLI, GUI, │
│ Message Consumers) │
└──────────────┬──────────────┘
│
┌─────────────────────────▼─────────────────────────┐
│ DRIVING PORTS │
│ (Input Interfaces) │
└─────────────────────────┬─────────────────────────┘
│
┌─────────────────────────▼─────────────────────────┐
│ │
│ APPLICATION CORE │
│ ┌─────────────────────────────────┐ │
│ │ APPLICATION LAYER │ │
│ │ (Use Cases, Services) │ │
│ └─────────────────┬───────────────┘ │
│ │ │
│ ┌─────────────────▼───────────────┐ │
│ │ DOMAIN LAYER │ │
│ │ (Entities, Value Objects, │ │
│ │ Domain Services) │ │
│ └─────────────────────────────────┘ │
│ │
└─────────────────────────┬─────────────────────────┘
│
┌─────────────────────────▼─────────────────────────┐
│ DRIVEN PORTS │
│ (Output Interfaces) │
└─────────────────────────┬─────────────────────────┘
│
┌──────────────▼──────────────┐
│ DRIVEN ADAPTERS │
│ (Repositories, External │
│ APIs, Message Publishers) │
└──────────────┬──────────────┘
│
┌──────────────▼──────────────┐
│ SECONDARY ACTORS │
│ (Database, External APIs, │
│ Message Queues) │
└─────────────────────────────┘
Core Rule: Application Core defines Ports. Adapters implement or use them.
Key Concepts
| Concept | Description | Location |
|---|---|---|
| Port | Interface defining how to interact with the core | Application/Domain |
| Driving Port | Input interface (how to use the application) | Application layer |
| Driven Port | Output interface (what the application needs) | Application/Domain |
| Driving Adapter | Implements input mechanism (HTTP, CLI) | Infrastructure |
| Driven Adapter | Implements external dependencies | Infrastructure |
| Application Core | Business logic, isolated from I/O | Domain + Application |
Quick Checklists
Driving Port Checklist
- Interface in Application layer
- Defines use case boundary
- Uses domain/application types
- No framework types
- Single responsibility
Driven Port Checklist
- Interface in Application/Domain layer
- Abstracts external dependency
- Uses domain types for return values
- No implementation details in signature
- Can have multiple adapters
Driving Adapter Checklist
- Implements/calls driving port
- Converts external format to domain format
- No business logic
- Framework code contained here
- One adapter per delivery mechanism
Driven Adapter Checklist
- Implements driven port interface
- Converts domain format to external format
- No business logic
- Handles external errors
- Easily replaceable
Common Violations Quick Reference
| Violation | Where to Look | Severity |
|---|---|---|
| Core depends on adapter | Domain importing Infrastructure | Critical |
| Missing port abstraction | Direct external service call | Critical |
| Business logic in adapter | if/switch in adapter | Critical |
| Framework in core | Symfony/Laravel in Domain | Warning |
| Port with implementation details | Interface using DB types | Warning |
| Adapter without port | Controller calling repository directly | Warning |
PHP 8.4 Hexagonal Patterns
Driving Port (Use Case Interface)
<?php
declare(strict_types=1);
namespace Application\Order\Port\Input;
use Application\Order\DTO\CreateOrderRequest;
use Application\Order\DTO\CreateOrderResponse;
interface CreateOrderUseCaseInterface
{
public function execute(CreateOrderRequest $request): CreateOrderResponse;
}
Driven Port (Repository Interface)
<?php
declare(strict_types=1);
namespace Domain\Order\Port\Output;
use Domain\Order\Entity\Order;
use Domain\Order\ValueObject\OrderId;
interface OrderRepositoryInterface
{
public function findById(OrderId $id): ?Order;
public function save(Order $order): void;
public function nextIdentity(): OrderId;
}
Driving Adapter (HTTP Controller)
<?php
declare(strict_types=1);
namespace Infrastructure\Http\Controller;
use Application\Order\Port\Input\CreateOrderUseCaseInterface;
use Application\Order\DTO\CreateOrderRequest;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
final readonly class CreateOrderController
{
public function __construct(
private CreateOrderUseCaseInterface $createOrder
) {}
public function __invoke(Request $request): JsonResponse
{
$dto = CreateOrderRequest::fromArray($request->toArray());
$response = $this->createOrder->execute($dto);
return new JsonResponse($response->toArray(), 201);
}
}
Driven Adapter (Repository Implementation)
<?php
declare(strict_types=1);
namespace Infrastructure\Persistence\Doctrine;
use Domain\Order\Entity\Order;
use Domain\Order\Port\Output\OrderRepositoryInterface;
use Domain\Order\ValueObject\OrderId;
use Doctrine\ORM\EntityManagerInterface;
final readonly class DoctrineOrderRepository implements OrderRepositoryInterface
{
public function __construct(
private EntityManagerInterface $em
) {}
public function findById(OrderId $id): ?Order
{
return $this->em->find(Order::class, $id->value);
}
public function save(Order $order): void
{
$this->em->persist($order);
$this->em->flush();
}
public function nextIdentity(): OrderId
{
return OrderId::generate();
}
}
References
For detailed information, load these reference files:
references/ports-patterns.md— Driving and Driven Port patternsreferences/adapters-patterns.md— Adapter implementation patternsreferences/testing-patterns.md— Testing strategies for hexagonal architecturereferences/antipatterns.md— Common violations with detection patterns
Converted and distributed by TomeVault — claim your Tome and manage your conversions.