Eloquent Repository Laravel Package

Getting Started

• Install with composer require jetcod/eloquent-repository:^1.7. This release requires PHP 8.1+, Laravel 12 or 13, the Carbon 3 line, and Testbench/migration autoloading as shipped by the package—verify your composer.json platform constraints before pulling it into an existing app.
• First stop is the package's base repository class and any shipped config file. Publish the config (php artisan vendor:publish --tag=...) if the package exposes one, and skim the README for the canonical "extend the base repository" example before writing your own abstractions.
• Your first use case: pick one read-heavy Eloquent model, create a UserRepository that extends the package's base class, and replace a couple of Model::where(...)->get() calls in a controller or service with repository methods. This keeps the change surface small and shows you the base class API before you commit to it project-wide.
• If you're upgrading from an earlier 1.x, the release notes are clear that no application-facing repository APIs changed — the work is almost entirely environment/composer plumbing, so start by bumping the platform and running your existing test suite.

Implementation Patterns

• Extend, don't reimplement. The base repository already wraps the common Eloquent operations. Subclass it, declare the model it manages, and add only the domain-specific methods (findActiveByEmail, paginateWithRelations) your app actually needs. Fighting the base class is the fastest way to make this package feel heavy.
• Bind interfaces in a service provider. Define a UserRepositoryInterface, implement it with your concrete repository, and bind it in a RepositoryServiceProvider. This is what makes the pattern worth the ceremony: controllers and services depend on the interface, and you can swap the implementation (or a fake) without touching call sites.
• Use criteria (or equivalent query objects) for reusable filters. Cross-cutting query logic — "only published", "in date range", "belongs to tenant" — belongs in criteria classes that the repository applies, not in every controller. Keep criteria small and composable so they can stack in different combinations.
• Keep repositories thin at the edges. Repositories should express what data you want, not HTTP concerns, pagination formatting, or resource transformation. Return models/collections and let your API resources or controllers shape the response.
• Resolve through the container. Type-hint the repository interface in constructor injection; don't app()->make() or new repositories manually. This keeps mocking straightforward in feature tests.
• Layer for tests. Because the repository wraps Eloquent, you can point your test suite at an in-memory SQLite connection and exercise real query behavior rather than mocking the query builder. Reserve mocks for the interface-level unit tests of your services.
• Testbench for package-level work. If you're writing your own repositories as a package (e.g. an internal composer package), the updated Testbench and migration autoloading mean your TestCase can pick up migrations without manual registration — lean on that rather than hand-wiring schema.

Gotchas and Tips

• This is a breaking release in the toolchain sense only. PHP < 8.1, Laravel 8–11, and Carbon 2 are dropped. If your app or any sibling package pins Carbon 2, Composer will refuse the upgrade — resolve Carbon conflicts before bumping this package, not after.
• Carbon 3 has behavioral differences. Date math and diff APIs changed subtly in Carbon 3 (e.g. diff methods returning floats in some cases, changed serialization behavior). Audit any repository method that returns computed dates or relies on diffIn* results, and check JSON output of date-cast attributes in your tests.
• PHP 8.5 CI coverage ≠ PHP 8.5 in production. The release is tested through 8.5, but if your app runs 8.2/8.3 you're still on the well-trodden path. Pin your platform requirement to what you actually deploy so CI green doesn't mask a runtime mismatch.
• Migration autoloading changes can bite package test suites. If your own test bootstrap registers migrations manually, you may end up with duplicate or missing tables after the Testbench upgrade. Prefer the package's provided autoloading path and delete hand-rolled loadMigrationsFrom calls in TestCase.
• Debugging generated queries: repositories tend to hide the query builder. Add a temporary ->toSql()/->getBindings() dump inside the repository method, or enable query logging (DB::listen) in a local test, to see what the base class actually emits before you blame Eloquent.
• Extension points worth knowing: the base repository's hook methods (e.g. pre/post query manipulation if provided), the criteria application pipeline, and the model-resolution mechanism. Overriding model resolution is the clean way to support multi-tenant or polymorphic repositories without duplicating logic.
• Don't over-abstract. A repository per model with one all() method is dead weight. Introduce repositories where there's genuine query complexity, reuse, or a real need to swap data sources — otherwise you're adding indirection without payoff.
• Pin the version in composer.json. With a breaking toolchain jump in 1.7, use ^1.7 deliberately and commit the lockfile so environment drift doesn't silently change Laravel/Carbon versions under you.