DEV Community: saad mouizina

[PHP] Understanding Ports & Adapters

saad mouizina — Sun, 29 Jun 2025 13:57:46 +0000

Ports and Adapters is a well-known and widely used design pattern — often without even realizing it. Foundational to maintainable and testable applications, this pattern separates the what (your core logic) from the how (external systems or tools). It’s commonly embedded in frameworks like Symfony and Laravel through features like dependency injection, contracts, and service containers.

In this article, we’ll focus specifically on the Ports and Adapters concept, without diving into full Hexagonal architecture.

What Are Ports & Adapters?

Ports are PHP interfaces that define the actions your application expects (inputs) or provides (outputs). Think of them as your contracts.

Adapters are concrete implementations of those interfaces. They allow communication with external systems: databases, APIs, file storage, queues, etc.

By depending on interfaces rather than implementations, your core application becomes easier to test, change, and extend. For instance:

You can mock external services in tests.
You can change how data is stored without touching business logic.
You can add new integrations just by writing a new adapter.

This is how frameworks like Laravel let you swap out mail drivers, queue backends, or filesystem disks with ease.

The Use Case: Configurable Data Importer

Let’s walk through a typical example to see Ports & Adapters in action: a system that imports user data from multiple sources (CSV, HTTP API) and stores them in multiple formats (MySQL, JSONL files).

We want to:

Add new sources/targets without modifying the core logic
Drive the behavior through config
Keep the application decoupled from external systems

Step 1: Define Contracts (Ports)

Let’s define our contracts :

interface ImportSourceInterface
{
    /** @return Collection<ImportDto> */
    public function fetch(): Collection;
}

interface ImportTargetInterface
{
    /** @param Collection<ImportDto> $records */
    public function store(Collection $records): void;
}

The ImportDto is a simple data carrier:

class ImportDto
{
    public function __construct(
        public readonly string $email,
        public readonly string $name,
    ) {}
}

Step 2: Create Adapters

namespace App\Adapters\Sources;

use App\Contracts\ImportSourceInterface;
use App\DTO\ImportDto;
use Illuminate\Support\Collection;

class CsvFileSource implements ImportSourceInterface
{
    public function __construct(private string $path) {}

    /**
     * @return Collection<ImportDto>
     */
    public function fetch(): Collection
    {
        $rows = collect();

        if (! file_exists($this->path)) {
            throw new \RuntimeException("CSV file not found at {$this->path}");
        }

        $handle = fopen($this->path, 'r');
        $headers = fgetcsv($handle);

        while ($line = fgetcsv($handle)) {
            $row = array_combine($headers, $line);
            $rows->push(new ImportDto(
                email: $row['email'] ?? '',
                name: $row['name'] ?? '',
            ));
        }

        fclose($handle);

        return $rows;
    }
}

<?php

namespace App\Adapters\Sources;

use App\Contracts\ImportSourceInterface;
use App\DTO\ImportDto;
use Illuminate\Support\Collection;
use Illuminate\Support\Facades\Http;

class HttpClientSource implements ImportSourceInterface
{
    public function __construct(private string $url, private ?string $token = null) {}

    /**
     * @return Collection<ImportDto>
     */
    public function fetch(): Collection
    {
        $response = Http::withToken($this->token)->get($this->url);

        if (! $response->successful()) {
            throw new \RuntimeException('Unable to fetch data from HTTP source.');
        }

        return collect($response->json())
            ->map(fn (array $item) => new ImportDto(
                email: $item['email'] ?? '',
                name: $item['name'] ?? '',
            ));
    }
}

<?php

namespace App\Adapters\Targets;

use App\Contracts\ImportTargetInterface;
use App\DTO\ImportDto;
use App\Models\ImportedUser;
use Illuminate\Support\Collection;

class EloquentStorage implements ImportTargetInterface
{
    public function store(Collection $records): void
    {
        $users = $records->map(function (ImportDto $record) {
            return [
                'email' => $record->email,
                'name' => $record->name,
            ];
        });

        ImportedUser::insert($users->toArray());
    }
}

<?php

namespace App\Adapters\Targets;

use App\Contracts\ImportTargetInterface;
use Illuminate\Support\Collection;

class FileStorage implements ImportTargetInterface
{
    public function __construct(
        private string $path,
    ) {}

    public function store(Collection $records): void
    {
        file_put_contents(
            filename: $this->path,
            data: json_encode($records)
        );
    }
}

Each adapter only cares about its specific task. They don’t know where they’re called from or why. That’s the job of our orchestration layer.

Step 3: Config-Driven Behavior:

We use a single port-adapters.php config file to list available sources, targets, and define the jobs.

<?php

return [
    // 👇 List of available sources
    'sources' => [
        'http_users' => [
            'class' => \App\Adapters\Sources\HttpClientSource::class,
            'arguments' => [
                'url' => env('USERS_API_URL'),
                'token' => env('USERS_API_TOKEN'),
            ],
        ],
        'local_csv' => [
            'class' => \App\Adapters\Sources\CsvFileSource::class,
            'arguments' => [
                'path' => storage_path('imports/users.csv'),
            ],
        ],
    ],

    // 👇 List of available targets
    'targets' => [
        'mysql' => [
            'class' => \App\Adapters\Targets\EloquentStorage::class,
            'arguments' => [],
        ],
        'file' => [
            'class' => \App\Adapters\Targets\FileStorage::class,
            'arguments' => [
                'path' => storage_path('imports/output/users.jsonl'),
            ],
        ],
    ],

    // 👇 Import job definitions (source ↔ target)
    'jobs' => [
        'users_from_http' => [
            'source' => 'http_users',
            'target' => 'file',
        ],
        'users_from_csv' => [
            'source' => 'local_csv',
            'target' => 'mysql',
        ],
    ],

];

This allows defining import jobs like users_from_http or users_from_csv dynamically.

Step 4: Job Runner Service

<?php

namespace App\Services;

use App\Contracts\ImportSourceInterface;
use App\Contracts\ImportTargetInterface;

class ImportJobRunner
{
    public function __construct(private string $jobName) {}

    public function run(): void
    {
        $job = config("import_jobs.{$this->jobName}");
        $sourceConfig = config("import_sources.{$job['source']}");
        $targetConfig = config("import_targets.{$job['target']}");

        $source = $this->makeAdapter($sourceConfig, ImportSourceInterface::class);
        $target = $this->makeAdapter($targetConfig, ImportTargetInterface::class);

        $target->store(
            $source->fetch()
        );

    }

    protected function makeAdapter(array $config, string $interface): object
    {
        $instance = app()->makeWith($config['class'], $config['arguments'] ?? []);

        if (! $instance instanceof $interface) {
            throw new \RuntimeException('Adapter does not implement required interface.');
        }

        return $instance;
    }
}

This is the heart of the system: given a job name, it dynamically resolves the correct adapters and runs the import.

Functional Tests

I wrote tests to cover each combination:

CSV -> MySQL
CSV -> File
HTTP -> MySQL
HTTP -> File

<?php

namespace Tests\Feature;

use App\Adapters\Sources\CsvFileSource;
use App\Adapters\Sources\HttpClientSource;
use App\Adapters\Targets\EloquentStorage;
use App\Adapters\Targets\FileStorage;
use App\Services\ImportJobRunner;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Facades\File;
use Illuminate\Support\Facades\Http;
use PHPUnit\Framework\Attributes\Test;
use Tests\TestCase;

class ImportJobRunnerTest extends TestCase
{
    use RefreshDatabase;

    #[Test]
    public function it_imports_from_csv_to_mysql(): void
    {
        config()->set('import_jobs.users_from_csv', [
            'source' => 'csv_users',
            'target' => 'mysql',
        ]);

        config()->set('import_sources.csv_users', [
            'class' => CsvFileSource::class,
            'arguments' => [
                'path' => storage_path('imports/users.csv'),
            ],
        ]);

        config()->set('import_targets.mysql', [
            'class' => EloquentStorage::class,
            'arguments' => [],
        ]);

        (new ImportJobRunner('users_from_csv'))->run();

        $this->assertDatabaseCount('imported_users', 4);
        $this->assertDatabaseHas('imported_users', ['email' => 'alice@example.com']);
        $this->assertDatabaseHas('imported_users', ['email' => 'bob@example.com']);
        $this->assertDatabaseHas('imported_users', ['email' => 'carla@example.com']);
        $this->assertDatabaseHas('imported_users', ['email' => 'mohamed@example.com']);

    }

    #[Test]
    public function it_imports_from_csv_to_file(): void
    {
        config()->set('import_jobs.csv_to_file', [
            'source' => 'csv_users',
            'target' => 'file',
        ]);

        config()->set('import_sources.csv_users', [
            'class' => CsvFileSource::class,
            'arguments' => [
                'path' => storage_path('imports/users.csv'),
            ],
        ]);

        config()->set('import_targets.file', [
            'class' => FileStorage::class,
            'arguments' => [
                'path' => storage_path('imports/users.jsonl'),
            ],
        ]);

        (new ImportJobRunner('csv_to_file'))->run();

        $this->assertFileExists(storage_path('imports/users.jsonl'));
        $content = File::get(storage_path('imports/users.jsonl'));

        $this->assertStringContainsString('mohamed@example.com', $content);
        $this->assertCount(4, json_decode($content, true));
    }

    #[Test]
    public function it_imports_from_http_to_mysql(): void
    {
        Http::fake([
            '*' => Http::response([
                ['email' => 'foo@example.com', 'name' => 'Foo'],
                ['email' => 'bar@example.com', 'name' => 'Bar'],
            ]),
        ]);

        config()->set('import_jobs.http_to_mysql', [
            'source' => 'http_users',
            'target' => 'mysql',
        ]);

        config()->set('import_sources.http_users', [
            'class' => HttpClientSource::class,
            'arguments' => [
                'url' => 'https://dummy.test/api/users',
                'token' => 'dummy_token',
            ],
        ]);

        config()->set('import_targets.mysql', [
            'class' => EloquentStorage::class,
            'arguments' => [],
        ]);

        (new ImportJobRunner('http_to_mysql'))->run();

        $this->assertDatabaseCount('imported_users', 2);
        $this->assertDatabaseHas('imported_users', ['email' => 'foo@example.com']);
        $this->assertDatabaseHas('imported_users', ['email' => 'bar@example.com']);
    }

    #[Test]
    public function it_imports_from_http_to_file(): void
    {
        Http::fake([
            '*' => Http::response([
                ['email' => 'zara@example.com', 'name' => 'Zara'],
            ]),
        ]);

        config()->set('import_jobs.http_to_file', [
            'source' => 'http_users',
            'target' => 'file',
        ]);

        config()->set('import_sources.http_users', [
            'class' => HttpClientSource::class,
            'arguments' => [
                'url' => 'https://dummy.test/api/users',
                'token' => 'dummy_token',
            ],
        ]);

        config()->set('import_targets.file', [
            'class' => FileStorage::class,
            'arguments' => [
                'path' => storage_path('imports/users.jsonl'),
            ],
        ]);

        (new ImportJobRunner('http_to_file'))->run();

        $this->assertFileExists(storage_path('imports/users.jsonl'));
        $this->assertStringContainsString('zara@example.com', File::get(storage_path('imports/users.jsonl')));
    }

    #[Test]
    public function it_throws_if_adapter_does_not_implement_interface(): void
    {
        config()->set('import_jobs.invalid_adapter', [
            'source' => 'invalid_source',
            'target' => 'mysql',
        ]);

        config()->set('import_sources.invalid_source', [
            'class' => \stdClass::class, // Ne respecte pas ImportSourceInterface
            'arguments' => [],
        ]);

        $this->expectException(\RuntimeException::class);
        $this->expectExceptionMessage('Adapter does not implement required interface');

        (new ImportJobRunner('invalid_adapter'))->run();
    }
}

These tests:

Ensure the correct integration between source & target
Test that the contracts are respected
Prove that the system can adapt dynamically to config changes

Conclusion

Ports & Adapters isn’t just a theory — it’s a powerful way to write maintainable code.

Your business logic doesn’t know how data is fetched or stored.
Your adapters don’t know why they’re used — just how.
Your application becomes easier to test and evolve.

Github repository : https://github.com/mouize/demo-ports-adapter

CQRS with Laravel: What It Is, When to Use It, and How I Implemented It

saad mouizina — Mon, 28 Apr 2025 11:16:43 +0000

As business logic becomes more complex, I’ve often found myself dealing with bloated services, classes that do too much, and tests that are hard to maintain. That’s when I started applying the CQRS pattern (Command Query Responsibility Segregation) in my Laravel projects, and honestly, it’s been a game changer.

In this article, I’ll explain what CQRS is, when it makes sense to use it (and when not), how to implement it in Laravel, and walk you through a concrete use case: generating a monthly invoice.

What is CQRS?

CQRS is an architectural pattern that separates commands aka operations that change the system’s statefrom queries , which only read data.

Why bother separating them?

It reflects business intent more clearly in code
It makes unit testing much easier
It keeps classes small and focused
In some cases, it improves performance by optimizing read and write paths separately

This is more than just using different methods: we create separate classes for each action, typically organized under Commands/ and Queries/, each with its own handler.

Setting up CQRS in Laravel

To keep things clean and easy to find, I usually organize commands and queries under a CQRS folder. Here's a typical folder structure:

app/
├── CQRS/
│ ├── Commands/
│ │ ├── GenerateMonthlyInvoiceCommand.php
│ │ └── GenerateMonthlyInvoiceHandler.php
│ └── Queries/
│ ├── GetInvoiceBreakdownQuery.php
│ └── GetInvoiceBreakdownHandler.php

This separation makes it very easy to reason about your application’s use cases at a glance.

A simple Command Bus for CQRS

To implement CQRS properly in Laravel, you’ll use a command bus that takes care of automatically finding the right handler for any command or query based on a simple naming convention :

Command ➔ CommandHandler,
Query ➔ QueryHandler).

Here’s a simple version:

namespace App\Services;

use Illuminate\Pipeline\Pipeline;

class CommandBus
{
    public function __construct(
        protected array $middlewares = []
    ) {}

    public function dispatch(object $command): mixed
    {
        $handler = $this->resolveHandler($command);

        return app(Pipeline::class)
            ->send($command)
            ->through($this->middlewares)
            ->then(fn ($command) => $handler->handle($command));
    }

    protected function resolveHandler(object $command): object
    {
        $handlerClass = get_class($command) . 'Handler';

        if (!class_exists($handlerClass)) {
            throw new \RuntimeException("Handler [{$handlerClass}] not found for command " . get_class($command));
        }

        return app($handlerClass);
    }
}

It also gives the flexibility to add middlewares around the execution, for example to log, trace, or validate commands before they are actually handled. If you want to use middlewares like logging or tracing:

namespace App\Services\Middlewares;

use Closure;

class LogCommandExecution
{
    public function handle(object $command, Closure $next)
    {
        logger()->info('Executing command: ' . get_class($command));

        return $next($command);
    }
}

Then, just register it in your service provider:

use App\Services\CommandBus;

public function register()
{
    $this->app->singleton(CommandBus::class, function () {
        return new CommandBus([
            // List your middlewares here if needed
            \App\Services\Middlewares\LogCommandExecution::class,
        ]);
    });
}

Common structure

For writes :

Command: holds the input data
CommandHandler: contains the business logic

For reads :

Query: describes the data you want
QueryHandler: handles the logic and returns a DTO or array

Naming your commands and queries

Naming matters. In CQRS, your class names should reflect a business intent , not a technical action.

Prefer explicit, intention-revealing names:

GenerateMonthlyInvoiceCommand
AssignRoleToUserCommand
GetInvoiceBreakdownQuery

Avoid generic names like InvoiceService, Handler, DoStuff, etc.

Ideally, a non-technical stakeholder should be able to understand what a command does just by reading its name.

When should you use CQRS?

ou don’t need CQRS everywhere. For simple CRUD, it’s probably overkill. But it becomes very useful when:

You have rich business rules (state checks, validations, calculations)
You need to aggregate data before writing
You want to structure your code around business use cases
You’re building modular or DDD-style architectures

Real-world example: generating a monthly invoice

Let’s take a more realistic example than the usual “create a blog post”: generating a monthly invoice.

The context

At the end of each month, the system must generate an invoice for a customer based on multiple data sources (subscriptions, one-time services, product usage…). Before saving the invoice, it needs to:

Retrieve all usage records for the month
Calculate the subtotal, taxes, and possible discounts
Build invoice line items
Save everything to the database

The command : GenerateMonthlyInvoiceCommand

class GenerateMonthlyInvoiceCommand
{
    public function __construct(
        public readonly int $customerId,
        public readonly DateTimeInterface $month
    ) {}
}

The handler :

class GenerateMonthlyInvoiceHandler
{
    public function __construct(
        private ConsumptionRepository $consumptions,
        private InvoiceRepository $invoices,
        private TaxService $taxService,
        private DiscountService $discountService,
    ) {}

    public function handle(GenerateMonthlyInvoiceCommand $command): void
    {
        $items = $this->consumptions->forCustomerAndMonth($command->customerId, $command->month);

        if ($items->isEmpty()) {
            throw new DomainException('No usage to invoice.');
        }

        $subtotal = $items->sum(fn($item) => $item->price);
        $taxes = $this->taxService->compute($command->customerId, $subtotal);
        $discount = $this->discountService->apply($command->customerId, $items);
        $total = $subtotal + $taxes - $discount;

        $invoice = new Invoice(
            customerId: $command->customerId,
            month: $command->month,
            subtotal: $subtotal,
            taxes: $taxes,
            discount: $discount,
            total: $total
        );

        $invoice->addLinesFromConsumption($items);
        $this->invoices->save($invoice);
    }
}

*The query * : GetInvoiceBreakdownQuery

class GetInvoiceBreakdownQuery
{
    public function __construct(
        public readonly int $customerId,
        public readonly DateTimeInterface $month
    ) {}
}

The handler :

class GetInvoiceBreakdownHandler
{
    public function __construct(private InvoiceRepository $invoices) {}

    public function handle(GetInvoiceBreakdownQuery $query): InvoiceDTO
    {
        $invoice = $this->invoices->findByCustomerAndMonth($query->customerId, $query->month);
        return new InvoiceDTO($invoice);
    }
}

Benefits I noticed in my project

Clarity : command and query names clearly describe business actions
Isolation : each handler is easy to test independently
Organization : fits perfectly in a modular architecture
Scalability : you can easily plug in validation, logging, or events without bloating your controllers

Testing handlers

CQRS makes unit testing much simpler: each command or query is an isolated unit that you can test without going through a controller or infrastructure.

Here’s a typical test for a command handler:

test('it generates an invoice with correct totals') {
    $consumptions = collect([
        new ConsumptionItem(price: 100),
        new ConsumptionItem(price: 200),
    ]);

    $handler = new GenerateMonthlyInvoiceHandler(
        new InMemoryConsumptionRepository($consumptions),
        new FakeInvoiceRepository(),
        new FixedTaxService(20),
        new FixedDiscountService(30)
    );

    $handler->handle(new GenerateMonthlyInvoiceCommand(1, now()));

    expect(FakeInvoiceRepository::$savedInvoice)->not->toBeNull();
    expect(FakeInvoiceRepository::$savedInvoice->total)->toBe(290); // 300 + 20 - 30
}

Conclusion

CQRS is a great tool to help structure your code when business logic starts getting more complex (would fit perfectly in this use case). It makes your intentions explicit, your responsibilities more focused, and your code easier to test.

You don’t need it everywhere, but when your services start feeling heavy or messy, consider giving it a try. Personally, I wouldn’t go back on larger projects.

Bonus: CQRS vs CQS

People often confuse CQRS with CQS.

CQS (Command Query Separation) is a design principle : a method should either modify state (command) or return data (query). NEVER both.
CQRS (Command Query Responsibility Segregation) takes this principle further by applying it at the application level : separating models, services, and logic for reads and writes.

So:

A CQRS command can contain some reads (e.g., find a customer before modifying it)
A CQS method must do only one thing: read or write, not both

CQRS is structural; CQS is behavioral.

Modular Architecture with Laravel

saad mouizina — Sat, 12 Apr 2025 14:43:08 +0000

Taming Laravel Monoliths with Modular Architecture

As Laravel projects grow, maintaining a clean structure becomes increasingly difficult. Controllers pile up, models get bloated, and domain logic starts to leak across unrelated parts of the application. You quickly end up with a monolith that’s hard to scale or reason about.

That’s where modular architecture comes in.

Why modular architecture?

The core idea is to break your application into feature-specific modules , each responsible for its own domain logic — authentication, blog, billing, etc. Each module contains its own models, controllers, routes, validation, services, and more.

This approach offers several key benefits:

Separation of concerns — every module owns its logic
Improved maintainability — easier to test, extend, or replace parts of the app
Better scalability — especially with larger teams or growing business domains

Modular architecture is particularly useful in mid-to-large-scale applications, where clear functional boundaries exist across features.

What we’ll build

In this tutorial, I’ll walk you through how to implement a clean modular structure in Laravel using the excellent nwidart/laravel-modules package.

We’ll build two core modules:

Authentication — handling registration, login, email verification, logout, etc.
Blog — a feature module containing User, Post, and Comment models, with full REST APIs

Along the way, we’ll cover:

How to keep modules decoupled but still communicate cleanly
to centralize authentication logic in the main app
How to secure all routes from the main app while allowing modules to expose their logic
How to structure repositories, requests, events, and resources in a scalable and maintainable way

For the business logic and API structure, I’ll build on top of what I introduced in this previous article, adapting it to a modular architecture — so it might be worth giving it a quick read first.

Getting Started: Project Setup and Docker Configuration

Before jumping into modularization, we need a solid Laravel base to work on — ideally with Docker so everything is isolated and reproducible across environments.

If you’re not familiar with Docker or want a ready-to-go setup for Laravel, I recommend checking out this article:

👉 Getting Started with Laravel Projects Using Docker — My Basic Configuration

It walks through a minimal and efficient Docker setup using:

PHP-FPM container
Nginx for web server
MySQL/MariaDB for database
Mailhog for local email testing
and volume bindings to keep everything in sync

Once your Docker environment is up and Laravel is running (you can use the make laravel-install) in the container, we can move to the modular part of the project.

I’ve made the full implementation of this tutorial available here: https://github.com/mouize/demo-modular-architecture

1. Install the nwidart/laravel-modules package

We’ll use the excellent nwidart/laravel-modules package to structure our app into independent feature modules.

Install it via Composer:

composer require nwidart/laravel-modules

Then publish the config file:

php artisan vendor:publish --provider="Nwidart\Modules\LaravelModulesServiceProvider"

To ensure Composer can autoload our modules, update your composer.json with:

"autoload": {
    "psr-4": {
        "Modules\\": "Modules/"
    }
},
"extra": {
    "merge-plugin": {
        "include": [
            "Modules/*/composer.json"
        ]
    }
}

And run:

composer dump-autoload

You can also customize how modules are generated by editing config/modules.php — for example, under the generator section, you can define which folders or files should be created by default for each module.

2. Setting up the Authentication Module

The first feature we’re going to modularize is authentication — one of the most critical and commonly reused parts of any application.

We’ll use Laravel Sanctum for token-based authentication, and organize the entire auth logic (registration, login, logout, email verification) inside a dedicated Authentication module.

But before diving into code, let’s understand the reasoning behind it.

Why isolate authentication into a module?

Authentication often touches a lot of parts in an app (user creation, email verification, session/token management, etc.), so it makes sense to extract it into its own self-contained domain.

By doing this:

We reduce coupling between authentication logic and the rest of the app
We can reuse or replace the module easily in other Laravel projects
We keep things organized and scalable — one module, one responsibility

Create the authentication module

php artisan module:make Authentication

This scaffolds a fully isolated folder structure under Modules/Authentication, including space for models, controllers, routes, requests, events, etc.

Create the AuthController

namespace Modules\Authentication\Http\Controllers;

use App\Http\Controllers\Controller;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Hash;
use Illuminate\Support\Facades\Event;
use Modules\Authentication\Http\Requests\RegisterRequest;
use Modules\Authentication\Http\Requests\LoginRequest;
use Modules\Authentication\Contracts\UserRepositoryInterface;
use Modules\Authentication\Events\UserRegistered;
use Modules\Authentication\Events\UserVerified;

class AuthController extends Controller
{
    public function __construct(protected UserRepositoryInterface $userRepository) {}

    public function register(RegisterRequest $request): JsonResponse
    {
        $user = $this->userRepository->register([
            'name' => $request->validated('name'),
            'email' => $request->validated('email'),
            'password' => Hash::make($request->validated('password'),
        ]);

        Event::dispatch(new UserRegistered($user));

        return response()->json([
            'message' => 'Account created successfully. Please check your email to verify your account.',
        ], 201);
    }

    public function verify(Request $request): JsonResponse
    {
        $user = $this->userRepository->findOrFail($request->route('id'));

        if (! hash_equals((string) $request->route('hash'), sha1($user->getEmail()))) {
            return response()->json(['message' => 'Invalid verification link'], 400);
        }

        Event::dispatch(new UserVerified($user));

        return response()->json(['message' => 'Email verified successfully']);
    }

    public function login(LoginRequest $request): JsonResponse
    {
        $user = $this->userRepository->getUserByEmail($request->validated('email'));

        if (! $user || ! Hash::check($request->validated('password'), $user->getPassword())) {
            return response()->json(['message' => 'Invalid credentials'], 401);
        }

        $token = $user->createToken('auth_token');

        return response()->json([
            'access_token' => $token->plainTextToken,
            'token_type' => 'Bearer',
        ]);
    }

    public function logout(Request $request): JsonResponse
    {
        $request->user()->tokens()->delete();

        return response()->json(['message' => 'Successfully logged out']);
    }
}

Add FormRequest validation

To keep our controller clean and follow Laravel best practices, we use FormRequest classes to validate the inputs.

php artisan module:make-request RegisterRequest Authentication
php artisan module:make-request LoginRequest Authentication

Then define rules in each request:

//Modules/Authentication/Http/Requests/RegisterRequest.php
public function rules(): array
{
    return [
        'name' => ['required', 'string'],
        'email' => ['required', 'email', 'unique:users,email'],
        'password' => ['required', 'min:8'],
    ];
}

//Modules/Authentication/Http/Requests/LoginRequest.php
public function rules(): array
{
    return [
        'email' => ['required', 'email'],
        'password' => ['required'],
    ];
}

Define contracts to decouple logic

To keep our module independent from the actual User implementation, we rely on interfaces.

This allows the main application to define how users are created, authenticated, and managed — while the module simply expects any class that fulfills the contract.

Create two interfaces inside your module:

php artisan module:make-interface UserInterface Authentication
php artisan module:make-interface UserRepositoryInterface Authentication

namespace Modules\Authentication\Contracts;

interface UserInterface
{
    public function getId(): int;
    public function getEmail(): string;
    public function getPassword(): string;
    public function createToken(string $name);
}

namespace Modules\Authentication\Contracts;

interface UserRepositoryInterface
{
    public function register(array $data): UserInterface;
    public function getUserByEmail(string $email): ?UserInterface;
    public function findOrFail(int $id): UserInterface;
}

Use events to externalize side-effects

Instead of triggering things like email notifications or verification logic directly inside the controller, we use events to handle side effects.

This gives us:

Clear separation of responsibilities
Flexibility to change what happens after registration without touching the controller

php artisan module:make-event UserRegistered Authentication
php artisan module:make-event UserVerified Authentication

Define them like so:

namespace Modules\Authentication\Events;

use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;
use Modules\Authentication\Interfaces\UserInterface;

class UserRegistered
{
    use Dispatchable, SerializesModels;

    /**
     * Create a new event instance.
     */
    public function __construct(public UserInterface $user) {}
}

use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;
use Modules\Authentication\Interfaces\UserInterface;

class UserVerified
{
    use Dispatchable, SerializesModels;

    /**
     * Create a new event instance.
     */
    public function __construct(public UserInterface $user) {}
}

3. Creating the Blog Module

Now that our authentication module is in place, let’s move on to building a second module — the Blog module.

This will represent a real business feature and give us the opportunity to organize models, resources, relationships, validation, and repositories in a modular way.

php artisan module:make Blog

Let’s generate our User, Post, and Comment models using the built-in Nwidart generator:

php artisan module:make-model User Blog -frRc
php artisan module:make-model Post Blog -frRc
php artisan module:make-model Comment Blog -frRc

We can now define for each model the relationships and fillable attributes inside each one.

The -frRc flags we used when generating the models gave us a solid base: eloquent resources, form requests, and RESTful controllers were all scaffolded automatically.

Now we just need to fill in the logic to bring it all together.

Migrations

Create the corresponding migrations in a folder stubs/migrations as shown here. (will be discussed deeply in a next section)

Using Spatie Query Builder for Clean & Flexible Queries

To keep our controllers clean and make our API flexible for consumers, we use Spatie Query Builder.

It allows us to build powerful filters, includes, and sorts with zero extra logic in the controller. All of that is handled inside the repository layer.

composer require spatie/laravel-query-builder

Each module has its own composer.json, so we also need to add the package there:

#Modules/Blog/composer.json
"require": {
    "spatie/laravel-query-builder": "*" //You can set a specific version depending on your needs
}

Then, regenerate the autoloader:

composer dump-autoload

Repositories: Centralizing Data Access

We can generate our repositories now:

php artisan module:make-repository UserRepository Blog
php artisan module:make-repository PostRepository Blog
php artisan module:make-repository CommentRepository Blog

Let’s complete them to encapsulate all the logic for querying and persisting data.

Http logics

RESTful controllers, form requests, eloquent resources were also scaffolded, let’s plug them into the repositories and handle basic CRUD operations as shown here.

4. Publishing Module Routes & Migrations

By design, modules should stay generic and reusable. That’s why we avoid hardcoding things like route prefixes or middleware inside the module.

Instead, we let the main application decide :

how to group or secure the routes
how to customize the migration structure if needed

To achieve that, we make our routes and migrations publishable.

Making routes publishable

In both the Authentication and Blog modules, define routes in a simple way — no middleware, no prefix:

//Modules/Authentication/Routes/api.php
use Illuminate\Support\Facades\Route;
use Modules\Authentication\Http\Controllers\AuthController;

Route::post('register', [AuthController::class, 'register']);
Route::post('login', [AuthController::class, 'login']);
Route::post('logout', [AuthController::class, 'logout']);
Route::get('verify/{id}/{hash}', [AuthController::class, 'verify']);

//Modules/Blog/Routes/api.php
use Illuminate\Support\Facades\Route;
use Modules\Blog\Http\Controllers\UserController;
use Modules\Blog\Http\Controllers\PostController;
use Modules\Blog\Http\Controllers\CommentController;

Route::apiResource('users', UserController::class);
Route::apiResource('posts', PostController::class);
Route::apiResource('comments', CommentController::class);

By avoiding hardcoded route groups, modules stay clean and composable — the main app is free to apply auth, prefixes, or rate limiting globally.

Then in your module service provider, add:

//Modules/Authentication/app/Providers/AuthenticationServiceProvider
$this->publishes([
    __DIR__.'/../../routes/api.php' => base_path('routes/modules/Authentication/api.php'),
], 'authentication-routes');

//Modules/Blog/app/Providers/BlogServiceProvider
$this->publishes([
    __DIR__.'/../../routes/api.php' => base_path('routes/modules/Blog/api.php'),
], 'blog-routes');

From the main app, you can now publish and control the routes:

php artisan vendor:publish --tag=authentication-routes
php artisan vendor:publish --tag=blog-routes

You’ll get fully editable copies under routes/modules/Blog/api.php and routes/modules/Authentication/api.php.

Once published, the app can load these routes with proper middleware and prefixing.

(We’ll see that in the next section.)

Making migrations publishable

Same idea for migrations. If the app needs to add extra columns or adapt table structures, it can override the module’s migrations.

In the same service providers:

//Modules/Authentication/app/Providers/AuthenticationServiceProvider
$this->publishes([
    __DIR__.'/../../stubs/migrations' => database_path('migrations'),
], 'authentication-migrations');

//Modules/Blog/app/Providers/BlogServiceProvider
$this->publishes([
    __DIR__.'/../../stubs/migrations' => database_path('migrations'),
], 'blog-migrations');

Important: We moved the migrations to the stubs/migrations folder to prevent them from being executed during a migrate command unless they are explicitly published first.

Then publish them with:

php artisan vendor:publish --tag=authentication-migrations
php artisan vendor:publish --tag=blog-migrations

You’ll get fully editable copies under database/migrations

5. Orchester Modules from the Main Application

Now that our modules are structured and publish their routes and migrations, the main application becomes the central orchestrator. It will:

Connect the app’s User model to the Authentication module
Implement the UserRepositoryInterface and UserInterface
Secure and load the module routes dynamically
Listen to events (like UserRegistered) and decide how to react

Create the main User model

This model lives in the app and extends the User model from the Blog module:

namespace App\Models;

use App\Mail\CustomVerifyEmail;
use Illuminate\Auth\Authenticatable;
use Illuminate\Auth\MustVerifyEmail;
use Illuminate\Contracts\Auth\Authenticatable as AuthenticatableContract;
use Laravel\Sanctum\HasApiTokens;
use Illuminate\Notifications\Notifiable;
use Modules\Authentication\Interfaces\UserInterface;
use Modules\Blog\Models\User as BlogUser;

class User extends BlogUser implements UserInterface, AuthenticatableContract
{
    use HasApiTokens, Notifiable, Authenticatable, MustVerifyEmail;

    protected $fillable = ['name', 'email', 'password'];

    public function getId(): int
    {
        return $this->id;
    }

    public function getEmail(): string
    {
        return $this->email;
    }

    public function getPassword(): string
    {
        return $this->password;
    }

    public function sendEmailVerificationNotification(): void
    {
        $this->notify(new CustomVerifyEmail);
    }
}

This model handles authentication and implements the interface expected by the Authentication module.

Configure Laravel to use this User model

In config/auth.php:

'providers' => [
    'users' => [
        'driver' => 'eloquent',
        'model' => App\Models\User::class,
    ],
],

Implement the UserRepository

namespace App\Repository;

use App\Models\User;
use Modules\Authentication\Interfaces\UserInterface;
use Modules\Authentication\Interfaces\UserRepositoryInterface;
use Modules\Blog\Repositories\UserRepository as BlogUserRepository;

class UserRepository extends BlogUserRepository implements UserRepositoryInterface
{
    protected string $model = User::class;

    public function register(array $data): UserInterface
    {
        return $this->model::create($data);
    }

    public function getUserByEmail(string $email): ?UserInterface
    {
        return $this->model::where('email', $email)->first();
    }

    public function findOrFail(int $id): UserInterface
    {
        return $this->model::findOrFail($id);
    }
}

Then bind the interface in your AppServiceProvider:

use Modules\Authentication\Contracts\UserRepositoryInterface;
use App\Repositories\UserRepository;

public function register()
{
    $this->app->bind(UserRepositoryInterface::class, UserRepository::class);
}

Listen to events

Create listeners for the events dispatched in the Authentication module.

namespace App\Listeners;

use Modules\Authentication\Events\UserRegistered;

class SendEmailVerificationNotification
{
    public function handle(UserRegistered $event): void
    {
        $event->user->sendEmailVerificationNotification();
    }
}

namespace App\Listeners;

use Modules\Authentication\Events\UserVerified;

class MarkEmailAsVerified
{
    public function handle(UserVerified $event): void
    {
        $event->user->markEmailAsVerified();
    }
}

use Modules\Authentication\Events\UserRegistered;
use Modules\Authentication\Events\UserVerified;

protected $listen = [
    UserRegistered::class => [
        \App\Listeners\SendEmailVerificationNotification::class,
    ],
    UserVerified::class => [
        \App\Listeners\MarkEmailAsVerified::class,
    ],
];

Secure routes

Create a new service provider like ModuleRouteServiceProvider:

namespace App\Providers;

use Illuminate\Support\Facades\Route;
use Illuminate\Support\ServiceProvider;
use Nwidart\Modules\Facades\Module;

class ModuleRouteServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        foreach (Module::allEnabled() as $module) {
            $name = $module->getName();
            $path = base_path("routes/modules/{$name}/api.php");

            if (file_exists($path)) {
                Route::prefix('api')
                    ->name('api.')
                    ->group($path);
            }
        }
    }
}

If needed, declare this new ServiceProvider in bootstrap/providers

Once the module routes are published (e.g. routes/modules/Blog/api.php), the main app can customize them freely — including applying authentication middleware.

For example, in the Blog module:

use Illuminate\Support\Facades\Route;
use Modules\Blog\Http\Controllers\PostController;
use Modules\Blog\Http\Controllers\UserController;
use Modules\Blog\Http\Controllers\CommentController;

Route::middleware('auth:sanctum')->group(function () {
    Route::apiResource('users', UserController::class);
    Route::apiResource('posts', PostController::class);
    Route::apiResource('comments', CommentController::class);
});

And for the Authentication module:

use Illuminate\Support\Facades\Route;
use Modules\Authentication\Http\Controllers\AuthController;

Route::post('register', [AuthenticationController::class, 'register'])
    ->name('register');
Route::post('login', [AuthenticationController::class, 'login'])
    ->name('login');
Route::middleware('signed')
    ->get('/email/verify/{id}/{hash}', [AuthenticationController::class, 'verify'])
    ->name('verification.verify');

This gives you maximum control over each module’s security behavior, without needing to maintain a custom route loader.

Your app now orchestrates everything:

It owns the User logic
Secures and loads module routes dynamically
Handles auth-specific events
Keeps the modules decoupled and reusable

And Voilà

Modular architecture brings clarity, separation of concerns, and long-term maintainability to Laravel projects — especially when things start to grow.

By leveraging nwidart/laravel-modules, we’ve been able to:

Split our application into clearly defined domains
Keep modules independent and reusable
Centralize responsibilities like authentication, route security, and event handling in the main app
Maintain clean API logic using repositories, resources, FormRequests, and Spatie Query Builder

This structure is particularly useful in real-world teams, where different developers work on different parts of the system, or where features evolve independently over time.

Bonus: What about Domain-Driven Design (DDD)?

Modular architecture is often confused with DDD — and while the two can overlap, they’re not the same.

Modular architecture is about technical organization : splitting your code by feature to make it more maintainable.
DDD is about business modeling : building your code around the language and rules of your domain.

You can absolutely use both together — in fact, modules are a great place to implement bounded contexts and aggregates if you want to go deeper into DDD later on.

How to Build a REST API with Laravel (Beginner Guide — Part 3): Using Api Platform

saad mouizina — Mon, 24 Mar 2025 15:31:42 +0000

In the first article of this series, we went through the entire process of building a REST API with Laravel from scratch. We covered…

Continue reading on Medium »

How to Build a REST API with Laravel (Beginner Guide — part 2): Authentication with Sanctum

saad mouizina — Thu, 20 Mar 2025 12:02:31 +0000

In the first part of this series, we built a REST API with Laravel using Users, Posts, and Comments. Now, it’s time to add authentication…

Continue reading on Medium »

How to Build a REST API with Laravel (Beginner’s Guide)

saad mouizina — Sun, 16 Mar 2025 14:10:12 +0000

In this guide, we will walk through building a REST API in Laravel using Users, Posts, and Comments. We will cover:

Continue reading on Medium »

Getting Started with Laravel Projects Using Docker: My Basic Configuration

saad mouizina — Thu, 13 Mar 2025 19:18:21 +0000

As someone who frequently works with Laravel and Docker, I’ve found that Docker is an excellent tool for managing and isolating services…

Continue reading on Medium »