Laravel Repositories Laravel Package

Getting Started

• Upgrade with composer require sinemacula/laravel-repositories:^3.2. v3.2.0 is an additive feature release: no breaking changes or deprecations are called out in the release notes.
• Start with the package README, then look at the base repository class and the new attribute under the package’s Attributes namespace.
• Create one concrete repository per aggregate rather than a generic repository for every model:

namespace App\Repositories;

use App\Models\User;
use SineMacula\LaravelRepositories\Attributes\Model;
use SineMacula\LaravelRepositories\Repository;

#[Model(User::class)]
final class UserRepository extends Repository
{
}

• Bind the repository behind an interface in a service provider if you want it swappable in tests:

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

• First use case: inject UserRepositoryInterface into a controller or action and replace ad-hoc Eloquent queries for that aggregate. The new v3.2.0 attribute is the cleanest way to tell the repository which model it manages, without overriding a $model property or model() method.

Implementation Patterns

• Attribute-first model declaration: Prefer the new attribute over legacy property/method-based model declaration. It keeps the model binding visible at the top of the repository class and avoids boilerplate in every repository.
• Interface + container binding: Depend on UserRepositoryInterface, not UserRepository, in controllers/actions. Bind the concrete implementation in AppServiceProvider or a dedicated repository service provider.
• Keep controllers thin: Let repositories handle query composition and persistence, but keep request validation, authorization, transactions, and response shaping in controllers/actions/services.
• Use specific repositories: A UserRepository with domain methods such as activeUsers(), findByEmail(), or paginateForAdmin() is more useful than a generic all/find/create/update/delete wrapper.
• Criteria/filter objects: If the package exposes criteria or query-scope composition, put reusable filters there instead of stacking conditions in controllers. Compose them in the repository or a service layer.
• Transactions at the service boundary: A repository method should usually represent one persistence operation. Wrap multi-repository writes in a service/action using DB::transaction().
• Pagination and API responses: Return paginators/collections from repositories, then convert to API resources in the HTTP layer. Avoid returning already-serialized arrays from repositories.
• Testing: Bind a fake or in-memory repository implementation for unit tests; use RefreshDatabase and a real repository for integration tests. The attribute makes it easier to instantiate a repository against the correct model in tests.
• Migration path from older versions: Add the model attribute to one repository, verify container resolution and basic queries, then remove the old $model property or model() override. Repeat incrementally rather than changing every repository at once.

Gotchas and Tips

• The attribute only declares the model. It does not register the repository, bind an interface, or configure dependency injection. You still need normal Laravel container bindings.
• Make sure you import the package’s attribute class, not Eloquent’s Model class. If the names collide, alias the attribute import.
• If a repository already declares its model via a property or method, confirm precedence before removing the old declaration. During migration, keep both only long enough to verify behavior, then remove the legacy path.
• The declared model must be an Eloquent model and must be autoloadable. A typo in the class string may not fail until the repository is resolved or used.
• The attribute does not affect route model binding, policies, factories, relationships, or observers. Those still need their normal Laravel wiring.
• Avoid lazy-loading relationships inside loops. Add eager-loading support through repository methods or criteria so callers can request relations explicitly.
• For debugging, resolve the repository from the container (app(UserRepository::class)) and inspect the model it resolves. If the package exposes a getModel()-style method, use it in tinker to confirm the attribute is being read.
• Extension point: create a shared base repository in your app for common behavior, but keep model-specific query logic in concrete repositories. Overriding package base methods is fine for cross-cutting concerns; avoid hiding domain-specific queries in a generic base class.
• The repository pattern can become ceremony if it only proxies Eloquent. Use it where it adds reuse, testability, or a clear boundary around complex query logic.