jooservices/laravel-repository

jooservices/laravel-repository

jooservices/laravel-repository is a PHP ^8.5 Laravel package for composing Eloquent repositories from opt-in traits, with CRUD, filtering, ordering, and request-driven query capabilities.

Upgrade note: The current release line is v4.0.0. Review UPGRADE-4.0.md before upgrading from 1.x; the major release includes API and behavior changes.

Features

• Compose repository capabilities with traits and segregated contracts.
• Use the ApiRepository and ReadRepository presets or generate a repository with Artisan.
• Add CRUD, filters, ordering, criteria, soft deletes, locking, cache wrappers, and cursor pagination as needed.
• Build request-driven queries with allowlists, strict mode, named filters, field selection, scopes, relation filters, aggregate includes, and query profiles.
• Reuse Filter and Order value objects.

Requirements

• PHP ^8.5
• Laravel 12 or 13
• Composer

Installation

composer require jooservices/laravel-repository:^4.0

Laravel package discovery registers the service provider. To publish the optional config or repository stubs:

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

Quick start

Extend the API preset for a repository with CRUD, filtering, ordering, reads, and request-query support:

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);

Or scaffold a repository with the api preset:

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

Design notes

• Capabilities are opt-in; the package does not apply repository behavior globally.
• Fluent query state is lazy and resets after terminal operations such as get() and paginate().
• Request-query clauses and relation discovery follow the supported rules in Request Query Support.

Documentation

• Documentation hub
• Installation
• Quick start
• Trait-based composition
• CRUD, filtering, and ordering
• Request-query support
• Examples and cookbook
• Upgrade guide
• Changelog
• Workflow reference

Development

Install dependencies and run the configured quality commands:

composer install
composer lint
composer test
composer check
composer ci

See contributor guidance, development setup, coding standards, testing, and CI/CD.

Community

• Contributing
• Security policy
• Code of Conduct
• Support
• Governance

License

This project is licensed under the MIT License.