devjromero / laravel-ddd-example

Hexagonal Architecture + DDD + CQRS in PHP using Laravel 8

Hexagonal Architecture, DDD & CQRS in Laravel PHP

This is a monorepo containing a PHP application using Domain-Driven Design (DDD) and Command Query Responsibility Segregation (CQRS) principles. It also has a front in Vue.js and Nuxt.js.

It's a basic implementation of a Kanban manager (at this moment, just only manages Board entity; not columns or tasks)

Report a bug · Request a feature

Installation

Requirements

• Install Docker

Environment

• Clone this project: git clone https://github.com/mguinea/laravel-ddd-example laravel-ddd-example
• Move to the project folder: cd laravel-ddd-example
• Create a local environment file cp .env.dist .env

Execution

Install all the dependencies and bring up the project with Docker executing: make install

Then you'll have 2 apps available (1 API and 1 Frontend):

1. Kanban API: http://localhost:8180/api/v1/kanban/health-check
2. Kanban Frontend: TBD

Tests

Install the dependencies if you haven't done it previously: make composer-install

Execute all test suites: make tests

Monitoring

TODO

Project structure and explanation

Bounded contexts

Kanban: Place where the main functionality is implemented. Management of boards, columns, tasks...

Architecture and Structure

This repository follows the Hexagonal Architecture pattern. Also, it's structured using modules. With this, we can see that the current structure of a Bounded Context is:

$ tree -L 4 src

src
├── Kanban
│   ├── Board
│   │   ├── Application
│   │   │   ├── BoardResponse.php
│   │   │   ├── BoardsResponse.php
│   │   │   ├── Create
│   │   │   ├── Delete
│   │   │   ├── Get
│   │   │   ├── Search
│   │   │   └── Update
│   │   ├── Domain
│   │   │   ├── BoardAlreadyExists.php
│   │   │   ├── BoardId.php
│   │   │   ├── BoardName.php
│   │   │   ├── BoardNotFound.php
│   │   │   ├── Board.php
│   │   │   ├── BoardRepository.php
│   │   │   └── Boards.php
│   │   └── Infrastructure
│   │       ├── Laravel
│   │       └── Persistence
│   └── Shared
│       └── Infrastructure
│           └── Laravel
└── Shared
    ├── Domain
    │   ├── Aggregate
    │   │   └── AggregateRoot.php
    │   ├── Bus
    │   │   ├── Command
    │   │   ├── Event
    │   │   └── Query
    │   ├── CollectionInterface.php
    │   ├── Collection.php
    │   ├── Criteria
    │   │   ├── Criteria.php
    │   │   ├── FilterField.php
    │   │   ├── FilterOperator.php
    │   │   ├── Filter.php
    │   │   ├── Filters.php
    │   │   ├── FilterValue.php
    │   │   ├── OrderBy.php
    │   │   ├── Order.php
    │   │   └── OrderType.php
    │   ├── DomainException.php
    │   └── ValueObject
    │       ├── EnumValueObject.php
    │       ├── StringValueObject.php
    │       └── UuidValueObject.php
    └── Infrastructure
        ├── Bus
        │   └── Laravel
        ├── InfrastructureException.php
        └── Laravel
            └── SharedServiceProvider.php

Repositories

Repository pattern

Our repositories try to be as simple as possible usually only containing basic CRUD methods (delete, find, save and search). If we need some query with more filters we use the Specification pattern also known as Criteria pattern. So we add a search method.

CQRS

Laravel Job has been used to implement commands, queries and events.

My conventions

There are some opinionated resolutions / approaches in this project.

Generic methods (CRUDs)

get retrieve an entity. If not found, throw an exception.

find retrieve an entity. If not found, return null.

delete delete an entity. If not found, throw an exception.

create create an entity. If found, throw an exception.

update update an entity. If not found, throw an exception.

search retrieve a collection of entities by criteria. If nothing found, returns an empty collection.

listing retrieve a collection of entities with no criteria. If nothing found, returns an empty collection.