README

A powerful, feature-rich CRUD service package for Laravel applications built on SOLID principles and design patterns. Provides comprehensive database operations with advanced features like caching, query logging, column validation, export capabilities, and more.

🚀 Key Features

Complete CRUD Operations - Create, Read, Update, Delete with full validation
Bulk Operations - Efficient bulk create, update, and delete operations
Advanced Filtering & Search - Column-based filtering, sorting, and text search
Search Strategy System - Pluggable search strategies for custom search implementations
Export Functionality - CSV, JSON, and custom export formats
Filter Helpers - One-line helpers for common filter patterns such as between ranges
Query Caching - Built-in query caching with configurable lifetime
Performance Monitoring - Query logging and slow query detection
Column Validation - Secure column validation for all operations
Virtual Filters - Safely expose computed filter columns via getCustomFilterColumns()
Event System - Extensible event system for custom business logic
Trait-Based Configuration - Type-safe, IDE-friendly configuration system
Audit Trail - Automatic tracking of record changes (created_by, updated_by, deleted_by)

📋 Requirements

PHP ^8.1
Laravel ^10.0|^11.0|^12.0
Illuminate Support ^10.0|^11.0|^12.0
Illuminate Database ^10.0|^11.0|^12.0
Illuminate Validation ^10.0|^11.0|^12.0
Illuminate Pagination ^10.0|^11.0|^12.0

📦 Installation

1. Install via Composer

composer require sgflores/cruder

2. Publish Configuration (Optional)

php artisan vendor:publish --provider="SgFlores\Cruder\CruderServiceProvider" --tag="cruder-config"

3. Service Provider (Auto-discovered)

The package will be automatically discovered by Laravel.

🎯 Quick Start

1. Create Your Service

<?php

namespace App\Services;

use SgFlores\Cruder\BaseCrudService;
use SgFlores\Cruder\Services\EventService;
use SgFlores\Cruder\Services\ValidationService;
use App\Models\User;

class UserService extends BaseCrudService
{
    public function __construct(
        User $user,
        EventService $eventService,
        ValidationService $validationService
    ) {
        parent::__construct($user, $eventService, $validationService);
    }
    
    // Override configuration methods as needed
    public function getDirectTextSearchColumns(): array
    {
        return ['name', 'email'];
    }
    
    public function getDirectFilterableColumns(): array
    {
        return ['status', 'department_id'];
    }
    
    public function getDirectSortableColumns(): array
    {
        return ['name', 'email', 'created_at'];
    }
    
    public function isAuditTrailEnabled(): bool
    {
        return true;
    }
}

💡 Configuration: The service uses a trait-based configuration system. See CONFIGURATION.md for all available configuration methods and examples.

2. Basic Usage

// Find all users with filtering and pagination
$users = $userService->findAll([
    'search' => 'john',
    'status' => 'active',
    'sort_by' => 'name',
    'sort_direction' => 'asc',
    'per_page' => 10,
    'page' => 1
]);

// Find user by ID and load department relation (resource-aware)
$user = $userService->findById(1, ['department']); // returns Model|JsonResource|null

// Find raw model (no resource transformation) for policy checks
$rawUser = $userService->findByIdRaw(1, ['department']); // returns ?Model

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

// Update user (returns Model|JsonResource|null)
$user = $userService->update(1, [
    'name' => 'John Smith'
]);

// Delete user
$userService->delete(1);

// Bulk operations
$userService->bulkCreate([
    ['name' => 'User 1', 'email' => 'user1@example.com'],
    ['name' => 'User 2', 'email' => 'user2@example.com']
]);

3. Between Filter Helper

BaseReaderService ships with a convenience helper for assembling range filters without hand-writing the advanced filter structure:

$filters = [
    'created_from' => '2025-01-01',
    'created_to'   => '2025-01-31',
];

$this->mergeBetweenFilter(
    $filters,
    'orders.created_at', // actual database column
    'created_from',      // input key for the lower bound
    'created_to',        // input key for the upper bound
    'Y-m-d'              // optional Carbon format
);

// $filters now contains:
// [
//     'orders.created_at' => [
//         'operator' => 'between',
//         'value'    => ['2025-01-01', '2025-01-31'],
//     ],
// ]

// Resulting SQL fragment
// where `orders`.`created_at` between '2025-01-01' and '2025-01-31'

📝 Note: For export functionality, you'll need to extend BaseReaderService with SearchService and ExportService injected. See Examples/README.md for complete examples.

4. Search Strategies

Create custom search implementations for complex reporting and analytics using the strategy pattern.

Key Features:

Custom Search Strategies - Pluggable strategies
Query Type Flexibility - Support both Eloquent Builder and QueryBuilder
Proper Service Injection - Extend BaseReaderService with SearchService injected

Example Strategy Implementation:

class TopOrdersStrategy implements SearchStrategyInterface
{
    public static function key(): string
    {
        return 'top_orders';
    }
    
    public function search(Builder|QueryBuilder|null $query, array $filters, array $config = []): Builder|QueryBuilder
    {
        return $query->orderBy('total_amount', 'desc');
    }
}

Usage:

// Register strategy
$this->searchService->addStrategy(TopOrdersStrategy::key(), new TopOrdersStrategy());

// Use in queries
$results = $this->findAll(['strategies' => TopOrdersStrategy::key()]);

Complete Example: See Examples/SalesReportService.php for full implementation.

📚 Documentation

CONFIGURATION.md - Complete configuration methods reference and examples
ARCHITECTURE.md - Package architecture, design patterns, and request lifecycle
Examples/README.md - Comprehensive examples documentation and usage patterns
Tests/README.md - Testing documentation and examples

📖 Available Examples

Quick Reference:

SimpleSalesExample.php - Basic CRUD operations
SalesInventoryExample.php - Advanced inventory management
SalesReportService.php - Custom search strategies for reporting
ProductExample.php - Custom validation strategies
ExportExample.php - Data export functionality

See Examples/README.md for comprehensive documentation.

🧪 Testing

composer test              # Run test suite
composer test-coverage     # Run with coverage

🤝 Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

sgflores

Email: floresopic@gmail.com

🙏 Acknowledgments

Built with ❤️ for the Laravel community using:

Laravel Framework - Foundation and ORM
Laravel Query Builder - Fluent query building
Laravel Validation - Input validation
SOLID Principles - Clean architecture foundation
Strategy Pattern - Interchangeable algorithms
PHPUnit - Unit testing framework
Orchestra Testbench - Laravel package testing

sgflores / cruder

Maintainers

Details