hexagonal-knowledge

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 patterns
• references/adapters-patterns.md — Adapter implementation patterns
• references/testing-patterns.md — Testing strategies for hexagonal architecture
• references/antipatterns.md — Common violations with detection patterns