Laravel Repository Pattern Laravel Package

Getting Started

1. Install the release that matches your framework. 0.2.0 is the first release with an explicit Laravel 11 constraint in composer.json. On Laravel 11 / PHP 8.2+, require ^0.2; on older Laravel 10 apps you can stay on 0.1.5 until you upgrade.

   composer require sostheblack/laravel-repository-pattern:^0.2
   

2. Confirm auto-discovery. The package ships a service provider; after install run php artisan about and check the package is listed. In Laravel 11 providers are registered via bootstrap/providers.php, but package discovery is unchanged — you should not need to add anything manually unless you disabled discovery.
3. Look first at the package README and any published config. In particular find the generator command name (typically php artisan make:repository) and the default namespace/stub paths. These determine where generated interfaces and implementations land (app/Repositories, app/Contracts, etc.).
4. First use case — wrap one read-heavy Eloquent model. Generate a repository for a model like Invoice, bind its interface in a service provider (or rely on the package's binding convention), inject the interface into a controller, and move a couple of scoped queries (forCustomer, unpaid, withRelations) out of the controller. This gives you an immediate, low-risk win and validates the binding wiring before you refactor broadly.

Implementation Patterns

• Contract-first injection. Depend on the generated interface in controllers, jobs, and services — never on the concrete Eloquent repository. This is the only way the pattern pays off for testing and for swapping implementations later.

  public function __construct(private InvoiceRepositoryInterface $invoices) {}
  

• Generator-driven consistency. Use the Artisan generator for every new repository so stubs, namespaces, and bindings stay aligned. Hand-created repositories tend to drift from the package's expected contract and base class.
• Thin repositories, rich queries. Put reusable query scopes and eager-loading decisions in the repository (with('lines', 'customer'), date filters, status filters). Keep business rules in services/actions; the repository should return models/collections, not make domain decisions.
• Criteria/filter objects if the package exposes them. Where supported, express cross-cutting filters as criteria and compose them per call. This keeps method signatures stable as filtering requirements grow.
• Service provider binding. Register interface → implementation bindings in a dedicated RepositoryServiceProvider rather than scattering them in AppServiceProvider. In Laravel 11 add that provider to bootstrap/providers.php.
• Testing. Because consumers type-hint interfaces, you can bind an in-memory fake in tests:

  $this->app->bind(InvoiceRepositoryInterface::class, FakeInvoiceRepository::class);
  

  For integration tests, resolve the real repository from the container so you exercise actual query behaviour.
• Pagination and caching. Keep pagination (paginate, simplePaginate) behind repository methods so the HTTP layer stays consistent. If you add caching, do it in a decorator around the interface rather than inside the Eloquent implementation — that preserves the swap-ability the pattern is meant to provide.
• Incremental adoption. Introduce repositories per aggregate root, not per table. A handful of well-scoped repositories around your most-queried models is more maintainable than a one-to-one wrapper over every Eloquent model.

Gotchas and Tips

• 0.2.0 is a compatibility release, not an API release. The only listed change is the Laravel 11 composer.json update. There are no new features or documented breaking changes, so an upgrade from 0.1.5 should be low risk — but re-run your test suite and check that the package's service provider still registers cleanly under Laravel 11's streamlined bootstrap.
• Watch the transitive constraints. The Laravel 11 bump may also raise the minimum PHP version and illuminate/* constraints. Run composer why-not / composer update --dry-run before merging into an app with pinned dependencies.
• Don't let the abstraction leak. Returning Builder instances or accepting raw $columns/$where arrays from callers defeats the purpose. Keep return types to models, collections, paginators, or scalars.
• Beware the "repository for everything" trap. Wrapping trivial find() calls adds indirection without value. Reserve repositories for models with non-trivial query logic or where a data-source swap/mocking boundary is genuinely useful.
• Binding mistakes are the most common failure. A Target [XInterface] is not instantiable error almost always means the interface isn't bound or the provider isn't registered (especially after moving to bootstrap/providers.php in Laravel 11). Verify with php artisan tinker → app(XInterface::class).
• Eager-loading drift. If controllers pass relationships ad hoc, the repository's loading strategy becomes inconsistent. Standardise with() defaults in the repository and expose explicit methods for variant loading.
• Extension points. The package's base repository class and generator stubs are the intended customisation seams. If you need shared behaviour (soft-delete filtering, tenant scoping), extend the base class in your app rather than editing vendor files, and republish/override stubs so future generated repositories inherit your conventions.
• Pin the version in CI. Because this is a small, low-velocity package (0.x, single-maintainer), pin to ^0.2 and review changelogs on each bump; the 0.x versioning signals that minor releases can still carry compatibility-affecting changes such as this Laravel 11 constraint update.