Clean Architecture with Laravel

Uncle Bob's Clean Architecture is quite the hype right now in the architects' world. But when it comes to actual implementations, nothing notable has been proposed for Laravel.

And that's understandable: Laravel's MVC architecture and its tendency to let you cross layers all the time using Facades doesn't help designing clean, decoupled software parts.

So today, I'm going to present you a working implementation of the Clean Architecture principles inside a Laravel app, as explained in The Clean Architecture by Robert C. Martin.

The complete, working implementation of the concepts explained here is available on my GitHub repository. I recommend you have a look at the actual code while reading this article.

For once, let's get our hands clean 👍

It all started with a diagram

The architecture must support the use cases. [...] This is the first concern of the architect, and the first priority of the architecture.

(The Clean Architecture chapter 16, p148.)

If you've never heard of use cases, you can think of it as a feature, the capacity of a system to do something meaningful. UML let you describe them using the well-named Use Case Diagrams.

In CA, use-cases are at the heart of the application. They're the microchip that controls the machinery of your app.

So, how are we supposed to implement those use cases then?

Glad you asked! Here's a second diagram:

Let me explain briefly, and we'll dive into the actual code.

The pink line is the flow of control; it represents the order in which the different components are being executed. First, the user changes something on the view (for instance, he submits a registration form). This interaction becomes a Request object. The controller reads it and produces a RequestModel to be used by the UseCaseInteractor.

The UseCaseInteractor then does its thing (for instance, creates the new user), prepares a response in the form of a ResponseModel, and passes it to the Presenter. Which in turn updates the view through a ViewModel.

Wow, that's a lot 😵 That's probably the main criticism made to CA; it's lenghty!

The call hierarchy looks like this:

Controller(Request)
  ⤷ Interactor(RequestModel)
      ⤷ Presenter(ResponseModel)
          ⤷ ViewModel

What about the ports?

I can see you're quite the observer! For the low lever layers (the Use Cases and the Entities, often referred to as the Domain, and represented as the red and yellow circles in the schema above) to be decoupled from the high-level layers (the framework, represented as the blue circle), we need adapters (the green circle). Their job is to convey messages between high and low layers using their respective API and contracts (or interfaces).

Adapters are absolutely crucial in CA. They guarantee that changes in the framework won't require changes in the domain and vice-versa. In CA, we want our use cases to be abstracted from the framework (the actual implementation) so that both can change at will without propagating the changes on other layers.

A traditional PHP/HTML application designed with clean architecture can therefore be transformed into a REST API only by changing its controllers and presenters - the Use Cases would remain untouched! Or you could have both HTML + REST side by side using the same Use Cases. That's pretty neat if you ask me 🤩

To do that, we need to "force" the adapter to "behave" the way each layer needs it to behave. We're going to use interfaces to define inputs and output ports. They say, in essence, "if you want to talk to me, you're going to have to do it this way!"

Blah blah blah. I want to see some code!

Since the UseCaseInteractor will be at the heart of everything, let's start with this one:

class CreateUserInteractor implements CreateUserInputPort
{
    public function __construct(
        private CreateUserOutputPort $output,
        private UserRepository $repository,
        private UserFactory $factory,
    ) {
    }

    public function createUser(CreateUserRequestModel $request): ViewModel
    {
        /* @var UserEntity */
        $user = $this->factory->make([
            'name' => $request->getName(),
            'email' => $request->getEmail(),
        ]);

        if ($this->repository->exists($user)) {
            return $this->output->userAlreadyExists(
                new CreateUserResponseModel($user)
            );
        }

        try {
            $user = $this->repository->create(
                $user, new PasswordValueObject($request->getPassword())
            );
        } catch (\Exception $e) {
            return $this->output->unableToCreateUser(
                new CreateUserResponseModel($user), $e
            );
        }

        return $this->output->userCreated(
            new CreateUserResponseModel($user)
        );
    }
}

There are 3 things we need to pay attention to here:

• The interactor implements the CreateUserInputPort interface,
• The interactor depends on the CreateUserOutputPort,
• The interactor doesn't make the ViewModel himself, instead it tells the presenter to do it,

Since the Presenter (abstracted here by CreateUserOutputPort) is located in the adapters (green) layer, calling it from the CreateUserInteractor is indeed an excellent example of inversion of control: the framework isn't controlling the use cases, the use cases are controlling the framework.

If you find it too boringly complicated, forget all that and consider that all the meaningful decisions are being made at the use case level - including choosing the response path (userCreated, userAlreadyExists, or unableToCreateUSer). The controller and the presenters are just obedient slaves, devoid of business logic.

We can never rehearse it enough so sing it with me: CONTROLLERS 👏 SHOULD 👏 NOT 👏 CONTAIN 👏 BUSINESS 👏 LOGIC 👏

So how does it look from the controller's perspective?

For the controller, life is simple:

class CreateUserController extends Controller
{
    public function __construct(
        private CreateUserInputPort $interactor,
    ) {
    }

    public function __invoke(CreateUserRequest $request)
    {
        $viewModel = $this->interactor->createUser(
            new CreateUserRequestModel($request->validated())
        );

        return $viewModel->getResponse();
    }
}

You can see it relies on the CreateUserInputPort abstraction instead of the actual CreateUserInteractor implementation. It gives us the flexibility to change the use case at will and make the controller testable. More on that later.

Okay, that's very simple and stupid indeed. What about the presenter?

Again, very straightforward:

class CreateUserHttpPresenter implements CreateUserOutputPort
{
    public function userCreated(CreateUserResponseModel $model): ViewModel
    {
        return new HttpResponseViewModel(
            app('view')
                ->make('user.show')
                ->with(['user' => $model->getUser()])
        );
    }

    public function userAlreadyExists(CreateUserResponseModel $model): ViewModel
    {
        return new HttpResponseViewModel(
            app('redirect')
                ->route('user.create')
                ->withErrors(['create-user' => "User {$model->getUser()->getEmail()} alreay exists."])
        );
    }

    public function unableToCreateUser(CreateUserResponseModel $model, \Throwable $e): ViewModel
    {
        if (config('app.debug')) {
            // rethrow and let Laravel display the error
            throw $e;
        }

        return new HttpResponseViewModel(
            app('redirect')
                ->route('user.create')
                ->withErrors(['create-user' => "Error occured while creating user {$model->getUser()->getName()}"])
        );
    }
}

Traditionally, all that code would have been ifs at the controller's end. Which would have forced the use case to find a way to "tell" the controller what happened (using $user->wasRecentlyCreated or by throwing exceptions, for example.)

Using presenters controlled by the use case allows us to choose and change the outcomes without touching the controller. How great is that?

So everything relies on abstractions, I imagine the container is going get involved at some point?

You're absolutely right, my good friend! It pleases me to be in good company today.

Here's how to wire all that in app/Providers/AppServiceProvider.php:

class AppServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     *
     * @return void
     */
    public function register()
    {
        // wire the CreateUser use case to HTTP
        $this->app
            ->when(CreateUserController::class)
            ->needs(CreateUserInputPort::class)
            ->give(function ($app) {
                return $app->make(CreateUserInteractor::class, [
                    'output' => $app->make(CreateUserHttpPresenter::class),
                ]);
            });


        // wire the CreateUser use case to CLI
        $this->app
            ->when(CreateUserCommand::class)
            ->needs(CreateUserInputPort::class)
            ->give(function ($app) {
                return $app->make(CreateUserInteractor::class, [
                    'output' => $app->make(CreateUserCliPresenter::class),
                ]);
            });
    }
}

I added the CLI variant to demonstrate how easy it is to swap the presenter to make the use case return different ViewModel instances. Have a look a the actual implementation for more details 👍

Can I test this?

Oh my! It's begging you to! Another good thing about CA is that it relies so much on abstractions it makes testing a breeze.

class CreateUserUseCaseTest extends TestCase
{
    use ProvidesUsers;

    /**
     * @dataProvider userDataProvider
     */
    public function testInteractor(array $data)
    {
        (new CreateUserInteractor(
            $this->mockCreateUserPresenter($responseModel),
            $this->mockUserRepository(exists: false),
            $this->mockUserFactory($this->mockUserEntity($data)),
        ))->createUser(
            $this->mockRequestModel($data)
        );

        $this->assertUserMatches($data, $responseModel->getUser());
    }
}

The complete test class is available here.

I use Mockery for, well, mocking, but it will work with anything. It might seem like a lot of code, but it's actually quite simple to write, and it will give you 100% coverage of your use cases effortlessly.

Isn't this implementation slightly different from the book?

Yes, it is. You see CA has been designed by Java people. And, in most cases, in a Java program, if you want to update the view, you can do so directly from the Presenter.

But not in PHP. Because we don't fully control the view and because the frameworks are structured around the concept of controllers returning a response.

So I had to adapt the principles and make the ViewModel climb the call stack up to the controller to return a proper response. If you can come up with a better design, please let me know in the comments 🙏

---

Would you please let me know what you think in the comments? Your opinion matters to me, for I write those articles to challenge my vision and learn new things every day.

You are, of course, welcome to suggest changes to the demo repository by submitting a pull-request. Your contribution is much appreciated 🙏

This article took me four days of research, implementation, testing, and writing. I would really appreciate a like, a follow, and maybe a share on your social networks 🙏

Thanks, guys, you contribution helps to keep me motivated to write more articles for you 👍

---

Further reading:

• Clean Coder Blog
• Entity-Control-Boundary
• Clean Architecture: Use case containing the presenter or returning data?
• A button, as a “Clean Architecture” plugin
• UML Diagrams cheatsheet

Comments

[Mostafa Nazarband]

Good Article

[Amaury Franssen]

Thank you for this explanation, for those as me who are discovering software architecture and this new professional path, these articles are precious. I add this context to my others where I learn clean architecture : a nextJs project and a java project.

[Ali Bayat]

Great article, this is how the framework can be a detail, and nothing more.
although i wouldn't use magic methods that much, but everything looks pretty clean.

[Dg]

Thanks for the great article, one of the best implementations of clean arch that I saw...
I was wondering why you created a port for use cases in the controller, being that the controller is outside the use case layer, the same for entities that were called from the use cases through ports as well

[Valeriu Guțu]

I think many commenters don't see one of the most significant things described in “Clean Architecture”.
Why making Framework a detail is that important? And why would you need to make such complexity?
— Because it allows you to make more code testable, independent of framework, which allows you to securely update from one version to another. You can only see the benefits of this approach over time.

[riterangel]

Good morning, first I think your article is great since in my opinion it is one of the best I have found. I have a doubt about the use of key custom in the attributes of UserModelFactory->make since I have always had doubts about whether or not to use an array of data. My solution is the following and please could you give me your comment.

[Benjamin Delespierre]

Hi @riter_angel thanks for your comment.

In my opinion, there is nothing wrong with using array as DTOs as long as you're using Psalm or PHPStan to declare and check their structure. Here's an example projet that makes extensive use of PHPStan array declarations.

[Tiago Lopes]

Another issue that I find interesting is authentication and authorization, which is more pleasant, a simple if in the interactor or polymorphism of the interactor for each role of the system?

[Benjamin Delespierre]

Can you provide examples for these?

[Tiago Lopes]

Yes,
In a post creation case where the authenticated user can be a simple author or a moderator, where should publish permission be checked?

With a conditional in the interactor:

 <?php

 class CreatePostInteractor implements CreatePostInputPort
 {
       public function __construct(
          private CreatePostOutputPort $output,
          private PostRepository $repository,
          private PostFactory $factory,
          private IAM $iam
        ) {}

      public function createPost(CreatePostRequestModel $request): ViewModel
      {
          /* @var PostEntity */
          $post = $this->factory->make([
             'title' => $request->getTitle(),
             'body' => $request->getBody(),
             'published' => null
          ]);

         if ($this->iam->hasRole($request->getUserAuth(), 'moderator')) {
             $post->publish();
         }

         if ($this->repository->titleExists($request->getTitle())) {
             return $this->output->titleAlreadyExists(
                 new CreatePostResponseModel($post)
            );
        }

        try {
             $user = $this->repository->create($post);
        } catch (\Exception $e) {
             return $this->output->unableToCreatePost(
                 new CreatePostResponseModel($user), $e
             );
        }

         return $this->output->postCreated(
              new CreatePostResponseModel($user)
         );
     }
 }

With derivations for each type of user:

 <?php

 abstract class AbstractCreatePostInteractor
 {
       public function __construct(
           private CreatePostOutputPort $output,
           private PostRepository $repository,
           private PostFactory $factory
        ) { }

       abstract protected function makePost(CreatePostRequestModel $request): PostEntity;

       public function createPost(CreatePostRequestModel $request): ViewModel
       {
             /* @var PostEntity */
             $post = $this->makePost($request);

            if ($this->repository->titleExists($request->getTitle())) {
                 return $this->output->titleAlreadyExists(
                     new CreatePostResponseModel($post)
                 );
            }

            try {
                  $user = $this->repository->create($post);
            } catch (\Exception $e) {
                  return $this->output->unableToCreatePost(
                       new CreatePostResponseModel($user), $e
                  );
            }

            return $this->output->postCreated(
                  new CreatePostResponseModel($user)
            );
       }
  }

  class CreatePostInteractor extends AbstractCreatePostInteractor implements CreatePostInputPort
  {

        protected function makePost(CreatePostRequestModel $request): PostEntity
        {
              return $this->factory->make([
                 'title' => $request->getTitle(),
                 'body' => $request->getBody(),
                 'published' => null
         ]);
     }
  }

 class CreatePostInteractorAsModerator extends AbstractCreatePostInteractor implements CreatePostInputPort
 {

      protected function makePost(CreatePostRequestModel $request): PostEntity
      {
              return $this->factory->make([
                 'title' => $request->getTitle(),
                 'body' => $request->getBody(),
                 'published' => new \DateTimeImmutable()
      ]);
   }
}

[Benjamin Delespierre]

Both approaches could work just fine IMHO. The second one is better suited if the two roles have a lot of differences in their use-cases, justifying the existence of two distinct use-cases.

I also believe the keyword interactor should be a suffix of the class like CreatePostAsModeratorInteractor.

Also note that the interactor returning the entity directly is not a recommendation of the Clean Architecture as it will inevitably introduce coupling between the interactor and its callers.

[Tiago Lopes]

Congratulations for the post, my question is in the case of a REST API, the viewmodel would be needed? If not what would be the default return type for presenter methods?

[Benjamin Delespierre]

I believe in the case of REST API, the ViewModel would be a Laravel Resource wrapper:

class CreateUserJsonPresenter implements CreateUserOutputPort
{
    public function userCreated(CreateUserResponseModel $model): ViewModel
    {
        return new JsonResourceViewModel(
            new Resources\UserCreatedResource($model->getUser())
        );
    }

    public function userAlreadyExists(CreateUserResponseModel $model): ViewModel
    {
        return new JsonResourceViewModel(
            new Resources\UserAlreadyExistsResource($model->getUser())
        );
    }

    public function unableToCreateUser(CreateUserResponseModel $model, \Throwable $e): ViewModel
    {
        if (config('app.debug')) {
            // rethrow and let Laravel display the error
            throw $e;
        }

        return new JsonResourceViewModel(
            new Resources\UnableToCreateUserResource($e)
        );
    }
}

I'll update the reference project with examples for a REST API and write another article about it. Stay tune!

[Artur Wasilewski]

Hello,

wouldn't it be better if the interactor returned new CreateUserResponseModel($user)
and then controller, command, etc. could decide on the type of response? Those layers could also get injected with a proper object handling the response (Presenter). It looks a bit weird that InputPort "knows" about OutputPort.

[Benjamin Delespierre]

It can, but it wouldn't adhere to the specifications of this diagram:

With your proposal, the flow of control would return in the controller for it to make the decision on how to update the view, forcing you to change it when the use case changes.

In summary, you absolutely can, but it's no longer Clean Architecure, it's Laravel Actions.

I also don't believe it's weird to have the Interactor knowing the output port while implementing the input port since it should control both.

[Bernard Wiesner]

Seems like overengineering for 95% of the apps out there.

I find many oop and design patterns add a lot of complexity with little to no benefit.

I am a big believer in YAGNI (you are not going to need it). Only implement design patterns when you have an immediate need of it, not just in case you might need it later or cause you want to just follow some best practice.

A big reason Laravel got so successful is because it makes things easy to read and keeps things simple.

I would say if you are working on some vendor package, or you are working in a very big team where you don't have influence on other development teams, then these oop and design patterns can be quite handy.

[Benjamin Delespierre]

Thanks for your comment Bernard.

As I quote in the article

The architecture must support the use cases. [...] This is the first concern of the architect, and the first priority of the architecture.

If Laravel's native architecture can support your use cases, which is likely to be the case for small / mid size or early project, then yes, maybe you don't need Clean Architecture.

As the system's architect (apointed or de-facto) it is your responsibiliy to pick the best architecture you can given the project, its scope, its constraints, and its team.

If CA is overkill, then pick something simpler 👍 Just make sure you can migrate later as the project grows.