In this article, we'll explain end-to-end the purpose of the Repository pattern, the wrong and right ways to implement it, and most importantly: when to use it.

But before we dive into repositories, we need to understand what a Domain Model is, otherwise the pattern explanation won't make much sense. So, have you heard about Domain Models?

Domain Models

"A model is a simplified representation of a thing or phenomenon that intentionally emphasizes certain aspects while ignoring others. An abstraction with a specific use in mind."

— Rebecca Wirfs-Brock, quoted in Learning Domain-Driven Design, Vlad Khononov

The Domain Model is the heart of software in Domain-Driven Design. It represents not just data, but also behaviors and business rules of the domain we're modeling. As Eric Evans describes in his seminal book:

"The heart of software is its ability to solve domain-related problems for its user. All other features, vital though they may be, support this basic purpose."

— Eric Evans, Domain-Driven Design: Tackling Complexity in the Heart of Software

A Domain Model is composed of several building blocks. Let's understand the main ones:

Entities

An Entity is an object that has a unique identity that persists over time, even when its attributes change. Identity is what defines an Entity, not its values.

Think of it this way: you can change your address, phone number, even your name, but you're still you. Your identity (your social security number, for example) remains the same.

<?php

namespace App\Domain\Entities;

class Customer
{
    public readonly CustomerId $id;
    public readonly \DateTimeImmutable $registeredAt;

    private(set) string $name;
    private(set) Email $email;
    private(set) Address $address;
    private(set) CustomerStatus $status;
    private int $failedPaymentAttempts = 0;

    private array $domainEvents = [];

    public static function register(
        CustomerId $id,
        string $name,
        Email $email,
        Address $address
    ): self {
        $customer = new self($id, $name, $email, $address);

        $customer->recordEvent(new CustomerRegistered($id, $email));

        return $customer;
    }

    public function changeEmail(Email $newEmail): void
    {
        $this->ensureIsActive();

        $oldEmail = $this->email;
        $this->email = $newEmail;

        $this->recordEvent(new CustomerEmailChanged($this->id, $oldEmail, $newEmail));
    }

    public function recordFailedPayment(): void
    {
        $this->failedPaymentAttempts++;

        if ($this->failedPaymentAttempts >= 3) {
            $this->suspend('Too many failed payment attempts');
        }
    }

    public function suspend(string $reason): void
    {
        if ($this->status->isSuspended()) {
            throw new \DomainException('Customer is already suspended');
        }

        $this->status = CustomerStatus::suspended();

        $this->recordEvent(new CustomerSuspended($this->id, $reason));
    }

    public function reactivate(): void
    {
        if (!$this->status->isSuspended()) {
            throw new \DomainException('Customer is not suspended');
        }

        $this->status = CustomerStatus::active();
        $this->failedPaymentAttempts = 0;

        $this->recordEvent(new CustomerReactivated($this->id));
    }

    private function ensureIsActive(): void
    {
        if ($this->status->isSuspended()) {
            throw new \DomainException('Cannot perform this action on a suspended customer');
        }
    }

    private function recordEvent(object $event): void
    {
        $this->domainEvents[] = $event;
    }

    public function pullDomainEvents(): array
    {
        $events = $this->domainEvents;
        $this->domainEvents = [];
        return $events;
    }
}

Notice that Customer can change address and email, but the CustomerId remains the same. Two customers with the same name and email, but different IDs, are different customers.

Value Objects

Unlike Entities, Value Objects are defined by their attributes, not by an identity. They are immutable and compared by value.

Think about money: a $100 bill is equal to any other $100 bill. It doesn't matter which specific bill you have, what matters is the value.

<?php

namespace App\Domain\ValueObjects;

class Money
{
    public readonly float $amount;
    public readonly string $currency;

    public function __construct(float $amount, string $currency)
    {
        if ($amount < 0) {
            throw new InvalidArgumentException('Amount cannot be negative');
        }

        $this->amount = $amount;
        $this->currency = $currency;
    }

    public function add(Money $other): Money
    {
        if ($this->currency !== $other->currency) {
            throw new InvalidArgumentException('Cannot add different currencies');
        }

        return new Money($this->amount + $other->amount, $this->currency);
    }

    public function subtract(Money $other): Money
    {
        if ($this->currency !== $other->currency) {
            throw new InvalidArgumentException('Cannot subtract different currencies');
        }

        return new Money($this->amount - $other->amount, $this->currency);
    }

    public function equals(Money $other): bool
    {
        return $this->amount === $other->amount 
            && $this->currency === $other->currency;
    }
}

Another classic example is Address:

<?php

namespace App\Domain\ValueObjects;

class Address
{
    public function __construct(
        public readonly string $street,
        public readonly string $city,
        public readonly string $state,
        public readonly string $zipCode
    ) {}

    public function equals(Address $other): bool
    {
        return $this->street === $other->street
            && $this->city === $other->city
            && $this->state === $other->state
            && $this->zipCode === $other->zipCode;
    }
}

Value Objects are immutable. If you need to "change" a Value Object, you create a new one.

Aggregates

Here we arrive at the most important concept for understanding Repositories correctly.

"An Aggregate is a cluster of domain objects that we treat as a unit for the purpose of data changes."

— Eric Evans, Domain-Driven Design

An Aggregate defines a consistency boundary. It groups Entities and Value Objects that need to be modified together to keep business rules consistent.

Every Aggregate has an Aggregate Root: the main Entity through which all external access must pass. External objects can only reference the Aggregate Root, never the internal entities directly.

Vaughn Vernon, in the red book (Implementing Domain-Driven Design), reinforces:

"Prefer references to external Aggregates only by their globally unique identity, not by holding a direct object reference (or 'pointer')."

Practical Example: Order

Let's use a classic e-commerce example: an order with its items.

<?php

namespace App\Domain\Entities;

use App\Domain\ValueObjects\Money;
use App\Domain\ValueObjects\OrderId;
use App\Domain\ValueObjects\CustomerId;

// Aggregate Root
class Order
{
    public readonly OrderId $id;
    public readonly CustomerId $customerId;
    public readonly \DateTimeImmutable $createdAt;

    private(set) string $status;
    private(set) Money $totalAmount;

    /** @var OrderItem[] */
    private(set) array $items = [];

    public function __construct(OrderId $id, CustomerId $customerId)
    {
        $this->id = $id;
        $this->customerId = $customerId;
        $this->status = 'pending';
        $this->totalAmount = new Money(0, 'USD');
        $this->createdAt = new \DateTimeImmutable();
    }

    public function addItem(
        string $productId,
        string $productName,
        Money $unitPrice,
        int $quantity
    ): void {
        $this->ensurePending();

        $this->items[] = new OrderItem(
            productId: $productId,
            productName: $productName,
            unitPrice: $unitPrice,
            quantity: $quantity
        );

        $this->recalculateTotal();
    }

    public function removeItem(string $productId): void
    {
        $this->ensurePending();

        $this->items = array_values(array_filter(
            $this->items,
            fn(OrderItem $item) => $item->productId !== $productId
        ));

        $this->recalculateTotal();
    }

    public function confirm(): void
    {
        if (empty($this->items)) {
            throw new \DomainException('Cannot confirm an empty order');
        }

        $this->status = 'confirmed';
    }

    private function ensurePending(): void
    {
        if ($this->status !== 'pending') {
            throw new \DomainException('Cannot modify a confirmed order');
        }
    }

    private function recalculateTotal(): void
    {
        $total = new Money(0, 'USD');

        foreach ($this->items as $item) {
            $total = $total->add($item->subtotal);
        }

        $this->totalAmount = $total;
    }
}

And the OrderItem (an Entity internal to the Aggregate):

<?php

namespace App\Domain\Entities;

use App\Domain\ValueObjects\Money;

class OrderItem
{
    public readonly string $productId;
    public readonly string $productName;
    public readonly Money $unitPrice;

    private(set) int $quantity;

    public function __construct(
        string $productId,
        string $productName,
        Money $unitPrice,
        int $quantity
    ) {
        if ($quantity <= 0) {
            throw new \InvalidArgumentException('Quantity must be positive');
        }

        $this->productId = $productId;
        $this->productName = $productName;
        $this->unitPrice = $unitPrice;
        $this->quantity = $quantity;
    }

    public function updateQuantity(int $quantity): void
    {
        if ($quantity <= 0) {
            throw new \InvalidArgumentException('Quantity must be positive');
        }

        $this->quantity = $quantity;
    }

    public Money $subtotal {
        get => new Money(
            $this->unitPrice->amount * $this->quantity,
            $this->unitPrice->currency
        );
    }
}

Important points:

1. Order is the Aggregate Root

2. OrderItem can only be accessed through Order

3. All invariants (business rules) are protected by the Aggregate Root

4. The Aggregate guarantees transactional consistency

Notice that we don't have an OrderItemRepository. Order items are always manipulated through Order.

DAO vs Repository

Now that we understand Domain Models and Aggregates, we can finally understand the difference between DAO and Repository. This is the part that most developers confuse.

DAO (Data Access Object)

The DAO pattern emerged in the context of J2EE applications, documented in the book Core J2EE Patterns (Alur, Crupi, and Malks, 2001). It's a data-oriented pattern.

A DAO is an abstraction close to the database. It encapsulates access to a specific data source (usually a table) and provides CRUD operations.

DAO Characteristics:

• Table-centric: Usually one DAO per table

• Database-oriented: Methods reflect database operations (insert, update, delete, find)

• Lower-level: Closer to infrastructure

• Data-focused: Works with data, not domain behavior

Note: The following examples use Laravel with Eloquent ORM to demonstrate the concepts in a familiar context for PHP developers.

<?php

namespace App\Infrastructure\DAO;

use App\Models\Order as OrderModel;
use Illuminate\Support\Collection;

class OrderDAO
{
    public function insert(array $data): int
    {
        $order = OrderModel::create($data);
        return $order->id;
    }

    public function update(int $id, array $data): bool
    {
        return OrderModel::where('id', $id)->update($data) > 0;
    }

    public function delete(int $id): bool
    {
        return OrderModel::destroy($id) > 0;
    }

    public function findById(int $id): ?array
    {
        $order = OrderModel::find($id);
        return $order?->toArray();
    }

    public function findByCustomerId(int $customerId): array
    {
        return OrderModel::where('customer_id', $customerId)
            ->get()
            ->toArray();
    }

    public function findByStatus(string $status): array
    {
        return OrderModel::where('status', $status)
            ->get()
            ->toArray();
    }
}

And a separate DAO for the items:

<?php

namespace App\Infrastructure\DAO;

use App\Models\OrderItem as OrderItemModel;

class OrderItemDAO
{
    public function insert(array $data): int
    {
        $item = OrderItemModel::create($data);
        return $item->id;
    }

    public function deleteByOrderId(int $orderId): int
    {
        return OrderItemModel::where('order_id', $orderId)->delete();
    }

    public function findByOrderId(int $orderId): array
    {
        return OrderItemModel::where('order_id', $orderId)
            ->get()
            ->toArray();
    }

    public function update(int $id, array $data): bool
    {
        return OrderItemModel::where('id', $id)->update($data) > 0;
    }
}

Notice: DAOs work with arrays, not domain objects. They are agnostic to the domain model. Each DAO corresponds to a single table.

Repository

The Repository pattern, on the other hand, emerged in the context of Domain-Driven Design, described by Eric Evans. It's a domain-oriented pattern.

"A Repository represents all objects of a certain type as a conceptual set... It acts like an in-memory collection of domain objects."

— Eric Evans, Domain-Driven Design

Repository Characteristics:

• Aggregate-centric: One Repository per Aggregate Root

• Domain-oriented: Methods speak the domain language

• Higher-level: Abstraction over data access

• Collection-like: Simulates an in-memory collection

• Encapsulates complexity: Hides how data is mapped and persisted

Repository in Domain Driven Design Context

In Domain-Driven Design, there's a clear separation between layers:

• Domain Layer: Contains Entities, Value Objects, Aggregates, Domain Services, and Repository Interfaces

• Infrastructure Layer: Contains Repository Implementations, ORM configurations, external service integrations

The Repository interface belongs to the Domain layer because it's part of the domain's vocabulary. The domain knows it needs to "save an Order" or "find Orders by customer", but it doesn't care how that's done.

The Repository implementation belongs to the Infrastructure layer because it deals with technical details like Eloquent, database connections, and query building.

app/
├── Domain/
│   ├── Aggregates/
│   │   └── Order.php
│   ├── Entities/
│   │   └── OrderItem.php
│   ├── ValueObjects/
│   │   ├── OrderId.php
│   │   ├── CustomerId.php
│   │   └── Money.php
│   └── Repositories/
│       └── OrderRepositoryInterface.php  <-- Interface (Domain Layer)
│
└── Infrastructure/
    └── Repositories/
        └── EloquentOrderRepository.php   <-- Implementation (Infrastructure Layer)

This separation allows you to:

1. Test domain logic without database dependencies

2. Swap implementations without changing domain code

3. Keep domain code clean and focused on business rules

Repository Interface (Domain Layer)

<?php

namespace App\Domain\Repositories;

use App\Domain\Aggregates\Order;
use App\Domain\ValueObjects\OrderId;
use App\Domain\ValueObjects\CustomerId;

interface OrderRepositoryInterface
{
    public function save(Order $order): void;

    public function findById(OrderId $id): ?Order;

    public function findByCustomer(CustomerId $customerId): array;

    public function findPendingOrders(): array;

    public function delete(Order $order): void;
}

Repository Implementation (Infrastructure Layer)

Now the implementation using Eloquent directly (without DAO):

<?php

namespace App\Infrastructure\Repositories;

use App\Domain\Aggregates\Order;
use App\Domain\Entities\OrderItem;
use App\Domain\Repositories\OrderRepositoryInterface;
use App\Domain\ValueObjects\CustomerId;
use App\Domain\ValueObjects\Money;
use App\Domain\ValueObjects\OrderId;
use App\Models\Order as OrderModel;
use App\Models\OrderItem as OrderItemModel;
use Illuminate\Support\Facades\DB;

class EloquentOrderRepository implements OrderRepositoryInterface
{
    public function save(Order $order): void
    {
        DB::transaction(function () use ($order) {
            // Upsert the order
            OrderModel::updateOrCreate(
                ['id' => $order->getId()->getValue()],
                [
                    'customer_id' => $order->getCustomerId()->getValue(),
                    'status' => $order->getStatus(),
                    'total_amount' => $order->getTotalAmount()->getAmount(),
                    'currency' => $order->getTotalAmount()->getCurrency(),
                    'created_at' => $order->getCreatedAt(),
                ]
            );

            // Remove old items and insert new ones
            OrderItemModel::where('order_id', $order->getId()->getValue())->delete();

            foreach ($order->getItems() as $item) {
                OrderItemModel::create([
                    'order_id' => $order->getId()->getValue(),
                    'product_id' => $item->getProductId(),
                    'product_name' => $item->getProductName(),
                    'unit_price' => $item->getUnitPrice()->getAmount(),
                    'currency' => $item->getUnitPrice()->getCurrency(),
                    'quantity' => $item->getQuantity(),
                ]);
            }
        });
    }

    public function findById(OrderId $id): ?Order
    {
        $orderModel = OrderModel::with('items')->find($id->getValue());

        if (!$orderModel) {
            return null;
        }

        return $this->toDomainEntity($orderModel);
    }

    public function findByCustomer(CustomerId $customerId): array
    {
        $orders = OrderModel::with('items')
            ->where('customer_id', $customerId->getValue())
            ->get();

        return $orders->map(fn($model) => $this->toDomainEntity($model))->all();
    }

    public function findPendingOrders(): array
    {
        $orders = OrderModel::with('items')
            ->where('status', 'pending')
            ->get();

        return $orders->map(fn($model) => $this->toDomainEntity($model))->all();
    }

    public function delete(Order $order): void
    {
        DB::transaction(function () use ($order) {
            OrderItemModel::where('order_id', $order->getId()->getValue())->delete();
            OrderModel::destroy($order->getId()->getValue());
        });
    }

    /**
     * Reconstitutes a domain Order aggregate from an Eloquent model.
     */
    private function toDomainEntity(OrderModel $model): Order
    {
        $order = new Order(
            new OrderId($model->id),
            new CustomerId($model->customer_id)
        );

        // Add items to the order
        foreach ($model->items as $itemModel) {
            $order->addItem(
                $itemModel->product_id,
                $itemModel->product_name,
                new Money($itemModel->unit_price, $itemModel->currency),
                $itemModel->quantity
            );
        }

        // Restore the status using reflection (since status might not be 'pending')
        if ($model->status !== 'pending') {
            $this->setPrivateProperty($order, 'status', $model->status);
        }

        // Restore the original created_at
        $this->setPrivateProperty($order, 'createdAt', new \DateTimeImmutable($model->created_at));

        return $order;
    }

    private function setPrivateProperty(object $object, string $property, mixed $value): void
    {
        $reflection = new \ReflectionProperty($object::class, $property);
        $reflection->setAccessible(true);
        $reflection->setValue($object, $value);
    }
}

Key points:

1. The Repository receives and returns complete Aggregates (Order with its Items)

2. The Repository handles multiple tables internally (orders + order_items)

3. The interface speaks the domain language (findPendingOrders, not findByStatus)

4. The mapping between tables and domain objects is encapsulated

5. Eloquent models are infrastructure details, not domain objects

6. The domain Order class has behavior; the Eloquent Order model is just for persistence

Comparison Table: DAO vs Repository

Repository Works Better with a Domain Model

The main point is: Repositories make sense when you have a rich Domain Model.

A Repository receives an Aggregate ID and returns a complete, hydrated Aggregate. It's the layer that translates between two worlds: the domain world (with Aggregates, Entities, and Value Objects) and the database world (with tables and relationships).

One Aggregate can persist data across multiple tables.

In our Order example:

• The domain has: 1 Aggregate (Order with OrderItems)

• The database has: 2 tables (orders and order_items)

This is a 1:2 relationship between Aggregate and tables.

We can have other proportions:

• 1:1 - A simple Aggregate in one table

• 1:3 - A complex Aggregate distributed across three tables

• 1:N - Aggregates with many internal entities

The Repository hides all this complexity from the rest of the application.

Repos Without a Domain Model are DAOs?

If you don't have a rich Domain Model, if your "models" are just DTOs or anemic objects without behavior, then yes, your Repository is basically a “glorified” DAO.

And that's not necessarily wrong! Not every application needs DDD. Simple CRUD applications can work perfectly well with Active Record or DAOs.

The problem is when you use the "Repository" nomenclature but implement a DAO, losing all the benefits of the pattern.

Are Laravel Eloquent Models DAOs?

This is a very common question in the Laravel ecosystem. The short answer: Eloquent Models implement the Active Record pattern, not DAO nor Repository.

The Active Record pattern, described by Martin Fowler in Patterns of Enterprise Application Architecture, combines data and persistence behavior in the same object. Each Model represents a row in the database and knows how to save and load itself.

// Active Record - the model knows about persistence
$user = new User();
$user->name = 'John';
$user->save(); // The model itself knows how to save

Active Record is different from both DAO and Repository:

• DAO: Separate object that manages data access for a table

• Repository: Collection abstraction for Aggregate Roots

• Active Record: The data object itself knows how to persist

Problems with using Active Record as Repository:

Active Record couples your domain model to database infrastructure. This goes against the Repository principle of isolating the domain from persistence details.

// This is NOT a real Repository - it's just a wrapper
class UserRepository
{
    public function find(int $id): User
    {
        return User::find($id); // Still using Active Record
    }

    public function save(User $user): void
    {
        $user->save(); // The model still knows about persistence
    }
}

This "Repository" doesn't provide real abstraction. The User is still an Eloquent Model that knows about the database.

When is this acceptable?

For most Laravel applications, using Eloquent directly is perfectly valid. Active Record is excellent for RAD (Rapid Application Development) and CRUD applications.

When should you consider "real" Repository?

• When you have complex domain logic that needs to be tested in isolation

• When you want to swap persistence mechanisms (rare in practice)

• When you're strictly following DDD

What I See Out There

Let me be honest about what I see in the real world:

1. Proxy Repos with Eloquent

// This is very common and... questionable
class UserRepository
{
    public function all()
    {
        return User::all();
    }

    public function find($id)
    {
        return User::find($id);
    }

    public function create(array $data)
    {
        return User::create($data);
    }
}

This is not a Repository, it's a proxy that adds no value. The Eloquent Model already does all of this.

2. One Repo per Table

// Too many repos, following DAO logic
class OrderRepository { }
class OrderItemRepository { }
class OrderStatusHistoryRepository { }

If OrderItem and OrderStatusHistory only exist in the context of an Order, you don't need separate repositories for them. The OrderRepository should manage the complete Aggregate.

3. Generic Interface for All

interface RepositoryInterface
{
    public function all();
    public function find($id);
    public function create(array $data);
    public function update($id, array $data);
    public function delete($id);
}

This turns all Repositories into DAOs. Each Repository should have its own interface with domain-specific methods.

Base Repository: Is It Worth It?

A common question: is it correct to have a Base Repository for CRUD operations and leave specific repositories only for extra queries?

abstract class BaseRepository
{
    protected $model;

    public function find($id)
    {
        return $this->model->find($id);
    }

    public function save($entity): void
    {
        $entity->save();
    }

    public function delete($entity): void
    {
        $entity->delete();
    }
}

class OrderRepository extends BaseRepository
{
    public function __construct()
    {
        $this->model = new Order();
    }

    // Domain-specific methods
    public function findPendingByCustomer(CustomerId $customerId): array
    {
        // ...
    }
}

My opinion: this works, but goes against the spirit of the Repository pattern.

Problems:

1. Assumes all Aggregates are persisted the same way

2. A complex Aggregate (like Order with Items) doesn't follow this pattern

3. Generic methods like find($id) don't speak the domain language

4. You lose the main advantage: swapping implementations

When it can work:

• Simpler applications where Aggregates map 1:1 to tables

• Teams starting with the pattern and needing something pragmatic

• Projects where complete abstraction isn't necessary

The ideal alternative for DDD contexts:

For that context, don't use inheritance and don't use a BaseRepository. Each repository should have its own implementation because each Aggregate has different persistence needs.

<?php

// Order: complex aggregate (2 tables)
class EloquentOrderRepository implements OrderRepositoryInterface
{
    public function findById(OrderId $id): ?Order
    {
        $model = OrderModel::with('items')->find($id->value);

        return $model ? $this->toDomainEntity($model) : null;
    }

    public function save(Order $order): void
    {
        DB::transaction(function () use ($order) {
            // Saves to 'orders' table
            // Saves to 'order_items' table
        });
    }

    private function toDomainEntity(OrderModel $model): Order { /* ... */ }
}

// Customer: simple aggregate (1 table)
class EloquentCustomerRepository implements CustomerRepositoryInterface
{
    public function findById(CustomerId $id): ?Customer
    {
        $model = CustomerModel::find($id->value);

        return $model ? $this->toDomainEntity($model) : null;
    }

    public function save(Customer $customer): void
    {
        // Saves to 'customers' table only
        CustomerModel::updateOrCreate([/* ... */]);
    }

    private function toDomainEntity(CustomerModel $model): Customer { /* ... */ }
}

Alternative for simple CRUDs:

If you need to share common CRUD logic for simple aggregates, use a trait:

<?php

class EloquentCustomerRepository implements CustomerRepositoryInterface
{
    use CrudRepositoryTrait;  // Handles basic find, save, delete

    // Domain-specific methods - implemented manually
    public function findByEmail(Email $email): ?Customer { /* ... */ }
    public function findActiveCustomers(): array { /* ... */ }
}

The key difference from BaseRepository:

• Interface stays domain-specific — CustomerRepositoryInterface has methods like findByEmail(), not generic find($id)

• Trait is just implementation detail — helps reduce boilerplate for basic operations

• Each repository still owns its mapping — toDomainEntity() and toDatabase() are specific to each Aggregate

For complex aggregates like Order (which persists to orders + order_items tables), write the repository from scratch. The trait won't fit, and that's fine — each repository knows best how to persist its Aggregate.

Conclusion

The Repository Pattern is powerful when used correctly, but frequently misunderstood.

Key points:

1. Repository ≠ DAO: Repository is domain-oriented, DAO is data-oriented

2. One Repository per Aggregate Root: Don't create repositories for internal entities

3. Repository requires Domain Model: Without a rich Domain Model, you just have a disguised DAO

4. Eloquent is Active Record: It's not DAO nor Repository

5. Interface should speak the domain language: findPendingOrders(), not findByStatus('pending')

6. Interface in Domain, Implementation in Infrastructure: This separation is key in DDD

Before implementing the Repository Pattern, ask yourself: "Do I really need this?"

If your application is simple CRUD, Active Record (Eloquent) solves it perfectly. If you have complex domain logic, business invariants, and need real testability, then yes, Repository might be the right choice.

References

• Evans, Eric. Domain-Driven Design: Tackling Complexity in the Heart of Software. Addison-Wesley, 2003. (Blue Book)

• Vernon, Vaughn. Implementing Domain-Driven Design. Addison-Wesley, 2013. (Red Book)

• Khononov, Vlad. Learning Domain-Driven Design: Aligning Software Architecture and Business Strategy. O'Reilly Media, 2021.

• Alur, Deepak; Crupi, John; Malks, Dan. Core J2EE Patterns: Best Practices and Design Strategies. Prentice Hall, 2001.

• Fowler, Martin. Patterns of Enterprise Application Architecture. Addison-Wesley, 2002.

• Evans, Eric. Domain-Driven Design Reference: Definitions and Pattern Summaries. Domain Language, 2015.

Enter CQRS (Command Query Responsibility Segregation) and Event-Driven Architecture – patterns that challenge the traditional way we build applications by answering a simple but important question: Why should reading data work the same way as writing it?

In this article, I'll walk you through building a example of a simple Order Management System that implements CQRS with PHP 8.4, using Slim Framework, RabbitMQ, PostgreSQL, and MongoDB. But more importantly, I'll explain why you might want to use these patterns, when they make sense, and how to implement them without overcomplicating your architecture.

What We'll Build

We'll create a system where:

• Write operations (creating/updating orders) go to PostgreSQL

• Read operations (querying orders) come from MongoDB

• Events connect both sides through RabbitMQ

• Everything is containerized with Docker for easy setup

By the end, you'll understand not just how CQRS works in theory, but how to implement it in PHP.

Why This Matters

Traditional CRUD applications face real challenges:

• Read queries can block write operations

• Complex joins slow down as data grows

• Scaling reads and writes independently is difficult

• One database structure must serve all purposes

CQRS solves these problems by recognizing a fundamental truth: the way we write data is rarely the optimal way to read it.

What is CQRS, Really?

CQRS stands for Command Query Responsibility Segregation. The idea is simple: separate the code that changes data from the code that reads data.

In a typical applications, everything hits the same database. One database handles everything with one structure that tries to be good at both reading and writing. Usually it ends up mediocre at both.

CQRS splits this responsibility. Write operations use one model and read operations use another model. They can share the same database or use different ones. In our project, we take it further by using PostgreSQL for writes and MongoDB for reads, with RabbitMQ keeping them in sync. When something changes on the write side, an event gets sent through the message queue. A consumer picks it up and updates the read side.

The key point is that CQRS is about separating the models and responsibilities, not necessarily about having two databases. You could have CQRS with a single database using different tables or even different queries against the same tables. The dual-database approach with message queues is just one way to implement it.

This makes sense when your reads vastly outnumber your writes. An e-commerce site might have ten thousand people browsing but only fifty making purchases. It also helps when read and write operations need different things. Writing needs data integrity and transactions. Reading needs speed and denormalized data.

Skip CQRS for simple CRUD apps, admin panels, or internal tools. If your database isn't slow and your reads and writes are roughly equal, you're just adding complexity for no reason.

Event-driven architecture pairs well with CQRS but isn't required. You could implement CQRS by directly updating both models synchronously. In our project, we use events because they provide flexibility. When a user creates an order, you handle the write and create an event. That event goes to RabbitMQ. Multiple listeners can react: one updates MongoDB, another sends an email, another logs analytics. Your write code stays simple. It just says "an order was created" and walks away. Everything else happens in the background.

The trade-off is eventual consistency. Your read database won't update instantly. There's a small delay while the event travels through the message queue. For most applications, a delay of a few milliseconds is fine.

As Greg Young points out in his CQRS documentation, the command and query sides have very different needs. The command side processes transactions with consistent data and needs strong guarantees. The query side, however, can be eventually consistent in most systems. This difference is actually an advantage: it's far easier to process transactions with consistent data than to handle all the edge cases that eventual consistency brings into play on the write side.

But if you're building something like banking software where data must be immediately consistent, you need to think carefully about this trade-off.

A Word of Caution

Martin Fowler, one of the most respected voices in software architecture, offers an important warning about CQRS. He notes that while CQRS can benefit a few complex domains, such suitability is very much the minority case. Usually there's enough overlap between the command and query sides that sharing a model is easier. Using CQRS on a domain that doesn't match it will add complexity, thus reducing productivity and increasing risk.

This is worth taking seriously. CQRS is not a default architecture. It's a specialized tool for specific problems. Most applications are better served by a traditional architecture where reads and writes share the same model. The complexity you add with CQRS needs to pay for itself with clear benefits: better scalability, clearer separation of concerns, or the ability to optimize reads and writes differently.

Before implementing CQRS, ask yourself: do I actually have these problems? If your application works fine with a single database and traditional queries, stick with that. Simple is better than clever.

The Project: Order Management System

To understand CQRS in practice, we built an order management system. The application is simple enough to grasp quickly but complete enough to demonstrate all the moving parts.

The system handles basic order operations. You can create orders, update their status, and query them. Nothing fancy. But under the hood, writes go to PostgreSQL while reads come from MongoDB, with RabbitMQ keeping everything in sync.

Architecture Overview

Here's how the pieces fit together:

+-------------+
|   client    |
+------+------+
       |
       | post /orders
       v
+-----------------+
|   slim api      |
|  (commands)     |
+--------+--------+
         |
         v
+-----------------+
|  postgresql     |
|  (write db)     |
+--------+--------+
         |
         | event: ordercreated
         v
+-----------------+
|   rabbitmq      |
|   (queue)       |
+--------+--------+
         |
         v
+-----------------+
|   consumer      |
|   (listener)    |
+--------+--------+
         |
         v
+-----------------+
|   mongodb       |
|   (read db)     |
+--------+--------+
         |
         | get /orders
         ^
+-----------------+
|   slim api      |
|   (queries)     |
+-----------------+

When a client creates an order, the request hits our Slim API. The API executes a command that saves the order to PostgreSQL. At this point, the order exists in the write database, but nowhere else.

Next, the command handler dispatches an event. This event gets published to RabbitMQ, where it sits in a queue waiting to be processed. The API responds to the client immediately without waiting for anything else to happen.

Meanwhile, a separate consumer process runs continuously, listening to the RabbitMQ queue. When it sees the order created event, it pulls the relevant data and writes it to MongoDB in a structure optimized for reading.

Now when a client queries for orders, the API reads directly from MongoDB. No joins, no complex queries. The data is already shaped exactly how we need it.

The Directory Structure

event-driven-cqrs-php/
│
├── api/
│   ├── src/
│   │   ├── Application/         ← HTTP layer
│   │   │   ├── Actions/         (Request handlers)
│   │   │   ├── Command/         (Write operations)
│   │   │   └── Query/           (Read operations)
│   │   │
│   │   ├── Domain/              ← Business logic
│   │   │   └── Order/
│   │   │       ├── Event/       (Domain events)
│   │   │       └── Order.php    (Entity)
│   │   │
│   │   └── Infrastructure/      ← Technical details
│   │       ├── Consumer/        (RabbitMQ listener)
│   │       ├── Persistence/     (PostgreSQL)
│   │       └── Query/           (MongoDB)
│   │
│   └── bin/
│       └── consumer.php         ← Background worker
│
└── docker/
    ├── php/
    └── postgres/

The project follows a clean architecture with three main layers.

The Application layer contains everything related to handling requests. Actions are the HTTP handlers that receive requests and return responses. Commands represent write operations with their handlers. Queries represent read operations with their handlers.

The Domain layer holds the business logic. This is where the Order entity lives, along with domain events like OrderCreated and OrderStatusChanged. The domain doesn't know anything about databases or HTTP. It just models what an order is and what can happen to it.

The Infrastructure layer handles all the technical details. Database connections, repository implementations, event listeners, and the RabbitMQ consumer all live here. This layer is the bridge between your domain and the outside world.

The Flow in Detail

Let's trace what happens step by step when you create an order:

1. Client Request
   POST /orders
   {
     "customer_name": "John Doe",
     "items": [...]
   }

2. Action Handler
   ↓
   CreateOrderCommand

3. Command Handler
   ↓
   Save to PostgreSQL
   ↓
   Dispatch OrderCreated Event

4. Event Listener
   ↓
   Publish to RabbitMQ
   ↓
   [API responds to client]

5. Consumer (background)
   ↓
   Read from RabbitMQ
   ↓
   Write to MongoDB

6. Query Time
   GET /orders
   ↓
   Read from MongoDB
   ↓
   Return response

The request comes in as a POST to /orders with JSON data. An Action handler receives it and creates a CreateOrderCommand with the request data. This command gets passed to a CreateOrderCommandHandler.

The command handler does two things. First, it saves the order to PostgreSQL using a repository. Second, it dispatches an OrderCreated event using League Event dispatcher.

An event listener immediately catches this event and publishes a message to RabbitMQ. The message contains the order ID and relevant data. At this point, the API request is done and sends a response back to the client.

The consumer process, which runs separately in its own container, picks up the message from RabbitMQ. It reads the order data and writes it to MongoDB in a denormalized format. Now the read model is updated.

When someone queries for orders, they hit GET /orders. A Query handler receives the request and fetches data directly from MongoDB. Fast, simple, no complex queries needed.

Database Structures

Here's how the same order looks in each database:

PostgreSQL (Write Model - Normalized):

orders table:
┌─────────────────────────────────────┬─────────────┬─────────┬────────────┐
│ id                                  │ customer_id │ total   │ status     │
├─────────────────────────────────────┼─────────────┼─────────┼────────────┤
│ 550e8400-e29b-41d4-a716-446655440000│ 123         │ 1049.99 │ pending    │
└─────────────────────────────────────┴─────────────┴─────────┴────────────┘

order_items table:
┌──────────┬────────────────────────────────────┬──────────┬──────────┐
│ order_id │ product_id                         │ quantity │ price    │
├──────────┼────────────────────────────────────┼──────────┼──────────┤
│ 550e...  │ prod_001                           │ 1        │ 999.99   │
│ 550e...  │ prod_002                           │ 2        │ 25.00    │
└──────────┴────────────────────────────────────┴──────────┴──────────┘

MongoDB (Read Model - Denormalized):

{
  "_id": "550e8400-e29b-41d4-a716-446655440000",
  "customer_name": "John Doe",
  "customer_email": "john@example.com",
  "items": [
    {"product": "Laptop", "quantity": 1, "price": 999.99},
    {"product": "Mouse", "quantity": 2, "price": 25.00}
  ],
  "total_amount": 1049.99,
  "status": "pending",
  "created_at": "2024-01-15T10:30:00Z"
}

PostgreSQL keeps things normalized for data integrity. MongoDB has everything pre-joined and ready to display.

Why This Structure Works

The separation of concerns is clear. Commands never touch MongoDB. Queries never touch PostgreSQL. Events flow in one direction from write to read.

You can scale each piece independently. Need to handle more reads? Add MongoDB replicas. Need to process events faster? Run multiple consumer instances. The write database can stay small and focused.

Testing becomes easier too. You can test command handlers without worrying about the read model. You can test query handlers without setting up event processing. Each piece has one job and does it well.

Let's dive in and see how this works in practice.

Looking at the Code

Now let's see how this actually works in practice. I'll walk you through the complete flow from creating an order to querying it back.

The full source code is available here: https://github.com/sahdoio/event-driven-cqrs-php?tab=readme-ov-file

Clone the project into your machine and then start the docker containers.

The Docker Setup

To start the application setup type on the project root folder:

make go

The Command: What We Want to Do

When someone creates an order, we start with a command object. It's just a simple data container:

class CreateOrderCommand
{
    public function __construct(
        public readonly string $customerName,
        public readonly string $customerEmail,
        public readonly array $items,
        public readonly float $totalAmount
    ) {}
}

Nothing fancy. Just the data needed to create an order.

The Command Handler: Doing the Work

The command handler receives this command and does two things:

class CreateOrderHandler
{
    public function __construct(
        private readonly PostgresOrderRepository $orderRepository,
        private readonly EventDispatcher $eventDispatcher
    ) {}

    public function handle(CreateOrderCommand $command): string
    {
        // 1. Create and save the order to PostgreSQL
        $orderId = Uuid::uuid7();
        $order = new Order(
            $orderId,
            $command->customerName,
            $command->customerEmail,
            $command->items,
            $command->totalAmount,
            OrderStatus::PENDING
        );

        $this->orderRepository->save($order);

        // 2. Dispatch an event
        $event = new OrderCreated(
            $orderId->toString(),
            $order->getCustomerName(),
            $order->getCustomerEmail(),
            $order->getItems(),
            $order->getTotalAmount(),
            $order->getStatus()->value,
            $order->getCreatedAt()->format('Y-m-d H:i:s')
        );

        $this->eventDispatcher->dispatch($event);

        return $orderId->toString();
    }
}

First it creates the Order entity and saves it to PostgreSQL. Then it creates an event and dispatches it. The handler doesn't know what happens with that event. Its job is done.

The Repository: Talking to PostgreSQL

The repository handles the database details:

public function save(Order $order): void
{
    $sql = "INSERT INTO orders (id, customer_name, customer_email, items, total_amount, status, created_at, updated_at)
            VALUES (:id, :customer_name, :customer_email, :items, :total_amount, :status, :created_at, :updated_at)
            ON CONFLICT (id) DO UPDATE SET ...";

    $stmt = $pdo->prepare($sql);
    $stmt->execute([
        'id' => $order->getId()->toString(),
        'customer_name' => $order->getCustomerName(),
        'customer_email' => $order->getCustomerEmail(),
        'items' => json_encode($order->getItems()),
        'total_amount' => $order->getTotalAmount(),
        'status' => $order->getStatus()->value,
        'created_at' => $order->getCreatedAt()->format('Y-m-d H:i:s'),
        'updated_at' => $order->getUpdatedAt()?->format('Y-m-d H:i:s'),
    ]);
}

Standard database insertion. The order is now in PostgreSQL.

Publishing to RabbitMQ

When the event dispatcher fires the OrderCreated event, the RabbitMQEventPublisher catches it:

class RabbitMQEventPublisher implements Listener
{
    public function __invoke(object $event): void
    {
        $eventName = method_exists($event, 'eventName') ? $event->eventName() : get_class($event);
        $payload = method_exists($event, 'toArray') ? $event->toArray() : ['event' => $eventName];

        $message = $this->context->createMessage(json_encode([
            'event' => $eventName,
            'payload' => $payload,
            'timestamp' => time(),
        ]));

        $this->producer->send($queue, $message);
    }
}

It serializes the event to JSON and sends it to RabbitMQ. At this point, the HTTP request is done. The API returns a response to the client.

The Consumer: Processing Events

Meanwhile, a separate PHP process runs continuously:

// bin/consumer.php
$consumer = $container->get(MessageConsumer::class);
echo "Message Consumer started\n";
echo "Listening for events on RabbitMQ...\n";
$consumer->consume();

This consumer sits there waiting for messages:

public function consume(): void
{
    while (true) {
        $message = $this->consumer->receive(1000);

        if ($message === null) {
            continue;
        }

        try {
            $data = json_decode($message->getBody(), true);
            $event = $data['event'];
            $payload = $data['payload'];

            $this->eventRouter->dispatch($event, $payload);
            $this->consumer->acknowledge($message);

            echo sprintf("Processed event: %s\n", $event);
        } catch (\Exception $e) {
            $this->consumer->reject($message);
            echo sprintf("Error processing event: %s\n", $e->getMessage());
        }
    }
}

When it receives a message, it extracts the event name and payload, then routes it to the appropriate listener.

The Event Listener: Updating MongoDB

The OrderCreatedListener handles the event:

class OrderCreatedListener implements EventListenerInterface
{
    public static function subscribedTo(): string
    {
        return 'order.created';
    }

    public function handle(array $payload): void
    {
        $collection = $this->mongoConnection->getDatabase()->selectCollection('orders');

        $collection->insertOne([
            '_id' => $payload['order_id'],
            'customer_name' => $payload['customer_name'],
            'customer_email' => $payload['customer_email'],
            'items' => $payload['items'],
            'total_amount' => $payload['total_amount'],
            'status' => $payload['status'],
            'created_at' => $payload['created_at'],
            'updated_at' => null,
        ]);
    }
}

It takes the event payload and writes it directly to MongoDB. Now the read model is updated.

The Complete Flow

Let me put it all together:

Step 1: Client sends POST request to create an order
Step 2: CreateOrderHandler receives CreateOrderCommand
Step 3: Handler creates Order entity and saves to PostgreSQL
Step 4: Handler dispatches OrderCreated event
Step 5: RabbitMQEventPublisher catches event and sends to RabbitMQ
Step 6: API responds to client (order created)
Step 7: Consumer picks up message from RabbitMQ
Step 8: Consumer routes event to OrderCreatedListener
Step 9: Listener inserts order into MongoDB
Step 10: Read model is now updated

When someone queries for orders, they hit a different endpoint that reads directly from MongoDB. No PostgreSQL involved. No events. Just a simple query.

Dependency Injection Setup

Everything is wired together in the dependencies file:

EventDispatcher::class => function (ContainerInterface $c) {
    $dispatcher = new EventDispatcher();
    $dispatcher->subscribeTo('order.created', $c->get(RabbitMQEventPublisher::class));
    $dispatcher->subscribeTo('order.updated', $c->get(RabbitMQEventPublisher::class));
    return $dispatcher;
},

CreateOrderHandler::class => function (ContainerInterface $c) {
    return new CreateOrderHandler(
        $c->get(PostgresOrderRepository::class),
        $c->get(EventDispatcher::class)
    );
},

The container builds all the pieces and injects dependencies where needed. Command handlers get repositories and event dispatchers. Query handlers get MongoDB connections. The consumer gets the event router with all listeners registered.

What Makes This Work

The separation is clean. Commands know nothing about MongoDB. Queries know nothing about PostgreSQL or events. The event system connects them without coupling them together.

You can test each piece independently. Mock the repository to test the command handler. Mock MongoDB to test the query handler. The consumer can be tested separately from the API.

And you can scale each piece differently. Need more API capacity? Add more PHP containers. Need faster event processing? Run multiple consumer instances. MongoDB getting hammered? Add replicas. They all scale independently.

Conclusion

CQRS isn't a silver bullet. It adds complexity that you need to justify with real benefits. Most applications don't need it.

But when you do need it, when your reads and writes have fundamentally different needs, when you need to scale them independently, CQRS gives you a clean way to handle that complexity.

The code in this project shows that implementing CQRS doesn't have to be complicated. Commands write to PostgreSQL. Queries read from MongoDB. Events keep them in sync through RabbitMQ. Each piece does one thing well.

The real lesson is knowing when to use patterns like this. Don't reach for CQRS because it's interesting or because you read about it in an article. Use it when you have the specific problems it solves.

The project is available on GitHub if you want to dig deeper. Clone it, run it, break it, see how it works. Understanding comes from doing.

https://github.com/sahdoio/event-driven-cqrs-php?tab=readme-ov-file

References

Young, G. (2010). CQRS Documents. Retrieved from https://cqrs.wordpress.com/wp-content/uploads/2010/11/cqrs_documents.pdf

Fowler, M. (2011). CQRS. martinfowler.com. Retrieved from https://martinfowler.com/bliki/CQRS.html

Microsoft. (n.d.). Command and Query Responsibility Segregation (CQRS) pattern. Azure Architecture Center. Retrieved from https://learn.microsoft.com/en-us/azure/architecture/patterns/cqrs

Vernon, V. (2013). Implementing Domain-Driven Design. Addison-Wesley Professional.

In this article, we’ll break down how these ideas work together to boost flexibility, maintainability, and scalability in your code.

Dependency Injection

The hability to inject dependencies trough the controller. According to laravel website,at the service container section we have this:

For example, imagine that you have a UserService and you want to connect to the database through a Database class. I’m going to create a class without using DI and I’ll create a new instance of the database class inside the UserService class:

<?php

class UserService 
{
    private MySQLDatabase $database;

    public function __construct() {
        // Warning: Creating a new instance inside the class !!!
        $this->database = new MySQLDatabase();
    }

    public function getUser($id): string {
        return $this->database->query("SELECT * FROM users WHERE id = $id");
    }
}

class MySQLDatabase 
{
    public function query($sql): string {
        return "User data for ID: $sql";
    }
}

$userService = new UserService();
echo $userService->getUser(1);

The result would be:

That defines an Association in Object-Oriented Programming (OOP). Specifically, it is a Composition Association since the UserService class holds an instance of the MySQLDatabase class and controls its lifecycle.

Composition is a strong form of association. In it, the "container" (or "whole") class owns the instance of the "part" class. This means that:

• If the "container" class is destroyed, the instances of the "part" class are also destroyed.

• The "part" class cannot exist independently of the "container" class.

Now let’s rewrite the class like below, now applying DI (Dependency Injection):

<?php

class UserService 
{
    public function __construct(private MySQLDatabase $database) {}

    public function getUser($id): string {
        return $this->database->query("SELECT * FROM users WHERE id = $id");
    }
}

class MySQLDatabase 
{
    public function query($sql): string {
        return "User data for ID: $sql";
    }
}

// depedency from outside
$mysqlDatabase = new MySQLDatabase();
// user service receives depedency from outside
$userService = new UserService($mysqlDatabase);

echo $userService->getUser(1);

Using Dependency Injection (DI) in this example improves flexibility, testability, and maintainability, but it does not fully decouple the system on its own. While DI allows the database dependency to be passed from the outside instead of being instantiated within UserService, the class is still tied to a specific implementation (MySQLDatabase). This means DI alone does not eliminate dependency on concrete implementations, it just makes injecting dependencies more manageable.

The Coupling Problem: DIP Can Handle It

Although UserService now receives the dependency from the outside, it is still tightly coupled to MySQLDatabase because the dependency type is explicitly defined as MySQLDatabase. If we needed to switch to PostgreSQLDatabase or MongoDBDatabase, we would still have to modify UserService, which violates the Open/Closed Principle (OCP). This is where the Dependency Inversion Principle (DIP) comes in, promoting the use of interfaces instead of concrete implementations.

According to Robert C. Martin (Uncle Bob) blog, definition of DIP:

In our example, by depending on an interface (DatabaseInterface), UserService becomes agnostic to the actual database implementation. This allows us to inject any database class that implements DatabaseInterface, enabling true flexibility and reducing coupling.

Here's the refactored version following DIP:

<?php

interface DatabaseInterface
{
    public function query(string $sql): string;
}

class MySQLDatabase implements DatabaseInterface
{
    public function query(string $sql): string
    {
        return "User data from MySQL for ID: $sql";
    }
}

class PostgreSQLDatabase implements DatabaseInterface
{
    public function query(string $sql): string
    {
        return "User data from PostgreSQL for ID: $sql";
    }
}

class UserService
{
    private DatabaseInterface $database;

    public function __construct(DatabaseInterface $database)
    {
        $this->database = $database;
    }

    public function getUser(int $id): string
    {
        return $this->database->query("SELECT * FROM users WHERE id = $id");
    }
}

// Injecting MySQLDatabase
$mysqlDatabase = new MySQLDatabase();
$userServiceMySQL = new UserService($mysqlDatabase);
echo $userServiceMySQL->getUser(1); 

// Injecting PostgreSQLDatabase
$postgresDatabase = new PostgreSQLDatabase();
$userServicePostgres = new UserService($postgresDatabase);
echo $userServicePostgres->getUser(2);

The result would be:

Do you see? Now UserService is completely agnostic to the database implementation. It doesn’t need to know any details about it, only how to use it through the interface.

The Dependency Inversion Principle (DIP) makes decoupling ideal because UserService no longer needs to know about the specific database implementation it interacts with. Instead of depending on a concrete class like MySQLDatabase, it relies on an abstraction (DatabaseInterface), allowing any database implementation to be injected without modifying UserService.

This makes future changes seamless, if a different database like MongoDBDatabase or PostgreSQLDatabase is needed, it can be integrated simply by implementing the interface. As a result, the system becomes more flexible, maintainable, and aligned with SOLID principles, particularly Open/Closed (OCP) and Dependency Inversion (DIP).

A Good Use Case: The Service Layer / Repository Pattern

I know the examples are too simple, and one thing I don’t like about them is that the query method is inside the UserService class. That’s not ideal in real-world applications.

Usually, service layers, if this is about a Layered Architecture, should not access DB implementations through database classes directly. Using a Repository might be better here since it acts as an abstraction over database operations, separating business logic from data access.

This makes it easier to switch database implementations without modifying service logic, improving maintainability, scalability, and testability. Here is an example using all the concepts examplained until now and adding the repository layer.

The structure would be:

/app/Database/DatabaseInterface.php

<?php

declare(strict_types=1);

namespace App\Database;

interface DatabaseInterface
{
    public function query(string $sql, array $params = []): array;
}

/app/Database/MySQLDatabase.php

<?php

declare(strict_types=1);

namespace App\Database;

use PDO;
use PDOException;
use RuntimeException;
use App\Database\DatabaseInterface;

class MySQLDatabase implements DatabaseInterface
{
    private PDO $connection;

    public function __construct()
    {
        try {
            $this->connection = new PDO("mysql:host=localhost;dbname=app", "user", "password");
            $this->connection->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
        } catch (PDOException $e) {
            throw new RuntimeException(
                "Database connection failed: " . $e->getMessage(), 
                (int) $e->getCode(), 
                $e
            );
        }
    }

    public function query(string $sql, array $params = []): array
    {
        try {
            $stmt = $this->connection->prepare($sql);
            $stmt->execute($params);
            return $stmt->fetch(PDO::FETCH_ASSOC) ?: [];
        } catch (PDOException $e) {
            throw new RuntimeException(
                "Database query failed: " . $e->getMessage(), 
                (int) $e->getCode(), 
                $e
            );
        }
    }
}

/app/Database/PostgreSQLDatabase.php

<?php

declare(strict_types=1);

namespace App\Database;

use PDO;
use PDOException;
use RuntimeException;
use App\Database\DatabaseInterface;

class PostgreSQLDatabase implements DatabaseInterface
{
    private PDO $connection;

    public function __construct()
    {
        try {
            $this->connection = new PDO("pgsql:host=localhost;dbname=app", "user", "password");
            $this->connection->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
        } catch (PDOException $e) {
            throw new RuntimeException(
                "Database connection failed: " . $e->getMessage(), 
                (int) $e->getCode(), 
                $e
            );
        }
    }

    public function query(string $sql, array $params = []): array
    {
        try {
            $stmt = $this->connection->prepare($sql);
            $stmt->execute($params);
            return $stmt->fetch(PDO::FETCH_ASSOC) ?: [];
        } catch (PDOException $e) {
            throw new RuntimeException(
                "Database query failed: " . $e->getMessage(), 
                (int) $e->getCode(), 
                $e
            );
        }
    }
}

/app/Repository/UserRepositoryInterface.php

<?php

declare(strict_types=1);

namespace App\Repository;

interface UserRepositoryInterface
{
    public function getUserById(int $id): ?array;
}

/app/Repository/DbUserRepository.php

<?php

declare(strict_types=1);

namespace App\Repository;

use App\Database\DatabaseInterface;
use App\Repository\UserRepositoryInterface;

class DbUserRepository implements UserRepositoryInterface
{
    public function __construct(private DatabaseInterface $database) {}

    public function getUserById(int $id): ?array
    {
        $sql = "SELECT * FROM users WHERE id = :id";
        return $this->database->query($sql, ['id' => $id]);
    }
}

/app/Repository/InMemoryUserRepository.php

<?php

declare(strict_types=1);

namespace App\Repository;

use App\Repository\UserRepositoryInterface;

class InMemoryUserRepository implements UserRepositoryInterface
{
    private array $users = [
        1 => ['id' => 1, 'name' => 'Alice', 'email' => 'alice@example.com'],
        2 => ['id' => 2, 'name' => 'Bob', 'email' => 'bob@example.com']
    ];

    public function getUserById(int $id): ?array
    {
        return $this->users[$id] ?? null;
    }
}

/app/Service/UserService.php

<?php

declare(strict_types=1);

namespace App\Service;

use App\Repository\UserRepositoryInterface;

class UserService
{
    public function __construct(private UserRepositoryInterface $userRepository) {}

    public function getUserDetails(int $id): ?array
    {
        $user = $this->userRepository->getUserById($id);
        if (empty($user)) {
            return null;
        }
        $user['email'] = substr($user['email'], 0, 3) . '****@' . explode('@', $user['email'])[1];
        return $user;
    }
}

This UserService might look like just a proxy because it simply fetches user details, making it seem redundant. However, in real-world scenarios, service layers handle way more than just CRUD operations.

In complex applications, the service layer is responsible for business rules, validations, aggregating data from multiple sources, handling transactions, caching, and orchestrating different dependencies. The example here is intentionally simple to demonstrate the structure flow, making it easier to understand in the context of an article.

While in this case, it only retrieves a user and masks their email, in production systems, services could be responsible for permission checks, event dispatching, sending notifications, or applying domain logic before returning data. So even though it looks unnecessary now, service layers become crucial as business complexity grows.

/public/index.php

<?php

declare(strict_types=1);

require __DIR__ . '/../vendor/autoload.php';

use App\Database\MySQLDatabase;
use App\Database\PostgreSQLDatabase;
use App\Repository\UserRepository;
use App\Repository\InMemoryUserRepository;
use App\Service\UserService;

$mysqlDatabase = new MySQLDatabase();
$userRepository = new UserRepository($mysqlDatabase);
$userService = new UserService($userRepository);
print_r($userService->getUserDetails(1));

$postgresDatabase = new PostgreSQLDatabase();
$userRepositoryPostgres = new UserRepository($postgresDatabase);
$userServicePostgres = new UserService($userRepositoryPostgres);
print_r($userServicePostgres->getUserDetails(2));

$inMemoryRepo = new InMemoryUserRepository();
$userServiceMemory = new UserService($inMemoryRepo);
print_r($userServiceMemory->getUserDetails(1));

In traditional frameworks like Laravel, Symfony, or Slim, we typically wouldn't manually instantiate dependencies like in this example. Instead, we would leverage the Dependency Injection (DI) container to handle object resolution automatically.

Final Thoughts

The idea is simple: reduce dependency between components. DI handles how dependencies are provided, while DIP ensures code relies on abstractions, not implementations. Together, they keep things modular and adaptable.

They also tie into Agile values, like adaptability and incremental development, helping teams build systems that evolve easily with changing needs.

In short, DI and DIP work hand-in-hand, laying the groundwork for strong, scalable, and modern software designs.

References

• SOLID Principles – https://blog.cleancoder.com/uncle-bob/2020/10/18/Solid-Relevance.html

• Laravel Dependency Injection Container – https://laravel.com/docs/container

• Symfony Dependency Injection Component – https://symfony.com/doc/current/components/dependency_injection.html

• Slim Framework Dependency Injection – https://www.slimframework.com/docs/v4/concepts/di.html