Filament Access Control Laravel Package

Getting Started

Minimal Setup Steps

1. Installation

   composer require chiiya/filament-access-control
   php artisan vendor:publish --provider="Chiiya\FilamentAccessControl\FilamentAccessControlServiceProvider"
   php artisan migrate
   

   • Publishes config (config/filament-access-control.php) and migrations.

2. Register Resources Add to app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->default()
           ->id('admin')
           ->path('admin')
           ->middleware([
               'auth',
               'verified',
               'password.confirmed',
           ])
           ->registration()
           ->discoverResources(in: app_path('Filament/Resources'), for: 'Chiiya\FilamentAccessControl\Http\Resources')
           ->discoverPages(in: app_path('Filament/Pages'), for: 'Chiiya\FilamentAccessControl\Http\Pages');
   }
   

3. First Use Case

   • Access /admin to see pre-built Admin Users, Roles, and Permissions CRUD resources.
   • Create a super-admin via CLI:

     php artisan filament-access-control:create-super-admin --email=admin@example.com
     

   • Follow the email link to set a password.

Implementation Patterns

Core Workflows

1. Admin User Management

   • Creation: Use the built-in resource or programmatically:

     use Chiiya\FilamentAccessControl\Models\AdminUser;
     
     $admin = AdminUser::create([
         'email' => 'user@example.com',
         'name' => 'Test Admin',
         'role_id' => 1, // Optional: Assign role
     ]);
     // User will receive a password reset email (no password set initially).
     

   • Password Handling: Use AdminUser::sendPasswordResetLink() or leverage Filament’s built-in password reset.

2. Role & Permission Assignment

   • Direct Permissions: Assign via AdminUser model:

     $admin->givePermissionTo('edit-posts');
     

   • Role-Based Permissions: Use Spatie’s Role model:

     use Spatie\Permission\Models\Role;
     
     $role = Role::find(1);
     $role->givePermissionTo(['edit-posts', 'delete-posts']);
     $admin->assignRole($role);
     

   • Policy Integration: Extend Filament policies:

     use Chiiya\FilamentAccessControl\Policies\AdminUserPolicy;
     
     class PostPolicy extends AdminUserPolicy
     {
         public function edit(AdminUser $user, Post $post)
         {
             return $user->hasPermissionTo('edit-posts');
         }
     }
     

3. Resource Customization

   • Override default resources by publishing and modifying:

     php artisan vendor:publish --tag="filament-access-control-resources"
     

   • Extend tables/columns in app/Filament/Resources/AdminUserResource.php:

     public static function table(Table $table): Table
     {
         return $table
             ->columns([
                 // Custom columns...
                 Columns\TextColumn::make('last_login')
                     ->dateTime('d/m/Y H:i')
                     ->sortable(),
             ]);
     }
     

4. Guard & Authentication

   • Use the admin guard in Filament:

     public function panel(Panel $panel): Panel
     {
         return $panel
             ->authGuard('admin') // Use admin guard
             ->discoverResources(...);
     }
     

   • Protect routes:

     Route::middleware(['auth:admin'])->group(function () {
         // Admin-only routes
     });
     

5. Localization

   • Override translations in resources/lang/{locale}/filament-access-control.php:

     return [
         'admin_user' => [
             'resources' => [
                 'singular' => 'Administrator',
                 'plural' => 'Administrators',
             ],
         ],
     ];
     

Gotchas and Tips

Pitfalls

1. Guard Misconfiguration

   • Issue: Forgetting to set authGuard('admin') in AdminPanelProvider causes login failures.
   • Fix: Explicitly define the guard:

     ->authGuard('admin')
     ->authMiddleware(['web', 'auth:admin'])
     

2. Permission Caching

   • Issue: Spatie’s permission cache may cause stale data after role/permission updates.
   • Fix: Clear cache after bulk operations:

     Spatie\Permission\Permission::cacheResolved();
     

3. Password Reset Edge Cases

   • Issue: Users created via API (not Filament) won’t receive password emails.
   • Fix: Manually trigger the email:

     $admin->sendPasswordResetNotification();
     

4. Role-Only vs. Permission-Only Conflicts

   • Issue: Mixing direct permissions and role assignments can lead to unintended access.
   • Tip: Use roles for broad access and direct permissions for exceptions:

     $admin->assignRole('editor'); // Broad access
     $admin->givePermissionTo('publish-posts'); // Exception
     

5. Resource Override Pitfalls

   • Issue: Custom resources may break if not properly namespaced.
   • Fix: Ensure overrides extend the base resource:

     class CustomAdminUserResource extends \Chiiya\FilamentAccessControl\Http\Resources\AdminUserResource
     

Debugging Tips

1. Check Guard Configuration

   • Verify config/auth.php includes the admin guard:

     'guards' => [
         'admin' => [
             'driver' => 'session',
             'provider' => 'admins',
         ],
     ],
     

2. Log Permission Checks

   • Enable Spatie’s debug mode in config/permission.php:

     'debug' => env('PERMISSION_DEBUG', false),
     

3. Test with tinker

   • Quickly test permissions:

     php artisan tinker
     >>> $admin = \Chiiya\FilamentAccessControl\Models\AdminUser::first();
     >>> $admin->hasPermissionTo('edit-posts');
     

Extension Points

1. Custom Admin User Model

   • Extend the model by publishing and modifying:

     php artisan vendor:publish --tag="filament-access-control-model"
     

   • Add fields (e.g., department_id):

     class AdminUser extends \Chiiya\FilamentAccessControl\Models\AdminUser
     {
         protected $fillable = ['department_id', ...];
     }
     

2. Custom Registration Logic

   • Override the create-super-admin command:

     php artisan make:command CreateCustomSuperAdmin
     

   • Extend Chiiya\FilamentAccessControl\Console\Commands\CreateSuperAdmin.

3. Custom Permission Tables

   • Use Spatie’s Permission model to add custom tables:

     $permission = Permission::create(['name' => 'manage-departments', 'table' => 'departments']);
     

4. Webhook Triggers

   • Listen for AdminUserCreated events:

     use Chiiya\FilamentAccessControl\Events\AdminUserCreated;
     
     AdminUserCreated::listen(function ($admin) {
         // Send Slack notification, etc.
     });
     

5. API Integration

   • Use the AdminUser model in API routes:

     Route::post('/admin/users', function (Request $request) {
         $admin = AdminUser::create($request->validate([
             'email' => 'required|email',
             'name' => 'required',
         ]));
         return response()->json($admin);
     })->middleware('auth:admin');