Laravel Repositories Laravel Package

Getting Started

• Confirm runtime requirements before installing: PHP ^8.3, Laravel ^12.0 or ^13.12. Laravel 11 is intentionally unsupported in 2.0.1 because Composer blocks it due to security advisories.
• Install the package with Composer, then check the package README for auto-discovery, config publishing, and the base repository/contract classes. Start with the package’s base repository and repository interface—those define the day-to-day API you will extend.
• First use case: create a repository contract for one aggregate, e.g. UserRepositoryInterface, implement it with an Eloquent repository extending the package base class, bind the contract in a service provider, and inject it into a controller or action. This gives you an immediate testability and query-organization win without refactoring the whole app.
• If you are upgrading from an earlier major, read the package upgrade notes before changing constraints; 2.0.1 is a patch release, but the support matrix change can affect existing lock files and CI.

Implementation Patterns

• Bind interfaces to implementations in AppServiceProvider or a dedicated RepositoryServiceProvider. Prefer constructor injection of the interface into controllers, actions, jobs, and services rather than resolving repositories with app().
• Extend the package base repository for standard CRUD and add domain-specific methods such as findActiveByEmail, paginateRecentForTeam, or existsForCustomer. Keep controllers thin and move query composition into repositories or a service layer.
• Use repositories as query boundaries: accept filters/DTOs, return paginators, collections, or models consistently. If the package provides criteria/filter support, use it for reusable query fragments; otherwise keep custom methods small and named after business intent.
• For complex reads, compose repositories with query objects or dedicated filter classes rather than creating one repository per model. Repositories are most valuable where query logic is repeated, needs testing, or crosses concerns such as tenancy, soft deletes, or authorization scopes.
• In tests, mock repository interfaces for unit tests and use the real Eloquent implementation against an in-memory SQLite database for integration tests. This is the main payoff of interface-first binding.
• Keep transaction boundaries in services/jobs, not in repositories. Let repositories perform queries and persistence operations; let the calling service decide what must be atomic.
• If the package supports caching or criteria pipelines, prefer decorators or dedicated query objects over embedding cache logic in every repository method.

Gotchas and Tips

• Do not force installation on Laravel 11 with ignored platform requirements. The 2.0.1 release explicitly removes Laravel 11 because Composer blocks it due to security advisories. Upgrade Laravel first, then install or update the package.
• Verify the exact Laravel 13 constraint: ^13.12 means Laravel 13.12 or newer within major 13. If your app is on an earlier Laravel 13 release, Composer will block the update.
• PHP ^8.3 is required. Align local, CI, and production runtimes before debugging package behavior; syntax or dependency failures may otherwise look like package bugs.
• Check for method-name collisions before adding methods like find, all, create, or paginate. The package base repository may already define them with different signatures or return types.
• Avoid over-abstracting. Repositories for every model add indirection without payoff. Start with aggregates that have complex queries, multiple data sources, or heavy test requirements.
• Be consistent about what repositories return. Returning Eloquent models is common in Laravel and practical; returning query builders leaks Eloquent and makes mocking harder. Pick one convention per repository and document it.
• Watch for N+1 queries when repository methods hide relationship loading. Accept eager-load hints or provide dedicated methods that call with() explicitly.
• If an interface is not bound, expect BindingResolutionException or container resolution errors. Confirm the service provider is registered and the contract-to-implementation mapping is correct.
• Use the package’s extension points—base repository overrides, contracts, criteria/filters, and config—before forking or copying vendor code. Check the updated documentation for config keys and pagination defaults.
• Pin to ^2.0 and review patch release notes. Support-matrix changes can affect CI even when the package code itself is unchanged.