jooservices/laravel-repository

JOOservices Laravel Repository is a PHP 8.5+ Laravel package for trait-based repository composition: CRUD, filtering, ordering, criteria, and request-driven query composition on Eloquent.

Composer package: jooservices/laravel-repository — current line: v4.0.0. Upgrading from 1.x: see UPGRADE-4.0.md.

Install

composer require jooservices/laravel-repository:^4.0

Optionally publish config and stubs:

php artisan vendor:publish --tag=laravel-repository-config
php artisan vendor:publish --tag=laravel-repository-stubs

Quick example

use App\Models\User;
use JOOservices\LaravelRepository\Repositories\Presets\ApiRepository;

/** @extends ApiRepository<User> */
final class UserRepository extends ApiRepository
{
    public function __construct(User $model)
    {
        parent::__construct($model);
    }
}

$repository = app(UserRepository::class);
$user = $repository->find($id);
$users = $repository->filter(['status' => 'active'])->orderBy(['-created_at'])->paginate(15);

Scaffold:

php artisan make:repository UserRepository --model=User --preset=api

See the Cookbook for profiles, value rules, soft deletes, locking, and debug helpers.

What is supported today

• trait-based composition through segregated contracts and traits
• presets ApiRepository / ReadRepository and Artisan make:repository
• CRUD (HasCrud) including findMany, findBy, updateOrCreate, upsert
• filters, pagination, and simplePaginate (HasFilter)
• ordering and sort shorthand (HasOrder)
• request-driven queries (HasRequestQuery) with allowlists / strict mode
• named filters, field selection, scopes, relation filters, aggregate includes
• operators including exact, partial, before, after, date, jsonContains
• criteria (HasCriteria), soft deletes, locking, SQL debug
• named query profiles with restrictive baseline semantics
• cursor pagination that preserves sparse and Expression projections
• opt-in cache wrappers (HasCache) with stable typed cache keys
• reusable Filter and Order value objects

Important boundaries

• capabilities are opt-in through traits; nothing is globally implied
• query state is lazy and resets after terminal operations
• RequestQueryParser supports only the documented clause families
• relation methods should declare a Relation return type (or use an explicit trust / allowlist path)

Documentation

• Documentation Hub
• Installation
• Quick Start
• Request Query Support
• Examples
• Cookbook
• Upgrade 4.0
• Changelog

Development

composer lint
composer test
composer check

Contributor workflow:

• Contributing
• Security Policy
• Setup
• Coding Standards
• Testing
• CI/CD
• Release Process

Project agents: AGENTS.md (workspace policy in the JOOservices root AGENTS.md).

License

This project is licensed under the MIT License.