Laravel Repository Toolkit

Laravel Repository is an Eloquent-backed repository toolkit for Laravel applications. It gives you a reusable BaseRepository, contracts for CRUD and criteria-based query composition, HTTP-driven filtering with RequestCriteria, and Artisan generators for repositories and criteria.

Quick Start

composer require thatobabusi/laravel-repository
php artisan vendor:publish --tag=repository-config
php artisan make:repository User

The generated repository only needs to point at its Eloquent model:

namespace App\Repositories;

use App\Models\User;
use Laravel\Repository\Eloquent\BaseRepository;

class UserRepository extends BaseRepository
{
    protected array $fieldSearchable = [
        'name' => 'like',
        'email' => '=',
    ];

    public function model(): string
    {
        return User::class;
    }
}

Use it from controllers, services, jobs, or actions:

use App\Repositories\UserRepository;
use Illuminate\Http\Request;

class UserController extends Controller
{
    public function __construct(private UserRepository $users) {}

    public function index(Request $request)
    {
        return $this->users->paginate(25);
    }
}

See Getting Started for the complete walkthrough.

Documentation

Complete documentation is organized into focused guides:

Getting Started

• Installation & Setup - Install the package, publish config, and create your first repository.
• Configuration - Configure pagination, request parameter names, and generator paths.

Using the Toolkit

• Getting Started - Generate, bind, inject, and extend repositories.
• Criteria - Build reusable query modifiers and manage the criteria stack.
• RequestCriteria - Add URL-driven search, filter, sorting, eager loading, and counts.
• Scope Query - Apply one-off anonymous query constraints.

Reference

• Method Reference - Every repository method with signatures and examples.
• Contracts - RepositoryInterface, CriteriaInterface, and RepositoryCriteriaInterface.
• Artisan Commands - make:repository and make:criteria.

Support

• Version Compatibility - Laravel and PHP support matrix.
• Troubleshooting - Common errors and fixes.
• FAQ - Short answers to common questions.
• Contributing - How to contribute docs, tests, and package changes.
• Changelog - Release history.

Key Features

• Eloquent-backed BaseRepository with common CRUD and query operations
• Criteria stack for reusable, composable query filters
• RequestCriteria for HTTP-driven search, filtering, ordering, eager loading, and relation counts
• Chainable query helpers: orderBy, with, withCount, has, whereHas, hidden, visible, and scopeQuery
• Artisan generators for repositories and criteria
• Configurable generator paths and root namespace
• Laravel package auto-discovery
• Laravel 11, 12, and 13 support

Version Compatibility

See Version Compatibility for details.

Example: HTTP-Driven Filtering

Push RequestCriteria in a controller and expose a flexible listing endpoint:

use App\Repositories\UserRepository;
use Illuminate\Http\Request;
use Laravel\Repository\Criteria\RequestCriteria;

class UserController extends Controller
{
    public function index(Request $request, UserRepository $users)
    {
        $users->pushCriteria(new RequestCriteria($request));

        return $users->paginate(25);
    }
}

Supported query parameters include:

GET /users?search=john&orderBy=name&sortedBy=asc&filter=id;name;email&with=profile

See RequestCriteria for all supported parameters and security notes.

Example: Custom Criteria

php artisan make:criteria ActiveUsers

namespace App\Criteria;

use Laravel\Repository\Contracts\CriteriaInterface;
use Laravel\Repository\Contracts\RepositoryInterface;

class ActiveUsersCriteria implements CriteriaInterface
{
    public function apply(mixed $model, RepositoryInterface $repository): mixed
    {
        return $model->where('active', true);
    }
}

$users = $this->users
    ->pushCriteria(new ActiveUsersCriteria())
    ->orderBy('name')
    ->paginate(25);

Testing

composer test

Credits

• Thato Babusi
• Prettus Laravel Repository for the original community pattern many Laravel teams know
• All Contributors

License

The MIT License (MIT). Please see License File for more information.