Download the PHP package amondar-libs/repository-pattern without Composer

amondar-libs/repository-pattern

Laravel package to implement a clean Repository + Service pattern with a tiny, expressive API.

• Model-first repository with a single source of truth declared via attribute
• Optional data normalization via spatie/laravel-data
• Higher-order helpers for running methods quietly (without model events)
• Higher-order helpers for running methods inside a database transaction

Requirements

• PHP ^8.3
• Laravel 10/11/12/13 (uses Eloquent, DB facade)
• spatie/laravel-data (optional, for typed DTOs)

Installation

No service provider registration is required.

Simple usage

This section shows the typical way to use the package: define a Model, optionally a Data object, and a Repository bound to that Model via an attribute.

1) Your Eloquent model

2) (Optional) A Data object

If you prefer typed DTOs, use spatie/laravel-data. The repository accepts arrays or Data instances and normalizes them automatically.

3) Your Repository bound to the model via attribute

4) Use the repository

Notes:

• The repository exposes your model’s query builder via magic __call, so you can chain any Builder methods directly on the repository.
• If you forget to bind a model via #[UseModel], a RepositoryModelNotFound exception will be thrown on repository construction.

Dive deep: quietly and transaction

Two higher‑order helpers are available to control side effects.

• quietly: disables Eloquent model events for the wrapped call
• transaction: runs the wrapped call inside a database transaction

You can use them independently or together.

Run quietly (suppress Eloquent events)

Under the hood, quietly uses Model::withoutEvents(...) around your repository call.

Run in a database transaction

Combine: transaction + quietly

Sometimes you want both: atomic writes and no model events.

Tip: Laravel’s ShouldDispatchAfterCommit events will be dispatched only after a successful commit when used inside a transaction. If the transaction rolls back, those events won’t be dispatched.

Run transaction with pessimistic locking (avoid lost updates)

Sometimes you want to make an atomic update with pessimistic lock.

Tip: You can add ->withTrashed->forUpdate(...) after transaction to get a soft-deleted model viable for update.

Optimistic locking (avoid lost updates)

Besides pessimistic locks, the package also supports optimistic locking to prevent lost updates without holding row locks.

How it works:

• Add the HasOptimisticLock trait to your Eloquent model, implement the Lockable contract, and point to a numeric version column using the VersionField attribute.
• Each successful ->save() (e.g ->update()) increments the version column. If a concurrent update occurs using a stale instance (older version), an OptimisticLockException is thrown.
• You can bypass the check when needed using saveUnlocked() on the model or by calling methods via the repository's ...->unlocked->... proxy.

Migrations:

Model setup:

Raw model usage:

Usage through a repository:

Tips:

• Default starting version is 1; you can override it by setting public static int $defaultLockVersion on your model.
• The version column must exist on the table and be an integer-compatible type.

It's highly recommended to use cache for attributes in production. To do so, implement Amondar\RepositoryPattern\Contracts\WithAttributesCache. Use any available cache driver from spatie/php-structure-discoverer, because it is a part of the php-attributes package used in a particular version.

In Laravel projects - use new \Spatie\StructureDiscoverer\Cache\LaravelDiscoverCacheDriver('YOUR_CACHE_PREFIX') - to use default cache driver of your Laravel application.

Service layer (optional)

You can build services on top of repositories. The Service base class provides a transaction helper as well. Example with handy create/update traits. Also, you can use traits to add target methods into commands in the CQRS pattern.

Service transactions

The service also exposes a transaction helper:

If the method throws, the transaction is rolled back and any ShouldDispatchAfterCommit events are not dispatched.

Data normalization

Repository::create() and Repository::update() accept either:

• plain arrays
• Spatie Data instances (Data), which will be converted to arrays via toArray()

This lets you keep controllers/services strongly typed while repositories remain simple.

Exceptions

• RepositoryModelNotFound — thrown when a Repository has no #[UseModel(...)] attribute assigned.
• ModelNotSaved — helper exception you can use in services when save operations fail (see traits usage).

Types and generics (PHPDoc)

The classes are annotated with generics to improve static analysis in IDEs:

• Repository<TModel, TData>
• Service<TModel, TData, TRepository>
• Proxies and traits carry through those generics as well

License

MIT. See LICENSE.md.