ashique-ar / laravel-crud-generator
A powerful, configuration-driven CRUD API generator for Laravel with advanced features including permissions, filtering, sorting, bulk operations, and custom logic handlers.
Requires
- php: ^8.1
- laravel/framework: ^10.0|^11.0|^12.0
- spatie/laravel-permission: ^5.0|^6.0
Requires (Dev)
- laravel/pint: ^1.0
- orchestra/testbench: ^8.0|^9.0
- phpstan/phpstan: ^1.0
- phpunit/phpunit: ^10.0
README
A powerful, configuration-driven CRUD API generator for Laravel applications. Generate complete REST APIs with advanced features like permissions, filtering, sorting, validation, and custom business logic handlers - all through simple configuration.
โจ Features
- ๐ Zero-Code CRUD APIs - Generate complete REST APIs through configuration
- ๐ Permission Integration - Built-in support for Spatie Laravel Permission
- ๐ฏ Custom Logic Handlers - Extend with custom business logic easily
- ๐ Advanced Filtering - Search across multiple fields with configurable operators
- ๐ Smart Sorting - Multi-field sorting with default configurations
- โก Bulk Operations - Perform operations on multiple resources at once
- ๐๏ธ Soft Deletes Support - Full soft delete support with restore capabilities
- โ Automatic Validation - Validation rules defined in configuration
- ๐ API Documentation - Auto-generated OpenAPI/Swagger documentation
- ๐ ๏ธ Artisan Commands - Powerful commands for scaffolding and management
- ๐งช Fully Tested - Comprehensive test suite included
๐ Requirements
- PHP 8.1+
- Laravel 10.x | 11.x | 12.x
- Spatie Laravel Permission (automatically installed)
๐ฆ Installation
Install the package via Composer:
composer require ashique-ar/laravel-crud-generator
Run the installation command:
php artisan crud:install
This will:
- Publish the configuration file
- Set up middleware
- Register routes
- Generate initial permissions (optional)
๐ Quick Start
1. Configure Your First Resource
Edit config/crud.php
to define your resources:
<?php return [ // ... other configuration sections ... 'resources' => [ 'users' => [ 'model' => App\Models\User::class, 'table' => 'users', 'fillable' => ['name', 'email', 'phone'], 'hidden' => ['password'], 'rules' => [ 'store' => [ 'name' => 'required|string|max:255', 'email' => 'required|email|unique:users,email', 'phone' => 'nullable|string|max:20' ], 'update' => [ 'name' => 'sometimes|string|max:255', 'email' => 'sometimes|email|unique:users,email,{{id}}', 'phone' => 'sometimes|string|max:20' ] ], 'search' => [ 'enabled' => true, 'fields' => ['name', 'email'], 'operator' => 'like' ], 'sort' => [ 'enabled' => true, 'fields' => ['name', 'email', 'created_at'], 'default' => ['field' => 'created_at', 'direction' => 'desc'] ], 'filters' => [ 'enabled' => true, 'fields' => ['status', 'role'], 'operators' => [ 'status' => 'exact', 'role' => 'in' ] ], 'relations' => ['profile', 'roles'], 'permissions' => [ 'enabled' => true, 'middleware' => 'check.crud.permission' ], 'soft_deletes' => true, 'bulk_operations' => [ 'enabled' => true, 'operations' => ['delete', 'restore', 'update'] ], 'api' => [ 'paginate' => true, 'per_page' => 15, 'max_per_page' => 100 ], 'middleware' => ['auth:sanctum'] ], // Example with model in subfolder 'user-profiles' => [ 'model' => App\Models\User\Profile::class, 'fillable' => ['bio', 'avatar', 'social_links'], 'rules' => [ 'store' => [ 'bio' => 'nullable|string|max:1000', 'avatar' => 'nullable|image|max:2048' ], 'update' => [ 'bio' => 'sometimes|string|max:1000', 'avatar' => 'sometimes|image|max:2048' ] ], 'search' => [ 'enabled' => true, 'fields' => ['bio'] ] ], // Example with full custom namespace 'vehicle-classes' => [ 'model' => App\Models\Vehicle\VehicleClass::class, 'table' => 'vehicle_classes', 'fillable' => ['name', 'description', 'is_active'], 'rules' => [ 'store' => [ 'name' => 'required|string|max:255|unique:vehicle_classes,name', 'description' => 'nullable|string|max:1000', 'is_active' => 'boolean', ], 'update' => [ 'name' => 'sometimes|string|max:255|unique:vehicle_classes,name,{{id}}', 'description' => 'sometimes|string|max:1000', 'is_active' => 'sometimes|boolean', ] ], 'search' => [ 'enabled' => true, 'fields' => ['name', 'description'], 'operator' => 'like' ], 'sort' => [ 'enabled' => true, 'fields' => ['name', 'created_at'], 'default' => ['field' => 'name', 'direction' => 'asc'] ], 'filters' => [ 'enabled' => true, 'fields' => ['is_active'], 'operators' => [ 'is_active' => 'exact' ] ], 'bulk_operations' => [ 'enabled' => true, 'operations' => ['delete', 'update'] ] ] ] ];
2. Register Routes
Add the CRUD routes to your routes/api.php
file:
use AshiqueAr\LaravelCrudGenerator\Facades\CrudGenerator; // Register all CRUD routes with prefix and middleware CrudGenerator::registerRoutes('api/v1', ['auth:sanctum']);
3. Generate Permissions
php artisan crud:permissions
4. Start Using Your API
Your CRUD endpoints are now available:
# List users with pagination, search, and sorting GET /api/v1/users?search=john&sort=name&direction=asc&page=1 # Create a new user POST /api/v1/users { "name": "John Doe", "email": "john@example.com" } # Get a specific user GET /api/v1/users/1 # Update a user PUT /api/v1/users/1 { "name": "John Smith", "email": "johnsmith@example.com" } # Delete a user DELETE /api/v1/users/1
๐ Available Endpoints
For each configured resource, the following endpoints are automatically generated:
Method | Endpoint | Description |
---|---|---|
GET |
/api/v1/{resource} |
List resources with pagination, search, and sorting |
POST |
/api/v1/{resource} |
Create a new resource |
GET |
/api/v1/{resource}/{id} |
Get a specific resource |
PUT/PATCH |
/api/v1/{resource}/{id} |
Update a resource |
DELETE |
/api/v1/{resource}/{id} |
Delete a resource |
POST |
/api/v1/{resource}/bulk |
Bulk operations (if enabled) |
GET |
/api/v1/{resource}/trashed |
List soft-deleted resources (if enabled) |
POST |
/api/v1/{resource}/{id}/restore |
Restore soft-deleted resource (if enabled) |
DELETE |
/api/v1/{resource}/{id}/force |
Force delete resource (if enabled) |
GET |
/api/v1/{resource}/docs |
API documentation for the resource |
Query Parameters
Pagination
page
- Page number (default: 1)per_page
- Items per page (default: 15, max: 100)
Search
search
- Search term across configured searchable fieldssearch_operator
- Search operator:like
,exact
,starts_with
,ends_with
(default:like
)
Sorting
sort
- Field to sort bydirection
- Sort direction:asc
ordesc
(default:asc
)
Filtering
filter[field]
- Filter by specific field valuefilter[field][operator]
- Filter with specific operator (=
,!=
,>
,<
,>=
,<=
,like
,in
,between
)
๐ง Advanced Usage
Model Namespacing
The package supports flexible model namespacing to accommodate different project structures:
// Configuration examples for different model locations 'resources' => [ // Simple model in App\Models 'users' => [ 'model' => App\Models\User::class, // ... other config ], // Model in subfolder 'profiles' => [ 'model' => App\Models\User\Profile::class, // ... other config ], // Model in admin subfolder 'admin-users' => [ 'model' => App\Models\Admin\User::class, // ... other config ], // Model in completely different namespace 'products' => [ 'model' => Modules\Catalog\Models\Product::class, // ... other config ] ]
When using artisan commands, you can specify models in several ways:
# Simple class name (assumes App\Models namespace) php artisan make:crud-logic UserLogic --model=User # With subfolder (within App\Models) php artisan make:crud-logic ProfileLogic --model=User\\Profile # Full namespace php artisan make:crud-logic ProductLogic --model=Modules\\Catalog\\Models\\Product
Custom Logic Handlers
Create custom business logic for your resources:
# For a simple model in App\Models php artisan make:crud-logic UserLogic --model=User # For a model in a subfolder php artisan make:crud-logic ProfileLogic --model=User\\Profile # For a model with full namespace php artisan make:crud-logic AdminLogic --model=App\\Models\\Admin\\User
This generates:
<?php namespace App\Services\Crud; use AshiqueAr\LaravelCrudGenerator\Services\Crud\BaseCrudLogic; use App\Models\User; class UserLogic extends BaseCrudLogic { protected string $modelClass = User::class; public function beforeCreate(array $data, Request $request): array { // Add custom logic before creating $data['created_by'] = auth()->id(); return $data; } public function afterCreate(Model $user, Request $request): void { // Send welcome email Mail::to($user)->send(new WelcomeEmail($user)); } // Override other methods as needed }
Then update your configuration:
'users' => [ 'model' => App\Models\User::class, 'logic' => App\Services\Crud\UserLogic::class, 'fillable' => ['name', 'email', 'created_by'], 'rules' => [ 'store' => [ 'name' => 'required|string|max:255', 'email' => 'required|email|unique:users,email' ], 'update' => [ 'name' => 'sometimes|string|max:255', 'email' => 'sometimes|email|unique:users,email,{{id}}' ] ], // ... other configuration ]
Adding New Resources
Use the artisan command to quickly add new resources:
# For a simple model in App\Models php artisan make:crud-resource posts --model=Post # For a model in a subfolder php artisan make:crud-resource user-profiles --model=User\\Profile # For a model with full namespace php artisan make:crud-resource admin-users --model=App\\Models\\Admin\\User
This will interactively help you configure:
- Model class and table
- Fillable fields
- Validation rules
- Search and sort configuration
- Permissions
- Relations
- Custom logic handler (optional)
Bulk Operations
Perform operations on multiple resources:
# Bulk delete POST /api/v1/users/bulk { "operation": "delete", "ids": [1, 2, 3] } # Bulk update POST /api/v1/users/bulk { "operation": "update", "ids": [1, 2, 3], "data": { "status": "active" } } # Bulk restore (soft deletes) POST /api/v1/users/bulk { "operation": "restore", "ids": [1, 2, 3] }
Permissions
The package integrates seamlessly with Spatie Laravel Permission:
# Generate permissions for all resources php artisan crud:permissions # Generated permissions (for 'users' resource): # - view-users # - create-users # - edit-users # - delete-users
API Documentation
Access auto-generated documentation:
# Complete API documentation for all resources GET /api/v1/docs # Documentation for specific resource GET /api/v1/users/docs
Returns OpenAPI 3.0 compatible JSON that can be used with Swagger UI or similar tools.
๐ Configuration
The package uses a comprehensive configuration system in config/crud.php
. Here's a complete reference:
Global Configuration
<?php return [ // API defaults applied to all resources 'api' => [ 'pagination' => [ 'enabled' => true, 'per_page' => 15, 'max_per_page' => 100, ], 'documentation' => [ 'enabled' => true, 'title' => 'CRUD API Documentation', 'version' => '1.0.0', ], 'response' => [ 'include_timestamps' => true, 'include_meta' => true, ], ], // Permission settings (uses Spatie Laravel Permission) 'permissions' => [ 'enabled' => true, 'guard' => 'web', 'format' => '{action}-{resource}', 'actions' => ['view', 'create', 'edit', 'delete'], 'super_admin_role' => 'super-admin', ], // Global middleware for all routes 'middleware' => [ // 'auth:api', // 'throttle:60,1', ], // Search configuration defaults 'search' => [ 'default_operator' => 'like', 'case_sensitive' => false, 'operators' => [ 'like' => 'LIKE', 'exact' => '=', 'not_equal' => '!=', 'greater_than' => '>', 'less_than' => '<', 'greater_equal' => '>=', 'less_equal' => '<=', 'in' => 'IN', 'not_in' => 'NOT IN', 'between' => 'BETWEEN', 'starts_with' => 'LIKE', 'ends_with' => 'LIKE', ], ], // Resource definitions 'resources' => [ // Your resources here... ] ];
Resource Configuration Options
Each resource supports the following configuration options:
'resource_name' => [ // Required: The Eloquent model class 'model' => App\Models\YourModel::class, // Optional: Database table name (auto-detected if not provided) 'table' => 'your_table', // Optional: Custom logic class for business logic 'logic' => App\Services\Crud\YourModelLogic::class, // Mass assignment protection - fields that can be filled 'fillable' => ['field1', 'field2', 'field3'], // Fields to hide in API responses 'hidden' => ['password', 'secret_key'], // Validation rules for different operations 'rules' => [ 'store' => [ 'name' => 'required|string|max:255', 'email' => 'required|email|unique:users,email', ], 'update' => [ 'name' => 'sometimes|string|max:255', 'email' => 'sometimes|email|unique:users,email,{{id}}', ] ], // Search configuration 'search' => [ 'enabled' => true, 'fields' => ['name', 'email', 'description'], 'operator' => 'like' // default operator for this resource ], // Sorting configuration 'sort' => [ 'enabled' => true, 'fields' => ['name', 'created_at', 'updated_at'], 'default' => ['field' => 'created_at', 'direction' => 'desc'] ], // Filtering configuration 'filters' => [ 'enabled' => true, 'fields' => ['status', 'category_id', 'is_active'], 'operators' => [ 'status' => 'exact', 'category_id' => 'in', 'is_active' => 'exact' ] ], // Relationships to eager load 'relations' => ['category', 'tags', 'author'], // Permission settings for this resource 'permissions' => [ 'enabled' => true, 'middleware' => 'check.crud.permission' ], // Soft deletes support 'soft_deletes' => true, // Set to true if model uses SoftDeletes trait // Bulk operations configuration 'bulk_operations' => [ 'enabled' => true, 'operations' => ['delete', 'restore', 'update'] // Available operations ], // API-specific settings for this resource 'api' => [ 'paginate' => true, 'per_page' => 20, // Override global default 'max_per_page' => 50 // Override global default ], // Additional middleware for this resource only 'middleware' => ['auth:sanctum', 'role:admin'] ],
Validation Rule Placeholders
In validation rules, you can use placeholders that will be replaced during validation:
{{id}}
- The ID of the current resource (useful for unique rules in updates){{user_id}}
- The ID of the authenticated user{{resource}}
- The name of the current resource
Example:
'rules' => [ 'update' => [ 'email' => 'required|email|unique:users,email,{{id}}', 'slug' => 'required|string|unique:posts,slug,{{id}}' ] ]
๐งช Testing
Run the package tests:
composer test
Run tests with coverage:
composer test-coverage
๐ Configuration
See the Configuration Guide for detailed configuration options.
๐ Changelog
Please see CHANGELOG for more information on what has changed recently.
๐ค Contributing
Please see CONTRIBUTING for details.
๐ Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
๐ License
The MIT License (MIT). Please see License File for more information.
๐ Credits
๐ก Support
Made with โค๏ธ for the Laravel community