Laravel Repositories Laravel Package

Getting Started

1. Install (with caution). composer require saritasa/laravel-repositories — read the released version first. 4.0.0 explicitly declares Laravel 11 compatibility, so it is the version to target on Laravel 11. On Laravel 12+ there is still no declared support; verify resolution or copy src/ into app/Repositories/ and treat it as vendored code.
2. Read the source first. There is essentially one class that matters: the abstract BaseRepository. Open it and the repository contract side by side — this is a thin wrapper over Eloquent, so its whole value is the handful of CRUD/query helpers it provides. Don't expect criteria, presenters, or caching layers.
3. No config to publish. There is typically no service provider config, migration, or published file. Your setup work is creating your own repository classes and binding them.
4. First use case — a single aggregate:

final class UserRepository extends BaseRepository implements UserRepositoryInterface
{
    protected $model = User::class; // set explicitly; don't rely on name inference
}

// AppServiceProvider::register()
$this->app->bind(UserRepositoryInterface::class, UserRepository::class);

// Controller / Action
public function show(UserRepositoryInterface $users, int $id): UserResource
{
    return new UserResource($users->find($id));
}

That's the whole happy path: interface → implementation → injected into a controller or action.

Implementation Patterns

• One repository per aggregate root. Bind an interface (UserRepositoryInterface) for every concrete repo, and inject the interface — not the class — into controllers, actions, jobs, and listeners. This keeps tests mockable and lets you swap implementations later.
• Extend, don't leak. Treat BaseRepository as your baseline CRUD surface (find, all, create, update, delete, pagination). Add domain methods (findActiveByEmail, paginateRecentForTeam) rather than exposing a generic query builder to callers.
• Keep return types Laravel-native. Return models and collections, not arrays or DTOs. This preserves relationships, casts, accessors, and authorization policies downstream.
• Eager loading at the repository boundary. Use the base with()/query helpers to preload relationships in read methods so controllers and resources never trigger N+1. Make the eager-load list a parameter or a per-method default.
• Writes belong in a service. Repositories are for persistence; if a business operation touches more than one repository, wrap it in a service/action with DB::transaction(). Don't grow the repo into an orchestrator.
• Test through the interface. Swap the binding for a fake in feature tests, or hit an in-memory SQLite connection for integration-style tests of the concrete repository. Because the package is a thin Eloquent wrapper, most of your meaningful tests are really Eloquent tests.
• Filter/sort composition. Where the base offers where/orderBy/scope-style helpers, chain them inside named repo methods and keep the call sites declarative.

Gotchas and Tips

• 4.0.0 is a compatibility-only major. The only stated change is "declare compatibility with Laravel 11" — no new features, no deprecations, no API changes called out. Treat it as a composer.json constraint bump: expect zero source diffs, but expect your illuminate/* range to shift. If you're still on Laravel 10, read the 4.0.0 constraint before upgrading — a major bump can drop the older framework from the allowed range and stall composer update entirely.
• Still effectively unmaintained. One release does not restore a support contract. Pin the version in composer.json ("saritasa/laravel-repositories": "4.0.0" or ^4.0), and fork/copy the base class into app/Repositories/AbstractRepository the moment the dependency causes upgrade friction.
• Very low adoption (2 stars, 0 dependents). Docs and examples are minimal; you will learn the API by reading src/. Budget for that.
• Model inference is convention-based. If the base derives the model from the repository class name, namespaced or reworded classes (AdminUserRepository → User) can silently resolve wrong. Always set $model explicitly.
• No criteria/presenter layer. Unlike prettus/l5-repository, you get no request-criteria, no presenters, no transformers. Build those yourself or pick a maintained alternative if you need them.
• Override points are narrow. Typically getModel()/newQuery() (or equivalent) and the CRUD methods. Overriding newQuery() is the cleanest place to inject default ordering/scopes — but scope it deliberately, or every query inherits it.
• Eager-loading defaults can bite. If all()/find() don't preload, watch for N+1 in list endpoints. Be explicit with with().
• create() vs save() semantics. Mass-assignment via create() respects $fillable/$guarded; direct save() on a hydrated model does not. Mixing the two in one repo is a common source of "why did this field save?" bugs.
• Compatibility matrix now matters more than the changelog. 4.0.0 = Laravel 11. Nothing declares Laravel 12 support, and the 3.x line was the Laravel 10/11-era target. Test on your actual framework version rather than trusting the README; run your repository test suite against the upgraded dependency before merging.
• Keep the base class small. The temptation with a "repository package" is to dump every query into the base. Prefer many small concrete repos with named methods; the base should stay a skeleton you rarely touch.