30 Chapters·7 Parts·4 Languages

Decoupled PHP.

Clean and Hexagonal Architecture for Applications That Outlive the Framework.

Ports the domain owns. Adapters for Doctrine, Eloquent, HTTP and the queue. One composition root, and a test suite that never boots Laravel or Symfony. Both architectures, taught together, in PHP 8.3 idioms.

amazonEnglishamazonDeutschamazonPortuguêsamazon日本語

Kindle · Paperback · Hardcover

Decoupled PHP
“A framework is something your application uses, not something your application is. The moment that flips, every upgrade becomes a migration and every business rule needs an HTTP request to run.”
Gabriel Anhaia

Gabriel Anhaia

Senior Software Engineer · Berlin

Sound familiar?

→Your controller calls Eloquent directly, so the discount rule only exists inside an HTTP request?
→Testing one pricing calculation needs a database, a container, and a booted kernel?
→The same business rule lives in a controller, a model, and a service class nobody owns?
→The framework upgrade has been a stale draft pull request for two quarters?
→Swapping the ORM — or the framework — is only ever discussed as a rewrite?

None of that is Laravel's fault, or Symfony's. It is where you put the business logic.

What's inside

30 chapters. 7 parts. One synthesis.

Cockburn's ports and adapters and Martin's four rings have been explained in Java for twenty years. This book teaches them together, in PHP, against real Laravel 11 and Symfony 7 codebases — not as Java translated into PHP syntax.

Part I — Why PHP Needs Architecture

3 chapters

The framework trap. What coupling actually costs by year four. What Clean and Hexagonal each really promise, minus the buzzwords.

Part II — Hexagonal in PHP

4 chapters

A domain of plain PHP objects. Ports written in the language of the business. Adapters at the edge. The dependency rule.

Part III — Clean in PHP

4 chapters

The four rings in PHP terms: entities, use cases, interface adapters — and a hard look at why the outer ring is replaceable.

Part IV — Two Architectures, One Codebase

3 chapters

Where Cockburn and Martin agree, where they don't, which to reach for — and the anti-patterns both of them forbid.

Part V — Building a Production Application

6 chapters

Layout and namespaces for PHP 8.3+. The domain, the ports, the use cases. Inbound and outbound adapters. The composition root.

Part VI — Production Patterns

5 chapters

Testing without a database. Errors across layers. Transactions, domain events, observability and authorization — all through ports.

Part VII — Evolution and Migration

5 chapters

When this is overkill. Refactoring a live Laravel service, then a Symfony one. The strangler pattern. The complete reference service.

After reading

You'll be able to:

Model a domain in plain PHP 8.3 — value objects, enums, invariants, no extends Model
Write ports in the language of the business instead of the language of your schema
Serve one use case from three inbound adapters: HTTP, CLI, and a queue worker
Put Doctrine, Eloquent, Guzzle and AMQP behind outbound ports the domain owns
Wire the whole application in one composition root — Laravel's container and Symfony's, compared
Run the domain suite in milliseconds, without booting a framework or touching a database
Keep transactions, domain events, logging and authorization from leaking inward
Enforce the dependency rule mechanically with Deptrac, so review does not have to
Refactor a live Laravel or Symfony service one endpoint at a time — no freeze week
Recognise the projects where this is overkill, and skip it on purpose

Read it in your language

Four editions.

Each translation is its own edition on its own Amazon storefront. Formats vary by language — the English edition ships in all three.

4 languages
🇺🇸English🇩🇪Deutsch🇧🇷Português🇯🇵日本語

Code you can run, not code you can read

Companion Repository

Runnable companion code, Dockerized and organised chapter by chapter. Bring up the container, run the suite, then change the adapters and watch the domain tests stay green.

github.com/gabrielanhaia/php-clean-hexagonal-examples
Gabriel Anhaia

About the author

Gabriel Anhaia

Senior Software Engineer in Berlin. He started his career in PHP and shipped production services on Laravel, Symfony, Yii and CodeIgniter before carrying the same backend craft into Go, TypeScript and the JVM — long enough to watch the same architectural mistake resurface in four different syntaxes.

Also the author of Hexagonal Architecture in Go and creator of Hermes IDE, an open-source AI-native terminal.

Frameworks have a shelf life

Demote the framework.
Keep the application.

30 chapters that move your business rules out of the request cycle and into code that will still make sense after the next major version.

amazonEnglishamazonDeutschamazonPortuguêsamazon日本語

Kindle · Paperback · Hardcover

Same architecture, another language

Ports and adapters in Go: Hexagonal Architecture in Go.

See the book