L5 Repository Laravel Package

Getting Started

Begin by installing the package via Composer (composer require andersao/l5-repository) and registering the service provider (auto-discovered in Laravel 5.5+). For Laravel 13 projects, ensure compatibility by using the updated 4.0.0 release. Generate your core repository and model using php artisan make:entity Post—this scaffolds a repository, model, controller, validator, and presenter skeleton, along with a service provider for interface binding. For simple cases, create a minimal repository class extending BaseRepository and implement the model() method to return your Eloquent model class name. From there, inject the repository into your controller and start using methods like all(), find(), paginate(), and create() without touching query builders directly.

Implementation Patterns

Use the repository as a single source of data access logic—controllers should never query the database directly. Leverage Criteria to encapsulate reusable query logic (e.g., filtering by authenticated user, active status, date ranges); push them via pushCriteria() or rely on the included RequestCriteria to auto-parse request parameters like ?filter=active&order_by=name. Configure caching with CacheableInterface implementations (e.g., setCacheTime(), skipCache()) for expensive queries. Use Presenters with Fractal transformers to normalize API responses, especially for versioned or multi-format outputs. Bind repositories via interfaces (e.g., PostRepositoryInterface → PostRepositoryEloquent) in a custom service provider to enable testability and flexibility. Employ the generator (make:repository, make:criteria, make:validator) to enforce consistency across modules.

For Laravel 13 projects, ensure your config/app.php includes the updated package provider and alias bindings. If migrating from older Laravel versions, verify that any custom scopes or criteria are compatible with Laravel 13’s Eloquent changes (e.g., query builder improvements).

Gotchas and Tips

⚠️ While the package now supports Laravel 13 (v4.0.0), some legacy features may still target older Laravel versions. Always test migrations thoroughly, especially if upgrading from Laravel 5.x or 8.x. When extending repositories, override resetModel() cautiously to avoid stale queries after state changes (e.g., after applying scopes or criteria). Validator rules defined in repositories via $rules or external classes require proper skipValidation() handling—remember to call skipValidation(false) if validation is desired.

Cache keys are derived from method + args; use getCacheKey() for debugging mismatches, and ensure your cache repository supports serialization of criteria/scopes if used with caching. Presenters must implement transform() on the model or return structured arrays—be wary of double-transforming if manually calling repository->get() vs. repository->paginate() in the same request. For findWhere() syntax, use array syntax for custom operators (e.g., ['field', '>', 5] or ['date_col', 'DATE', '2024-01-01'])—errors often stem from misformatting these.

For Laravel 13 compatibility, ensure your custom scopes or query modifications align with the latest Eloquent API. If using API resources or Fractal transformers, verify that any custom logic in presenters adheres to Laravel 13’s updated service container and dependency injection. Always use skipPresenter(true) when returning raw data for background jobs or internal logic to avoid presenter overhead.