Skip to content

Lesson 7 of 15 · Architectural Styles

Hexagonal vs Clean vs Vertical Slice Architecture

Advanced•
lesson•
November 16, 2026•
~7 min read

Architectures as religion

If you spend enough time reading about software architecture online, you'll find tribes. The Hexagonal tribe insists everything else is an over-complicated version of the same idea. The Clean tribe insists Hexagonal is missing the use case as a first-class concept. The Vertical Slice tribe insists both are hopelessly horizontal and a feature should never be split across folders.

In my experience, working PHP architectures land somewhere in the middle of all three, and the engineers who've shipped multiple long-lived products use ideas from all of them. The differences in how strictly each one is interpreted are usually bigger than the differences between them.

Dependency direction versus organization

Hexagonal and Clean are about dependency direction (which kinds of code can depend on which). Vertical Slice Architecture is about organization (which folder a file lives in). They aren't fully alternatives.

Here is the same RequestReservation use case laid out three ways, seven files each, colored by layer:

Three folder trees of the same seven RequestReservation files, each file colored by its layer: presentation, use case, domain or infrastructure. In the Clean tree each color has its own folder: Domain, Application, Infrastructure and Http. In the Hexagonal and Vertical Slice trees the controller, request, command and handler share the RequestReservation folder, the entity and its repository interface sit in Reservation, and the Eloquent adapter sits in Infrastructure. The Hexagonal tree also tags each port and adapter.

Clean, in its pragmatic form, groups the files by layer:

TEXT
Hearth/Booking/ ├── Domain/ # entities │ ├── Reservation.php │ └── Reservations.php ├── Application/ # use cases │ ├── RequestReservationCommand.php │ └── RequestReservationCommandHandler.php ├── Infrastructure/ # adapters, frameworks │ └── EloquentReservations.php └── Http/ # adapters ├── RequestReservationController.php └── RequestReservationRequest.php

Hexagonal names each file's role and leaves the folders to you. Hearth keeps the use case's files together and puts the shared ones beside them:

TEXT
Hearth/Booking/ ├── RequestReservation/ │ ├── RequestReservationController.php # driving adapter │ ├── RequestReservationRequest.php │ ├── RequestReservationCommand.php # driving port │ └── RequestReservationCommandHandler.php # driving port ├── Reservation/ │ ├── Reservation.php │ └── Reservations.php # driven port └── Infrastructure/ └── EloquentReservations.php # driven adapter

Vertical Slice Architecture uses the same folders and treats each one as a unit: one use case, one folder.

TEXT
Hearth/Booking/ ├── RequestReservation/ # one use case │ ├── RequestReservationController.php # HTTP entry point │ ├── RequestReservationRequest.php # validation │ ├── RequestReservationCommand.php # input DTO │ └── RequestReservationCommandHandler.php # the use case ├── Reservation/ # shared │ ├── Reservation.php │ └── Reservations.php └── Infrastructure/ # shared └── EloquentReservations.php

The Hexagonal and Vertical Slice trees hold the same folders and differ only in their comments. The code is the same in all three trees, so the dependency rule is too.

What each is best at

Hexagonal. Best at: framework decoupling. The single rule (dependencies point inward, framework on the outside) is small enough to teach in one sitting. The pattern's economy is its strength: just enough structure to keep the framework from absorbing the domain.

Clean. Best at: making the use case visible. The screaming-architecture idea (your top-level folders should describe the product, not the framework) is one of the most applicable contributions to PHP work, even if you skip the rest of Clean. Domain-heavy products that need a strong entity-vs-use-case distinction benefit from the explicit layering.

Vertical Slice Architecture. Best at: cohesion. When everything related to a feature lives in one folder, every change has a smaller blast radius. Code review, deleting a feature and onboarding all get easier, and each slice maps to one command and its handler.

Where each one hurts

Hexagonal. The lightweight framing is also the missing one. Without explicit guidance on how to organize the inside of the application core, teams sometimes end up with a giant app/ folder containing everything from entities to use cases to domain services, with no internal structure. Vertical Slice Architecture is one good way to fill the gap.

Clean. The full ceremony costs. Input/output boundaries, request/response models, presenters, interactors, controllers, gateways. For a single use case, that's many types where one or two might have done. In my experience, cargo-culted Clean is a common architectural anti-pattern in PHP: a project with the full layered structure, none of the discipline, and a steep learning curve for new hires that doesn't pay back.

Vertical Slice Architecture. Cross-cutting concerns are awkward. Auditing, transactions, authorization, metrics, rate limiting, internationalization. They cut across slices. The pattern doesn't tell you where they go. Different teams answer differently (middleware, decorators, listeners, module-level services), and inconsistent answers across a codebase are noise.

Vertical Slice Architecture also makes "global consistency" harder to enforce. With horizontal layering, every controller is in one folder; you can audit them at a glance. With slices, every controller is in its own folder; consistency requires team discipline and tooling (PHPArkitect, Deptrac).

The honest hybrid

For a long-lived PHP product, the pragmatic answer is the one this course's codebase uses:

  • Vertical Slice Architecture for the structure. Each module is a folder; each use case is a slice within the module.

  • Hexagonal-flavored discipline inside slices. Commands, handlers, repositories behind ports, framework-free domain entities and value objects.

  • Clean's screaming-architecture principle for the top-level. The first level of folders describes the product (Booking/, Pricing/, Housekeeping/, GuestProfile/, Payments/), not the framework.

  • Clean's entity-vs-use-case distinction inside the module. A shared Reservation entity in its own Booking/Reservation/ folder; one folder per use case. Entities and use cases are different kinds of things, in different places.

  • Skip the strict Clean ceremony (input/output boundaries, interactors that return nothing and hand results to a presenter, request/response models). Use the command/handler shape instead. The handler returns a value where the caller needs one; the controller shapes the response.

A decision framework

Question

Yes

No

Is the project going to live for years?

Hexagonal-flavored discipline (ports, adapters, framework on the outside).

Plain Laravel patterns might be enough.

Does the team need fast tests?

Hexagonal/Clean dependency direction so the core can be tested without booting the framework.

Integration tests with the framework are probably fine.

Is there a rich domain with rules and edge cases?

Clean's entity-vs-use-case distinction helps. Vertical Slice Architecture gives the use cases a home.

A simpler structure works.

Are there many distinct features that don't share much?

Vertical Slice Architecture.

Horizontal layering might be cleaner.

Is the team large or growing?

Both Vertical Slice Architecture (for cohesion) and Hexagonal-flavored layering (for clear seams) help with coordination.

Less ceremony is fine.

Is the product still discovering itself?

Don't lock in an architecture. Use the framework's defaults; add structure as the domain reveals itself.

Pick a structure and apply it consistently.

If you answered yes to the first five and no to the last, the hybrid above fits.

The "we picked one and stuck with it" trap

Some teams adopt one architecture and apply it strictly to every line of code in the project. The result is consistent, which sounds good, and overbuilt for most of the project, which is bad.

The reality of any non-trivial codebase is that different parts of the system have different needs:

  • The reservation flow is genuinely complex; full Hexagonal-flavored discipline pays off.

  • The admin "view all guests" page is a thin query; a controller calling a repository directly is fine.

  • The "subscribe to newsletter" endpoint is one method; a Form Request, a controller, and a queued job is plenty.

A codebase where "view all guests" goes through an Interactor with Input Boundary, Request Model, Output Boundary, Response Model, Presenter, and Controller has paid the architecture's full cost for a feature that didn't need it.

The strictness of the architecture should match the complexity of the module. Keep one hybrid for the whole app and make the call on depth per module (Choosing a Style Per Module shows Housekeeping as a thin Active Record module beside a full Booking).

The "we mixed three and wandered" trap

The opposite mistake: a team reads about all three architectures, takes a little from each, and ends up with a codebase that has folder structures from Vertical Slice Architecture, layer rules from Clean, and ports from Hexagonal, but no overall coherence. Different parts follow different conventions. Some files are in app/Services/; others are in Hearth/Booking/CancelReservation/. Some controllers call services; others dispatch commands.

The fix is to pick a coherent hybrid and apply it consistently. The hybrid above is one such answer. Whatever your team picks, write it down, apply it in every module, and update it deliberately.

Practical recommendations

Concrete advice for picking an approach for your codebase:

For a new Laravel project starting today: Vertical Slice Architecture, internal command/handler structure, ports for repositories and external integrations, a plain PHP entity behind the repository port with an Eloquent adapter. Use the same hybrid from the first slice, and give each module only the depth it needs.

For a new Symfony project starting today: Same pattern. A Doctrine adapter instead of the Eloquent one. Most of the rest is identical.

For an existing Laravel project already in production: Don't refactor everything. Pick one new feature, write it as a slice with the full pattern, and use that as the seed. New features land in the slice format. Existing code stays as it is, and gets migrated when it's touched anyway. Migrating a Legacy PHP App Step by Step and The Strangler Fig Pattern cover this in detail.

For a tiny project: Plain Laravel is fine. Don't over-engineer.

The one thing to remember

For a long-lived PHP product I take Vertical Slice Architecture for organization, Hexagonal-flavored dependency rules for the inside of slices, and Clean's screaming-architecture top level. I skip the parts that don't earn their keep (the full Interactor ceremony) and apply the parts that do across the codebase, with the depth set per module.

Pick a coherent hybrid, document it, and give each module the depth it needs.

Course Content