README

Laravel Repositories

Structured repository layer for Laravel with contracts, Eloquent implementations, cache decorators and CQRS-friendly bindings.

This package provides a production-ready way to generate repositories with:

• strict contracts
• Eloquent adapters
• optional cache decorators (with versioned cache keys)
• automatic service container bindings
• ready-to-run unit tests (PHPUnit or Pest)

Architectural Position

Repositories are not the canonical Laravel path for every model interaction, and this package does not try to replace Eloquent. It treats repositories as a pragmatic boundary for applications that want cleaner service, action, job and controller code:

• depend on contracts from business code
• keep persistence details inside Eloquent implementations
• keep cache behavior in decorators
• use typed repository methods that work with integer, UUID and ULID model keys
• avoid generic abstraction when a direct Eloquent query is clearer

Generated Repository Structure

root/
├── app/
│   └── Repositories/
│       ├── Contracts/
│       │   └── ProductRepositoryContract.php
│       └── Implementations/
│           ├── Eloquent/
│           │   └── ProductRepository.php
│           └── Cached/
│               └── ProductCacheRepository.php
└── tests/
    ├── Feature/
    │   └── Repositories/
    │       └── ProductRepositoryTest.php
    └── Unit/
        └── Repositories/
            └── ProductCacheRepositoryTest.php

Installation

composer require alex-kudrya/laravel-repositories

The package service provider is auto-discovered by Laravel 11, 12 and 13.

Usage

The package ships with a single artisan command:

php artisan make:repository Product --model=Product

Or run it as an interactive wizard (recommended):

php artisan make:repository

What will be generated

By default it creates:

• app/Repositories/Contracts/RepositoryContract.php
• app/Repositories/Implementations/Eloquent/Repository.php
• app/Repositories/Implementations/Cached/CacheRepository.php (optional)
• app/Providers/RepositoryServiceProvider.php (created if missing)
• App\Providers\RepositoryServiceProvider::class registration in bootstrap/providers.php
• service container bindings inside RepositoryServiceProvider

Cache decorator

If cache is enabled, the decorator uses versioned cache keys to invalidate all cached lists on write operations (create/update/delete) without tracking each individual key.

Use --no-cache to bind the contract directly to the Eloquent implementation. If cached artifacts already exist, run --no-cache --force to remove the generated cached repository and cache test.

Publishing Stubs

You can publish stubs to customize generated code

php artisan vendor:publish --tag=laravel-repositories-stubs

Published to:

• stubs/laravel-repositories

Laravel Boost

This package ships with Laravel Boost resources:

• resources/boost/guidelines/core.blade.php
• resources/boost/skills/laravel-repositories-development/SKILL.md

When a consuming application installs Laravel Boost and runs php artisan boost:install or php artisan boost:update --discover, Boost can include these package-specific guidelines and the repository development skill.

This repository also keeps matching local AI resources under .ai/guidelines and .ai/skills for direct agent use while developing the package.

Testing (PHPUnit / Pest)

The generator can create repository unit tests compatible with PHPUnit or Pest.

• If Pest is installed in your app, Pest-style tests will be generated.
• Otherwise, PHPUnit tests will be generated.

The tests avoid model-field assumptions. Model-bound repository tests still require the referenced model and its table/migration to exist in the consuming application.

License

MIT

Alexander Kudria alexkudrya91@gmail.com