Complete Guide to Laravel Repository Pattern: Implementation & Best Practices

Introduction to Repository Pattern
Why Use the Repository Pattern?
Architecture Comparison
Implementation Steps
Improvement: Base Repository (Generic)
When Should You Use This Pattern?
Conclusion

Introduction to Repository Pattern

The Repository Pattern is a design pattern that acts as an abstraction layer between the application’s domain logic and the data access layer. Simply put, a Repository is a component that encapsulates data access logic.

With this pattern, the “consumer” or client of the repository (such as a Controller or Service) doesn’t need to know if the data comes from Eloquent ORM, an external API, cache, or a flat file. The consumer only needs to know what methods are available in the repository interface.

Why Use the Repository Pattern?

Even though Laravel’s Eloquent is very powerful, using the Repository Pattern provides several significant advantages:

Decoupling: The application logic is not directly tied to a specific ORM. If you ever want to change the data model or data source, you only need to change the repository implementation.
Centralized Logic: Complex database queries are no longer scattered across various Controllers but are centralized in one easily manageable place.
Testability: It makes unit testing easier because you can ‘mock’ the repository interface without having to interact directly with the database.
Clean Code: Keeps Controllers “skinny” because query logic has been moved to the repository layer.

Architecture Comparison

Here is a comparison between the traditional Laravel MVC flow and the flow using the Repository Pattern:

graph TD
    subgraph "Standard Laravel MVC"
        C1[Controller] --> M1[Eloquent Model]
        M1 --> DB1[(Database)]
    end
    
    subgraph "Repository Pattern Architecture"
        C2[Controller] --> I[Repository Interface]
        I --> R[Repository Implementation]
        R --> M2[Eloquent Model]
        M2 --> DB2[(Database)]
    end

Implementation Steps

Let’s practice with a simple case study: User Management.

1. Create Model and Migration

Make sure you already have a User model.

php artisan make:model User -m

2. Create Repository Interface

The interface defines the contract or methods that must be available. Create it in app/Repositories/Interfaces/UserRepositoryInterface.php.

<?php

namespace App\Repositories\Interfaces;

interface UserRepositoryInterface
{
    public function all();
    public function findById($id);
    public function create(array $details);
    public function update($id, array $newDetails);
    public function delete($id);
}

3. Create Repository Implementation

This implementation will use Eloquent to interact with the database. Create it in app/Repositories/Eloquent/UserRepository.php.

<?php

namespace App\Repositories\Eloquent;

use App\Models\User;
use App\Repositories\Interfaces\UserRepositoryInterface;

class UserRepository implements UserRepositoryInterface
{
    public function all()
    {
        return User::all();
    }

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

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

    public function update($id, array $newDetails)
    {
        return User::whereId($id)->update($newDetails);
    }

    public function delete($id)
    {
        User::destroy($id);
    }
}

4. Register in Service Provider

So Laravel knows which implementation to use when the interface is called (Dependency Injection), we need to bind it in AppServiceProvider.php.

public function register()
{
    $this->app->bind(
        \App\Repositories\Interfaces\UserRepositoryInterface::class,
        \App\Repositories\Eloquent\UserRepository::class
    );
}

5. Usage in Controller

Now, the Controller no longer calls User::all() directly but through the Interface.

use App\Repositories\Interfaces\UserRepositoryInterface;

class UserController extends Controller
{
    private $userRepository;

    public function __construct(UserRepositoryInterface $userRepository)
    {
        $this->userRepository = $userRepository;
    }

    public function index()
    {
        $users = $this->userRepository->all();
        return view('users.index', compact('users'));
    }
}

Improvement: Base Repository (Generic)

For large applications, you don’t want to write the same CRUD methods repeatedly for every repository. You can create a Base Repository.

classDiagram
    class BaseRepositoryInterface {
        <<interface>>
        +all()
        +find(id)
        +create(data)
    }
    class EloquentBaseRepository {
        #model
        +all()
        +find(id)
    }
    class UserRepository {
        +findActiveUsers()
    }
    
    BaseRepositoryInterface <|-- EloquentBaseRepository
    EloquentBaseRepository <|-- UserRepository

BaseRepository.php:

abstract class BaseRepository implements BaseRepositoryInterface {
    protected $model;

    public function __construct(Model $model) {
        $this->model = $model;
    }

    public function all() {
        return $this->model->all();
    }
    // ... other methods
}

When Should You Use This Pattern?

✅ Use If:

Your project is large and complex.
You plan to use Unit Testing extensively.
There’s a possibility of changing data sources (e.g., migrating from SQL to NoSQL).
You want to strictly separate domain logic from data access logic.

❌ Avoid If (YAGNI - You Ain’t Gonna Need It):

Your project is small or a simple MVP.
You only perform standard CRUD operations without complex logic.
You want very fast development speed without additional file overhead.

Conclusion

The Repository Pattern is a great tool for building maintainable and testable Laravel applications. By separating the data access layer, you make your code more flexible for future changes. However, always consider the complexity of your project before deciding to use it.

Have you tried the Repository Pattern in your project? Or do you find it unnecessary? Let’s discuss in the comments! 💬

Resources

Related Articles:

Table of Contents