Laravel Repository

A clean and flexible base repository package for Laravel that simplifies data access, enforces the Repository Pattern, and keeps your application code organized, testable, and maintainable.

This package provides a reusable BaseRepository implementation with common Eloquent operations and a powerful filtering system.

Table of Contents

1. Features
2. Requirements
3. Installation
4. Basic Usage
5. Available Methods
6. Filtering System
7. Query Builder & Chainable Methods
8. Persisting Queries
9. CRUD Operations
10. Advanced Usage
11. Testing
12. Contributing
13. License

Features

• Clean BaseRepository implementation
• Built‑in query builder helpers
• Dynamic filtering system with multiple operators
• Support for nested and OR conditions
• Relation filtering using dot notation
• Fluent query chaining
• Works with Laravel 9+
• Fully testable and extendable

Requirements

• PHP >= 8.0
• Laravel / Illuminate components >= 9.0

Installation

  composer require mrtolouei/laravel-repository

No configuration or service provider registration is required.

Basic Usage

Create a repository for your model by extending the BaseRepository.

Example Model

App\Models\User

Create Repository

namespace App\Repositories;

use App\Models\User;
use Repository\Repositories\BaseRepository;

class UserRepository extends BaseRepository
{
    public function __construct(User $model)
    {
        parent::__construct($model);
    }

    protected array $allowedFilters = [
        'email',
        'name',
        'age',
        'created_at',
    ];
}

Available Methods

The BaseRepository provides many commonly used data access methods.

Create

$user = $repository->create([
    'email' => 'john@example.com',
    'name' => 'John'
]);

Find

$user = $repository->find($id);

$user = $repository->findOrFail($id);

Update

$repository->update($id, [
    'name' => 'Updated Name'
]);

Delete

$repository->delete($id);

Restore (Soft Deletes)

$repository->restore($id);

Insert Multiple

$repository->insert([
    ['email' => 'a@example.com'],
    ['email' => 'b@example.com']
]);

Where

$repository->where('age', '>', 18)->all();

OR Where

$repository
    ->where('age', 18)
    ->orWhere('age', 25)
    ->all();

Where In

$repository->whereIn('id', [1,2,3])->all();

Where Not In

$repository->whereNotIn('id', [4,5])->all();

Order

$repository->orderBy('created_at', 'desc')->all();

Limit

$repository->limit(10)->all();

Pagination

$repository->paginate(15);

Aggregate Functions

$repository->count();

$repository->sum('amount');

$repository->avg('rating');

Existence Check

$repository->where('email', 'john@example.com')->exists();

Filtering System

The package includes a powerful filtering trait that allows structured filtering from arrays (useful for APIs).

Only fields listed in $allowedFilters can be filtered.

Example

$repository->filter([
    'age' => ['gte' => 18],
    'email' => ['like' => 'gmail']
])->all();

Supported Operators

Using Filters

Example usage in a controller:

public function index(Request $request)
{
    $repo = new UserRepository(new User());

    $users = $repo
        ->filter($request->query())  // apply filters
        ->orderBy('created_at', 'desc')
        ->paginate(15);

    return response()->json($users);
}

Example filter input (from query parameters or request body):

{
  "email": {
    "like": "example.com"
  },
  "is_active": true,
  "or": [
    {
      "age": {
        "gte": 30
      }
    },
    {
      "roles.id": {
        "in": [
          1,
          2,
          3
        ]
      }
    }
  ]
}

Explanation

• email.like: Finds users with email containing “example.com”
• is_active: Equals true
• or group: Matches users aged 30+ or belonging to roles with IDs 1, 2, 3

Query Builder & Chainable Methods

All major query methods remain chainable:

Persisting Queries

Preserve query state across multiple operations:

$repo->persistQuery()
    ->where('is_active', true)
    ->orderBy('created_at', 'desc');

$firstActive = $repo->first();
$activeUsers = $repo->all();

Without calling persistQuery(), queries auto‑reset after each operation.

CRUD Operations

// Create
$newUser = $userRepo->create([
    'name' => 'Ali',
    'email' => 'ali@example.com',
]);

// Update
$updated = $userRepo->update($newUser->id, ['name' => 'Ali Tolouei']);

// Delete (soft)
$deletedCount = $userRepo->delete($newUser->id);

// Restore
$restoredCount = $userRepo->restore($newUser->id);

// Insert many
$userRepo->insert([
    ['name' => 'John', 'email' => 'john@example.com'],
    ['name' => 'Jane', 'email' => 'jane@example.com'],
]);

// First or create
$user = $userRepo->firstOrCreate(['email' => 'user@example.com'], ['name' => 'User']);

// Update or create
$user = $userRepo->updateOrCreate(['email' => 'user@example.com'], ['name' => 'Updated']);

Advanced Usage

Powerful nested filter combinations with chaining:

$users = $userRepo
    ->filter([
        'is_active' => true,
        'roles.id' => ['in' => [1, 5]],
        'or' => [
            ['created_at' => ['gte' => '2024-01-01']],
            ['name' => ['like' => 'Ali']],
        ],
    ])
    ->with(['profile', 'posts'])
    ->orderBy('created_at', 'desc')
    ->paginate(10);

Testing

Run tests using PHPUnit:

  vendor/bin/phpunit

Contributing

1. Fork the repository
2. Create a feature branch (feature/awesome-feature)
3. Commit your changes (git commit -m 'Add new feature')
4. Push to the branch (git push origin feature/awesome-feature)
5. Open a Pull Request

License

This package is open-sourced software licensed under the MIT license.