PHP Hexagonal Architecture

Every PHP developer eventually hits the same wall: a codebase that used to be simple now fights back. One small change breaks three unrelated things. Tests take minutes to run, so nobody runs them. The database, the framework, and the business logic have all become one tangled mass, and nobody remembers where one ends and the other begins. Hexagonal architecture, also known as ports and adapters, gives you a clear, repeatable way out of that mess, one that keeps your business rules protected from the technology choices around them.

Picture two developers handed the same bug report. One opens a two-thousand-line controller, holds their breath, and prays the fix doesn't break checkout. The other opens a single, small class, writes a test that runs in milliseconds, and ships the fix before lunch.

The difference isn't talent. It's architecture.

This book walks you through exactly how that second developer's codebase came to be, one deliberate decision at a time, until swapping a database, replacing an email provider, or testing a business rule in isolation stops being a nightmare and becomes... routine.

What's Inside

• Why tangled PHP code becomes expensive, and what "decoupled" really means
• Ports and adapters, explained from first principles, with real PHP interfaces
• Modeling entities, value objects, and aggregates that protect their own rules
• Building use cases, commands, and application services that stay framework-free
• Real adapters: Doctrine, PDO, HTTP controllers, queues, and external APIs
• Wiring it all together with dependency injection, Symfony, and Laravel
• A complete testing strategy: fast unit tests, test doubles, integration tests, and contract tests
• Refactoring an existing tangled monolith safely, without a risky rewrite

Who It's Meant For

This book is for PHP developers who are tired of fearing their own codebase. Whether you're maintaining a growing Laravel or Symfony application, leading a team that keeps stepping on each other's changes, or simply want your tests to run in seconds instead of minutes, this book meets you where you are and builds up from there. Some familiarity with object-oriented PHP is helpful. No prior architecture experience is required.

Your codebase isn't broken because you're a bad developer. It's broken because nobody showed you where the walls should go.

Every day you wait, another shortcut gets baked in, another class quietly learns too much, another "quick fix" makes the next one harder. The gap between the codebase you have and the one you actually want to work in only grows wider.

Open this book. Build the walls. Take your codebase back.