Upgrade make:module command with full ServiceProvider structure
Enhanced make:module command: - Added --model flag for creating model + migration + Filament resource - Added --api flag for including API routes - Added --no-filament flag to skip Filament resource - Creates full ServiceProvider structure with auto-registration - Creates Config, Permissions, Routes, Views, Tests - Module migrations stored in module folder - Filament resources stored in module folder - Auto-registers ServiceProvider in bootstrap/providers.php Also added: - ModuleAuditable trait for audit trail support - Updated Modules README to document new command options
This commit is contained in:
@@ -1,94 +1,128 @@
|
||||
# Module System
|
||||
|
||||
> **🤖 AI Agents**: For EXACT file templates, see [CLAUDE.md](../../../CLAUDE.md)
|
||||
|
||||
This Laravel application uses a modular architecture to organize features into self-contained modules.
|
||||
|
||||
## Creating a New Module
|
||||
|
||||
Use the artisan command to scaffold a complete module:
|
||||
|
||||
```bash
|
||||
# Basic module (no model)
|
||||
php artisan make:module ProductCatalog
|
||||
|
||||
# With a model + Filament resource
|
||||
php artisan make:module ProductCatalog --model=Product
|
||||
|
||||
# With API routes
|
||||
php artisan make:module ProductCatalog --model=Product --api
|
||||
|
||||
# Without Filament admin
|
||||
php artisan make:module ProductCatalog --model=Product --no-filament
|
||||
```
|
||||
|
||||
This creates:
|
||||
- **Model**: `app/Modules/ProductCatalog/Models/ProductCatalog.php`
|
||||
- **Controller**: `app/Modules/ProductCatalog/Controllers/ProductCatalogController.php`
|
||||
- **Routes**: `app/Modules/ProductCatalog/routes.php`
|
||||
- **Views**: `app/Modules/ProductCatalog/Views/`
|
||||
- **Migration**: `database/migrations/YYYY_MM_DD_HHMMSS_create_product_catalogs_table.php`
|
||||
- **Filament Resource**: `app/Filament/Resources/ProductCatalogResource.php`
|
||||
- **Tests**: `tests/Modules/ProductCatalog/ProductCatalogTest.php`
|
||||
|
||||
## Module Structure
|
||||
## What Gets Created
|
||||
|
||||
### Basic module (`make:module Name`):
|
||||
```
|
||||
app/Modules/
|
||||
└── ProductCatalog/
|
||||
├── Models/
|
||||
│ └── ProductCatalog.php
|
||||
├── Controllers/
|
||||
│ └── ProductCatalogController.php
|
||||
├── Views/
|
||||
│ ├── index.blade.php
|
||||
│ ├── create.blade.php
|
||||
│ ├── edit.blade.php
|
||||
│ └── show.blade.php
|
||||
└── routes.php
|
||||
app/Modules/Name/
|
||||
├── Config/name.php # Module config
|
||||
├── Database/Migrations/ # Module migrations
|
||||
├── Database/Seeders/
|
||||
├── Filament/Resources/ # Admin resources
|
||||
├── Http/Controllers/NameController.php
|
||||
├── Http/Middleware/
|
||||
├── Http/Requests/
|
||||
├── Models/
|
||||
├── Policies/
|
||||
├── Services/
|
||||
├── Routes/web.php # Frontend routes
|
||||
├── Resources/views/index.blade.php
|
||||
├── Permissions.php # Module permissions
|
||||
└── NameServiceProvider.php # Auto-registered
|
||||
```
|
||||
|
||||
## Registering Module Routes
|
||||
### With `--model=Product`:
|
||||
Adds:
|
||||
- `Models/Product.php` (with auditing)
|
||||
- `Database/Migrations/create_products_table.php`
|
||||
- `Filament/Resources/ProductResource.php` (full CRUD)
|
||||
|
||||
After creating a module, register its routes in `routes/web.php`:
|
||||
|
||||
```php
|
||||
require __DIR__.'/../app/Modules/ProductCatalog/routes.php';
|
||||
```
|
||||
### With `--api`:
|
||||
Adds:
|
||||
- `Routes/api.php` (Sanctum-protected)
|
||||
|
||||
## Module Features
|
||||
|
||||
Each module includes:
|
||||
|
||||
✅ **CRUD Operations** - Full Create, Read, Update, Delete functionality
|
||||
✅ **Authentication** - Routes protected by auth middleware
|
||||
✅ **Filament Admin** - Auto-generated admin panel resource
|
||||
✅ **Blade Views** - Responsive Tailwind CSS templates
|
||||
✅ **Tests** - Pest test suite for module functionality
|
||||
✅ **Permissions** - Ready for role-based access control
|
||||
✅ **ServiceProvider** - Auto-registered, loads routes/views/migrations
|
||||
✅ **Config** - Module-specific settings with audit configuration
|
||||
✅ **Permissions** - Pre-defined CRUD permissions
|
||||
✅ **Filament Admin** - Full CRUD resource with navigation group
|
||||
✅ **Auditing** - Track all changes via ModuleAuditable trait
|
||||
✅ **Tests** - Feature tests with permission checks
|
||||
|
||||
## Example Usage
|
||||
|
||||
```bash
|
||||
# Create an Inventory module
|
||||
php artisan make:module Inventory
|
||||
# Create a Stock Management module with Product model
|
||||
php artisan make:module StockManagement --model=Product --api
|
||||
|
||||
# Run migrations
|
||||
php artisan migrate
|
||||
|
||||
# Register routes in routes/web.php
|
||||
require __DIR__.'/../app/Modules/Inventory/routes.php';
|
||||
# Seed permissions
|
||||
php artisan db:seed --class=RolePermissionSeeder
|
||||
|
||||
# Access at: http://localhost:8080/inventory
|
||||
# Admin panel: http://localhost:8080/admin/inventories
|
||||
# Clear caches
|
||||
php artisan optimize:clear
|
||||
```
|
||||
|
||||
## Adding Permissions
|
||||
**Access:**
|
||||
- Frontend: `http://localhost:8080/stock-management`
|
||||
- Admin: `http://localhost:8080/admin` → Stock Management section
|
||||
- API: `http://localhost:8080/api/stock-management`
|
||||
|
||||
To add module-specific permissions:
|
||||
## Permissions
|
||||
|
||||
Each module creates these permissions in `Permissions.php`:
|
||||
|
||||
```php
|
||||
// In database/seeders/RolePermissionSeeder.php
|
||||
$permissions = [
|
||||
'inventory.view',
|
||||
'inventory.create',
|
||||
'inventory.edit',
|
||||
'inventory.delete',
|
||||
return [
|
||||
'stock_management.view' => 'View Stock Management',
|
||||
'stock_management.create' => 'Create Stock Management records',
|
||||
'stock_management.edit' => 'Edit Stock Management records',
|
||||
'stock_management.delete' => 'Delete Stock Management records',
|
||||
];
|
||||
```
|
||||
|
||||
Use in Blade:
|
||||
```blade
|
||||
@can('stock_management.view')
|
||||
<a href="{{ route('stock-management.index') }}">Stock</a>
|
||||
@endcan
|
||||
```
|
||||
|
||||
Use in Controller:
|
||||
```php
|
||||
$this->authorize('stock_management.view');
|
||||
```
|
||||
|
||||
## Audit Configuration
|
||||
|
||||
Edit `Config/module_name.php`:
|
||||
|
||||
```php
|
||||
'audit' => [
|
||||
'enabled' => true,
|
||||
'strategy' => 'all', // 'all', 'include', 'exclude', 'none'
|
||||
'include' => [], // Fields to audit (if strategy='include')
|
||||
'exclude' => ['password'], // Fields to exclude
|
||||
],
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Keep modules self-contained** - Each module should be independent
|
||||
2. **Use namespaces** - Follow the `App\Modules\{ModuleName}` pattern
|
||||
3. **Test your modules** - Run `php artisan test` after creating
|
||||
4. **Document changes** - Update module README if you modify structure
|
||||
5. **Use Filament** - Leverage the admin panel for quick CRUD interfaces
|
||||
1. **Keep modules independent** - Avoid tight coupling between modules
|
||||
2. **Use Services** - Put business logic in `Services/`, not controllers
|
||||
3. **Define clear permissions** - One permission per action
|
||||
4. **Test your modules** - Run `php artisan test` after creating
|
||||
5. **Use Filament** - Leverage admin panel for quick CRUD
|
||||
|
||||
Reference in New Issue
Block a user