README

Elegant data layer abstraction for Laravel using the Repository Pattern with powerful criteria-based filtering. Keep your controllers clean and your data logic reusable.

Features

• 🏗️ Repository Pattern — Abstract Eloquent models behind clean interfaces
• 🔍 Criteria System — Composable, reusable query filters (where, like, date, JSON, null, in)
• ⚡ Zero Boilerplate — Artisan generators for repositories, services, and criteria
• 🔗 Fluent Chaining — Chain any Eloquent Builder method directly on repositories
• 🔄 Auto Query Reset — Query state resets after execution, preventing stale queries
• 📦 Laravel Auto-Discovery — Install and go, no manual provider registration

Requirements

• PHP 8.1+
• Laravel 9.0+

Installation

composer require bytetcore/serpo

Publish the configuration:

php artisan vendor:publish --tag=serpo-config

Quick Start

1. Generate a Repository

# Basic repository
php artisan make:repository UserRepository

# With a specific model
php artisan make:repository UserRepository --model=User

# With a corresponding service class
php artisan make:repository UserRepository --model=User --service

2. Generate a Service

php artisan make:service UserService

3. Generate a Custom Criteria

php artisan make:criteria ActiveUserCriteria

Usage

Basic Repository

namespace App\Repositories;

use App\Models\User;
use ByteTCore\Serpo\Repositories\BaseRepository;

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

Query Methods

$repo = app(UserRepository::class);

// Get all records
$users = $repo->all();

// Get with specific columns
$users = $repo->get(['id', 'name', 'email']);

// Get first record
$user = $repo->first();

// Get first or throw exception
$user = $repo->firstOrFail();

// Get latest record
$user = $repo->last();
$user = $repo->last('updated_at');

Eloquent Builder Chaining

All Eloquent Builder methods are available directly on the repository:

$users = $repo->where('active', true)
    ->orderBy('name')
    ->limit(10)
    ->get();

$count = $repo->where('role', 'admin')->count();

$users = $repo->with('posts')->whereHas('posts')->get();

Criteria-Based Filtering

Define reusable filters in your repository using the fluent Condition API:

use ByteTCore\Serpo\Criteria\Condition;
use App\Criteria\ActiveUserCriteria;

class UserRepository extends BaseRepository
{
    protected function conditions(): array
    {
        return [
            'status'   => Condition::where(),
            'keyword'  => Condition::like('name', 'email')->or(),
            'min_age'  => Condition::where('age')->gte(),
            'created_from' => Condition::date('created_at')->gte(),
            'price_between' => Condition::between('price'),
            'tags'     => Condition::whereIn('tags'),
            'deleted'  => Condition::whereNull('deleted_at'),
            'birth_year' => Condition::year('birth_date'),
            'active'   => Condition::custom(ActiveUserCriteria::class),
            'search'   => Condition::orGroup(
                Condition::like('name'),
                Condition::where('email'),
            ),
        ];
    }

    public function __construct(User $model)
    {
        parent::__construct($model);
    }
}

Apply filters from request data:

// In your controller
$users = $repo->filters($request->only(['status', 'keyword', 'min_age']))->get();

Controlling Filter Application Order

By default, filters are applied in the order declared in conditions(). Override filterOrder() to change the order without reordering the conditions() map:

protected function filterOrder(): array
{
    return [
        'keyword',  // applied first
        'status',   // applied second
    ];
    // 'min_age', 'created_from', ... — any keys not listed are appended in original order
}

Available Criteria

Fluent modifiers

Detailed Criteria Walkthrough

Database Comparisons

'status'     => Condition::where(),              // WHERE status = input
'price_over' => Condition::where('price')->gte(), // WHERE price >= input
'not_admin'  => Condition::where('role')->not(), // WHERE role != input

Search & Text (LikeCriteria)

'keyword' => Condition::like('title', 'content', 'author')->or(),
// WHERE (title LIKE '%val%' OR content LIKE '%val%' OR author LIKE '%val%')

'prefix' => Condition::like('name')->startsWith(),
// WHERE name LIKE 'val%'

'suffix' => Condition::like('name')->endsWith(),
// WHERE name LIKE '%val'

Ranges (BetweenCriteria)

'price_range' => Condition::between('price'),
// expects $request->price_range = [100, 500]

Working with Dates

'created_at'  => Condition::date('created_at'),
'birth_year'  => Condition::year('birth_date'),
'birth_month' => Condition::month('birth_date'),

Sets & Arrays

'tags'   => Condition::whereIn('tags'),
'ignore' => Condition::whereNotIn('id'),

Nullity Checks

'unverified' => Condition::whereNull('email_verified_at'),
'active'     => Condition::whereNotNull('email_verified_at'),

JSON Columns

'has_tag' => Condition::jsonContains('tags'),

Dynamic Sorting

'sort_by' => Condition::orderBy('created_at')->desc(),

Nested Groups

Combine different criteria types in a single parenthesized group:

'search' => Condition::orGroup(
    Condition::like('name'),
    Condition::where('email'),
),
// WHERE ((name LIKE '%val%') OR (email = 'val'))

'date_range' => Condition::andGroup(
    Condition::date('created_at')->gte(),
    Condition::date('created_at')->lte(),
),
// WHERE ((DATE(created_at) >= 'val') AND (DATE(created_at) <= 'val'))

Custom Criteria

Create your own criteria by extending BaseCriteria, then reference it with Condition::custom():

namespace App\Criteria;

use ByteTCore\Serpo\Criteria\BaseCriteria;
use Illuminate\Database\Eloquent\Builder;

class ActiveWithRecentPostsCriteria extends BaseCriteria
{
    public function apply(Builder $query): void
    {
        $query->where('active', true)
            ->whereHas('posts', fn (Builder $q) => $q->where('created_at', '>=', now()->subDays(30)));
    }
}

// In your repository:
use App\Criteria\ActiveWithRecentPostsCriteria;

protected function conditions(): array
{
    return [
        'recent_active' => Condition::custom(ActiveWithRecentPostsCriteria::class),
    ];
}

Auto-Reset Behavior

By default, the query builder resets after each execution to prevent stale state:

$active = $repo->where('active', true)->get();   // query resets after get()
$all = $repo->all();                              // fresh query — returns all records

Disable auto-reset when you need to reuse the query:

$repo->withoutAutoReset()
    ->where('active', true);

$count = $repo->count();       // same filtered query
$users = $repo->get();         // same filtered query

Configuration

// config/serpo.php
return [
    'repository' => [
        'namespace' => env('SERPO_REPOSITORY_NAMESPACE', 'Repositories'),
    ],
    'service' => [
        'namespace' => env('SERPO_SERVICE_NAMESPACE', 'Services'),
    ],
    'criteria' => [
        'namespace' => env('SERPO_CRITERIA_NAMESPACE', 'Criteria'),
    ],
];

Testing

composer test

Changelog

See CHANGELOG.md for release history.

Contributing

See CONTRIBUTING.md for guidelines.

License

Licensed under the Apache License 2.0.