README

Frontier Repository

Repository Pattern with Transparent Caching for Laravel

Installation • Quick Start • Caching • API Reference • Commands

Features

• ✅ Repository Pattern — Clean abstraction for data access
• ✅ Decorator Caching — Choose between simple or cached repository implementations
• ✅ Full CRUD — Create, Read, Update, Delete with consistent API
• ✅ Advanced Queries — Filtering, sorting, pagination, scopes
• ✅ Module Support — Works with internachi/modular

Installation

composer require frontier/repository

Quick Start

1. Create Interface

It is best practice to always code against interfaces.

php artisan frontier:repository-interface UserRepository

2. Generate Repository

Create a standard repository that implements the interface.

php artisan frontier:repository UserRepositoryEloquent

3. Generate Repository Cache (Optional)

Create a decorator repository that adds caching.

php artisan frontier:repository-cache UserRepositoryCache

4. Bind in ServiceProvider

Bind your interface to either the standard repository or the cached one.

// app/Providers/RepositoryServiceProvider.php

// Option A: Standard Repository (No Caching)
$this->app->bind(UserRepository::class, function ($app) {
    return new UserRepositoryEloquent(new User());
});

// Option B: Cached Repository (Repository + Caching Decorator)
$this->app->bind(UserRepository::class, function ($app) {
    return new UserRepositoryCache(
        new UserRepositoryEloquent(new User())
    );
});

Caching

Caching is implemented via the Decorator Pattern. The BaseRepositoryCache wraps your BaseRepository and handles caching logic transparently.

Architecture

┌─────────────────────────────────────────┐
│         UserRepository         │
└───────────────────┬─────────────────────┘
                    │ bind to either:
    ┌───────────────┴───────────────┐
    ▼                               ▼
UserRepositoryEloquent              UserRepositoryCache
extends BaseRepository              extends RepositoryCache
(Direct DB Access)                  (Caching Decorator)

Usage

Inject the interface into your controllers or actions:

class UserController extends Controller
{
    public function __construct(
        protected UserRepository $users
    ) {}

    public function index()
    {
        // Automatically cached if UserRepositoryCache is bound
        return $this->users->retrieve();
    }
}

Cache Control Methods

The BaseRepositoryCache exposes helper methods to control cache behavior:

// Skip cache for this query
$users->withoutCache()->retrieve();

// Force refresh cache
$users->refreshCache()->retrieve();

// Clear all cache
$users->clearCache();

Caching Behavior

Configuration

Publish config:

php artisan vendor:publish --tag=repository-config

// config/repository-cache.php
return [
    'enabled' => env('REPOSITORY_CACHE_ENABLED', true),
    'driver' => env('REPOSITORY_CACHE_DRIVER', null),
    'ttl' => env('REPOSITORY_CACHE_TTL', 3600),
];

Artisan Commands

All commands support the --module flag for modular applications.

CRUD Operations

// CREATE
$user = $this->users->create(['name' => 'John']);

// READ
$user = $this->users->find(['id' => 1]);
$users = $this->users->retrieve();
$users = $this->users->retrievePaginate(['*'], ['per_page' => 15]);

// UPDATE
$count = $this->users->update(['id' => 1], ['name' => 'Jane']);

// DELETE
$count = $this->users->delete(['id' => 1]);

Advanced Queries

The retrieve() and retrievePaginate() methods accept an $options array to build complex queries without writing boilerplate.

$users = $this->users->retrieve(['id', 'name', 'email'], [
    // Filtering (requires EloquentFilter on Model)
    'filters' => ['status' => 'active', 'role' => 'admin'],
    
    // Scopes
    'scopes' => ['verified', 'olderThan' => [18]],
    
    // Relationships
    'with' => ['profile', 'posts'],
    'with_count' => ['posts'],
    
    // Sorting
    'sort' => 'created_at',
    'direction' => 'desc',
    
    // Pagination (for retrievePaginate)
    'per_page' => 25,
    
    // Limits & Offsets
    'limit' => 10,
    'offset' => 5,
    
    // Grouping
    'group_by' => ['status'],
    'distinct' => true,
]);

Supported Options

Note

To use filters, your Eloquent Model must use the Filterable trait (typically from tucker-eric/eloquentfilter).

Development

composer test          # Run tests
composer lint          # Fix code style
composer rector        # Apply refactorings

Related Packages

🤝 Contributing

1. Follow PSR-12 coding standards
2. Use Laravel Pint for code styling
3. Write tests using Pest
4. Add strict types to all PHP files

📄 License

MIT License - see LICENSE for details.

👤 Author

Mohamed Khedr — 0xkhdr@gmail.com

Made with ❤️ for the Laravel community