theRADcozaDEV
f903914c2b
RolePermissionSeeder now automatically scans app/Modules/*/Permissions.php files and registers all permissions found. No manual registration required. - Added loadModulePermissions() method to scan module directories - Changed givePermissionTo() to syncPermissions() for idempotency - Updated Modules README to document auto-loading - Updated CLAUDE.md to reflect auto-loading behavior
132 lines
3.7 KiB
Markdown
132 lines
3.7 KiB
Markdown
# 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
|
|
|
|
```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
|
|
```
|
|
|
|
## What Gets Created
|
|
|
|
### Basic module (`make:module Name`):
|
|
```
|
|
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
|
|
```
|
|
|
|
### With `--model=Product`:
|
|
Adds:
|
|
- `Models/Product.php` (with auditing)
|
|
- `Database/Migrations/create_products_table.php`
|
|
- `Filament/Resources/ProductResource.php` (full CRUD)
|
|
|
|
### With `--api`:
|
|
Adds:
|
|
- `Routes/api.php` (Sanctum-protected)
|
|
|
|
## Module Features
|
|
|
|
✅ **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 a Stock Management module with Product model
|
|
php artisan make:module StockManagement --model=Product --api
|
|
|
|
# Run migrations
|
|
php artisan migrate
|
|
|
|
# Seed permissions
|
|
php artisan db:seed --class=RolePermissionSeeder
|
|
|
|
# Clear caches
|
|
php artisan optimize:clear
|
|
```
|
|
|
|
**Access:**
|
|
- Frontend: `http://localhost:8080/stock-management`
|
|
- Admin: `http://localhost:8080/admin` → Stock Management section
|
|
- API: `http://localhost:8080/api/stock-management`
|
|
|
|
## Permissions
|
|
|
|
Each module creates these permissions in `Permissions.php`:
|
|
|
|
```php
|
|
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',
|
|
];
|
|
```
|
|
|
|
**Permissions are auto-loaded!** When you run `php artisan db:seed --class=RolePermissionSeeder`,
|
|
it scans all `app/Modules/*/Permissions.php` files and registers them automatically.
|
|
|
|
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 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
|