README

A comprehensive Laravel repository package that provides enterprise-level features for data access, performance optimization, analytics, and advanced querying capabilities. Perfect for applications handling large datasets, complex relationships, and requiring high-performance data operations.

✨ Features

Core Repository Pattern

✅ Complete CRUD Operations - Standard create, read, update, delete operations
✅ Clean Interface Separation - Well-defined contracts and implementations
✅ Laravel Best Practices - Follows Laravel conventions and patterns

Advanced Query Building

� Advanced Join Capabilities - Left, right, inner joins with relationship handling
🔍 Comprehensive Filtering - Dynamic field filtering with multiple operators
🎯 Query String Parser - Parse complex URL filters with 20+ operators
📊 Dynamic Scopes & Macros - Extensible query building with custom scopes

Performance & Optimization

🚀 Large Dataset Optimization - Handle 5M+ records efficiently with cursor pagination
⚡ Smart Pagination - Auto-optimization for different dataset sizes
� Performance Metrics - Built-in profiling and query analysis
🧠 Intelligent Caching - Advanced caching with tags and auto-invalidation

Data Operations

� Bulk Operations - Efficient bulk insert, update, delete, and upsert
🔄 Batch Processing - Process large datasets in manageable chunks
📁 Data Export/Import - CSV, JSON, Excel export/import with streaming
� Relationship Manager - Advanced relationship handling and optimization

Analytics & Insights

📊 Repository Aggregations - Statistical analysis and trend calculations
📈 Analytics Functions - Percentiles, correlations, moving averages
� Pivot Tables - Dynamic data pivoting and cross-tabulation
📉 Histogram Generation - Data distribution analysis

Search & Discovery

🔍 Multi-Engine Search - Database, Elasticsearch, and Algolia integration
🎯 Fuzzy Search - Similarity-based matching with configurable thresholds
📝 Full-Text Search - Advanced text search with relevance scoring
🔧 Search Index Management - Automated indexing and reindexing

Events & Monitoring

🎪 Repository Events - Comprehensive event system for all operations
� Performance Monitoring - Real-time metrics and benchmarking
🚨 Error Tracking - Built-in error handling and reporting
📋 Audit Trail - Complete operation logging and tracking

Security & Validation

🛡️ Field Whitelisting - Secure field access control
✅ Input Validation - Built-in data validation and sanitization
� Rate Limiting Ready - Prepared for rate limiting implementation
🛡️ SQL Injection Protection - Secure query building

A Laravel package that implements the Repository pattern with a clean, intuitive API. This package provides a base repository class, interfaces, service provider bindings, CRUD operations, pagination support, and artisan commands to generate repositories.

Features

🏗️ Repository Pattern Implementation - Clean separation of data access logic
🔧 Base Repository Class - Common CRUD operations out of the box
🎯 Repository Interface - Contract-based development
📦 Service Provider - Automatic Laravel integration
🔍 Advanced Querying - Search, filtering, and sorting capabilities
� Comprehensive Join Support - Inner, left, right, cross joins with subqueries
📊 Aggregation Methods - Group by, having, raw expressions, and complex analytics
�📄 Pagination Support - Built-in pagination methods
⚡ Artisan Commands - Generate repositories with make:repository
🧪 Fully Tested - Comprehensive test suite
📚 Well Documented - Complete documentation and examples

Requirements

PHP 8.2 or higher
Laravel 11.0 or 12.0

Installation

You can install the package via Composer:

composer require litepie/repository

The package will automatically register its service provider.

Quick Start

1. Create a Repository

Use the artisan command to generate a repository:

php artisan make:repository UserRepository

This will create a repository class and interface in your app/Repositories directory.

2. Use the Repository

<?php

namespace App\Http\Controllers;

use App\Repositories\Contracts\UserRepositoryInterface;

class UserController extends Controller
{
    public function __construct(
        private UserRepositoryInterface $userRepository
    ) {}

    public function index()
    {
        $users = $this->userRepository->paginate(15);
        return view('users.index', compact('users'));
    }

    public function store(Request $request)
    {
        $user = $this->userRepository->create($request->validated());
        return redirect()->route('users.show', $user);
    }
}

Usage

Basic CRUD Operations

// Create
$user = $userRepository->create(['name' => 'John Doe', 'email' => 'john@example.com']);

// Read
$user = $userRepository->find(1);
$users = $userRepository->all();

// Update
$user = $userRepository->update(1, ['name' => 'Jane Doe']);

// Delete
$userRepository->delete(1);

Advanced Querying

// Find with relationships
$user = $userRepository->with(['posts', 'comments'])->find(1);

// Search and filter
$users = $userRepository
    ->where('status', 'active')
    ->orderBy('created_at', 'desc')
    ->paginate(10);

// Custom queries
$users = $userRepository->findWhere([
    ['status', '=', 'active'],
    ['created_at', '>', now()->subDays(30)]
]);

// Advanced filtering
$users = $userRepository
    ->filter(['status' => 'active', 'role' => ['admin', 'moderator']])
    ->search('john', ['name', 'email'])
    ->dateRange('created_at', '2024-01-01', '2024-12-31')
    ->get();

// Request-based filtering
$users = $userRepository
    ->filterFromRequest(request()->all(), ['name', 'email', 'status'])
    ->sortFromRequest(request()->all(), ['name', 'created_at'])
    ->paginate(15);

// Join tables
$posts = $postRepository
    ->select(['posts.*', 'users.name as author_name'])
    ->join('users', 'posts.user_id', '=', 'users.id')
    ->where('posts.status', 'published')
    ->orderBy('posts.created_at', 'desc')
    ->get();

// Complex joins with conditions
$posts = $postRepository
    ->select(['posts.*', 'users.name as author_name'])
    ->selectRaw('COUNT(comments.id) as comments_count')
    ->join('users', 'posts.user_id', '=', 'users.id')
    ->leftJoin('comments', 'posts.id', '=', 'comments.post_id')
    ->where('posts.status', 'published')
    ->groupBy(['posts.id', 'users.name'])
    ->having('comments_count', '>', 5)
    ->orderByRaw('comments_count DESC')
    ->get();

Repository Methods

The base repository provides the following methods:

Basic CRUD

all($columns = ['*']) - Get all records
find($id, $columns = ['*']) - Find record by ID
create(array $data) - Create new record
update($id, array $data) - Update existing record
delete($id) - Delete record by ID

Query Building

where($column, $operator = null, $value = null) - Add where clause
orWhere($column, $operator = null, $value = null) - Add or where clause
whereIn($column, array $values) - Add where in clause
whereBetween($column, array $values) - Add where between clause
whereNull($column) - Add where null clause
whereNotNull($column) - Add where not null clause
whereDate($column, $operator, $value) - Add where date clause
whereRaw($sql, array $bindings = []) - Add raw where clause
orderBy($column, $direction = 'asc') - Add order by clause
orderByRaw($sql, array $bindings = []) - Add raw order by clause
with($relations) - Eager load relationships
limit($limit) - Limit results
offset($offset) - Offset results

Join Operations

join($table, $first, $operator = null, $second = null) - Add inner join
leftJoin($table, $first, $operator = null, $second = null) - Add left join
rightJoin($table, $first, $operator = null, $second = null) - Add right join
innerJoin($table, $first, $operator = null, $second = null) - Add inner join
crossJoin($table) - Add cross join
joinWhere($table, callable $callback) - Add join with closure conditions
leftJoinWhere($table, callable $callback) - Add left join with closure
joinSub($query, $as, $first, $operator, $second) - Add subquery join
leftJoinSub($query, $as, $first, $operator, $second) - Add left subquery join

Aggregation & Grouping

select($columns) - Select specific columns
selectRaw($expression, array $bindings = []) - Add raw select expression
distinct() - Add distinct clause
groupBy($groups) - Add group by clause
having($column, $operator, $value) - Add having clause
orHaving($column, $operator, $value) - Add or having clause
havingBetween($column, array $values) - Add having between clause

Advanced Queries

findWhere(array $where, $columns = ['*']) - Find records with conditions
findWhereIn($column, array $values, $columns = ['*']) - Find records where column in values
paginate($perPage = 15, $columns = ['*']) - Paginate results
simplePaginate($perPage = 15, $columns = ['*']) - Simple pagination

Utility Methods

count() - Count records
exists($id) - Check if record exists
chunk($count, callable $callback) - Process records in chunks

Custom Repository Example

<?php

namespace App\Repositories;

use App\Models\User;
use App\Repositories\Contracts\UserRepositoryInterface;
use Litepie\Repository\BaseRepository;

class UserRepository extends BaseRepository implements UserRepositoryInterface
{
    public function model(): string
    {
        return User::class;
    }

    public function findActiveUsers()
    {
        return $this->where('status', 'active')->get();
    }

    public function findByEmail(string $email)
    {
        return $this->where('email', $email)->first();
    }

    public function getRecentUsers(int $days = 30)
    {
        return $this->where('created_at', '>=', now()->subDays($days))
                   ->orderBy('created_at', 'desc')
                   ->get();
    }
}

Service Provider Bindings

The package automatically binds repository interfaces to their implementations. You can also manually bind repositories in your AppServiceProvider:

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use App\Repositories\UserRepository;
use App\Repositories\Contracts\UserRepositoryInterface;

class AppServiceProvider extends ServiceProvider
{
    public function register()
    {
        $this->app->bind(UserRepositoryInterface::class, UserRepository::class);
    }
}

🚀 Large Dataset Optimization

When dealing with datasets over 5 million records, traditional pagination becomes slow. This package provides several optimization strategies:

Cursor-Based Pagination (Recommended)

// Much faster than OFFSET pagination for large datasets
$users = $userRepository
    ->where('status', 'active')
    ->cursorPaginate(20);

// For APIs
return response()->json([
    'data' => $users->items(),
    'next_cursor' => $users->nextCursor()?->encode(),
    'has_more' => $users->hasMorePages(),
]);

Fast Pagination (No Total Count)

// Skip expensive COUNT(*) queries
$users = $userRepository
    ->where('status', 'active')
    ->fastPaginate(20);

Smart Pagination (Auto-Optimization)

// Automatically chooses the best pagination method based on dataset size
$users = $userRepository
    ->where('status', 'active')
    ->smartPaginate(20);

Memory-Efficient Processing

// Process large datasets without memory issues
$userRepository->chunk(1000, function ($users) {
    foreach ($users as $user) {
        // Process each user
    }
});

// Or use lazy collections
$users = $userRepository->lazy(1000);
foreach ($users as $user) {
    // Memory-efficient iteration
}

Performance Comparison

Method	1M Records	5M Records	10M Records	Best For
Standard	~500ms	~2000ms	~5000ms+	Small datasets
Fast	~50ms	~100ms	~150ms	No total needed
Cursor	~10ms	~15ms	~20ms	Large datasets
Seek	~5ms	~10ms	~15ms	Real-time feeds

📖 Read the complete optimization guide →

🔍 Query String Filter Parser

Parse complex filter expressions from URL query strings for advanced search and filtering capabilities.

Complex Filter Syntax

// Parse filter string like:
// "category:IN(Apartment,Bungalow);price:BETWEEN(100000,500000);status:EQ(Published);bua:GT(1000)"

$properties = $propertyRepository
    ->parseQueryFilters($filterString, ['category', 'price', 'status', 'bua'])
    ->cursorPaginate(20);

Supported Operators

Comparison: EQ, NEQ, GT, GTE, LT, LTE
Arrays: IN, NOT_IN
Ranges: BETWEEN, NOT_BETWEEN
Strings: LIKE, NOT_LIKE, STARTS_WITH, ENDS_WITH
Nulls: IS_NULL, IS_NOT_NULL
Dates: DATE_EQ, DATE_GT, DATE_BETWEEN, YEAR, MONTH
JSON: JSON_CONTAINS, JSON_LENGTH

Real-World Example

// URL: /api/properties?filters=category:IN(Apartment,Villa);price:BETWEEN(100000,500000);bedrooms:IN(2,3,4)

public function search(Request $request, PropertyRepository $repository)
{
    $filterString = $request->get('filters');
    
    // Security: Define allowed fields
    $allowedFields = ['category', 'price', 'bedrooms', 'status', 'location'];
    
    $properties = $repository
        ->parseQueryFilters($filterString, $allowedFields)
        ->with(['images', 'location'])
        ->optimizedPaginate(20);
        
    return response()->json([
        'data' => $properties->items(),
        'filters' => $repository->getFilterSummary($filterString),
    ]);
}

Frontend Integration

// JavaScript filter builder
const filters = new FilterBuilder()
    .addFilter('category', 'IN', ['Apartment', 'Villa'])
    .addFilter('price', 'BETWEEN', [100000, 500000])
    .build();
// Output: "category:IN(Apartment,Villa);price:BETWEEN(100000,500000)"

fetch(`/api/properties?filters=${encodeURIComponent(filters)}`)
    .then(response => response.json())
    .then(data => console.log(data));

📖 Complete Query String Parser Guide →

Artisan Commands

make:repository

Generate a new repository class and interface:

# Generate repository with interface
php artisan make:repository UserRepository

# Generate repository only (without interface)
php artisan make:repository UserRepository --no-interface

# Specify model
php artisan make:repository UserRepository --model=User

# Generate in custom directory
php artisan make:repository Admin/UserRepository

Configuration

You can publish the configuration file:

php artisan vendor:publish --provider="Litepie\Repository\RepositoryServiceProvider" --tag="config"

This will create a config/repository.php file where you can customize:

Default repository namespace
Default interface namespace
Repository stub files

Testing

Run the tests with:

composer test

🚀 Advanced Features

Your repository package now includes these enterprise-level features:

📊 Analytics & Data Science

// Statistical analysis
$stats = $repository->statisticalSummary('revenue');
$trends = $repository->trend('created_at', 'day', 'sales', 'sum');
$correlation = $repository->correlation('price', 'rating');

// Pivot tables
$salesData = $repository->pivot('category', 'month', 'revenue', 'sum');

🔍 Advanced Search

// Multi-engine search (Database, Elasticsearch, Algolia)
$results = $repository
    ->configureSearch(['engine' => 'elasticsearch'])
    ->search('laravel repository pattern');

// Fuzzy search with similarity matching
$fuzzyResults = $repository->fuzzySearch('jhon doe', 0.8);

📦 Bulk Operations

// Handle large datasets efficiently
$repository->bulkInsert($millionRecords, 2000);
$repository->bulkUpsert($data, ['email'], ['name', 'status']);
$repository->batchProcess($callback, 1000);

🧠 Intelligent Caching

// Advanced caching with tags and auto-invalidation
$data = $repository
    ->remember(3600)
    ->tags(['users', 'active'])
    ->where('status', 'active')
    ->get();

📈 Performance Monitoring

// Built-in profiling and optimization
$repository->enableProfiling();
$data = $repository->complexQuery();
$report = $repository->getPerformanceReport();

📁 Data Import/Export

// Stream large exports
return $repository->streamExport('csv');

// Bulk import with conflict resolution
$imported = $repository->importFromCsv('data.csv', $mapping, [
    'update_existing' => true,
    'skip_errors' => true
]);

🎪 Event System

// Listen to repository events
Event::listen('repository.User.created', function ($model) {
    // Send notifications, update caches, etc.
});

🔗 Relationship Management

// Advanced relationship operations
$repository->syncRelation('tags', $postId, [1, 2, 3]);
$repository->createRelated('comments', $postId, $commentData);
$repository->loadMissingRelations($collection, ['user', 'tags']);

For detailed documentation on all advanced features, see Advanced Features Guide.

📚 Documentation

Advanced Features Guide - Complete guide to all enterprise features
Query String Parser - URL filter parsing documentation
Performance Optimization - Optimization strategies for large datasets
API Reference - Complete API documentation

🎯 Real-World Examples

Perfect for applications like:

E-commerce platforms - Product catalogs, order processing, inventory management
Real estate systems - Property listings, advanced filtering, market analytics
CRM systems - Customer data, relationship tracking, performance analytics
Content management - Article publishing, media handling, user engagement tracking
Financial applications - Transaction processing, reporting, audit trails
IoT platforms - Sensor data, time-series analysis, bulk data processing

Contributing

Please see CONTRIBUTING.md for details.

Security

If you discover any security-related issues, please email security@litepie.com instead of using the issue tracker.

litepie / repository

Maintainers

Details