Filament Authentication Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation Run:

   composer require phpsa/filament-authentication
   php artisan filament-authentication:install
   

   This publishes migrations, config, and sets up Spatie Permissions if not already configured.

2. Run Migrations

   php artisan migrate
   

   Ensures the users, roles, and permissions tables are created.

3. Register the Resource Add the FilamentAuthentication\Resources\UserResource to your app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->resources([
               // ... other resources
               \FilamentAuthentication\Resources\UserResource::class,
           ]);
   }
   

4. Access the Admin Panel Visit /admin and navigate to the Users section to manage users, roles, and permissions.

First Use Case: Creating a Super Admin

1. Create a User

   • Go to Users → Create User.
   • Fill in details (e.g., name, email, password).
   • Assign the super-admin role (created by default during installation).

2. Verify Permissions

   • Check the Roles & Permissions tab in the user edit view.
   • Ensure the user has all necessary permissions (e.g., access admin panels).

Implementation Patterns

Core Workflows

1. User Management

• Bulk Actions: Use the table’s bulk actions to assign roles/permissions to multiple users.
• Search/Filter: Leverage Filament’s built-in search (name, email) and filters (e.g., role).
• Custom Fields: Extend the UserResource to add custom fields (e.g., department):

  // app/Filament/Resources/UserResource.php
  public static function form(Form $form): Form
  {
      return $form
          ->schema([
              // ... default fields
              TextInput::make('department')->required(),
          ]);
  }
  

2. Role & Permission Management

• Role Hierarchy: Use Spatie’s hasRole() or givePermissionTo() in policies:

  // app/Policies/UserPolicy.php
  public function viewAny(User $user)
  {
      return $user->hasRole('admin');
  }
  

• Permission Groups: Organize permissions into groups (e.g., Management, Content) in config/permission.php.

3. Integration with Filament Policies

• Restrict resource access in AdminPanelProvider:

  ->resources([
      UserResource::class, // Only accessible to admins
  ])
  ->policy(UserResource::class, UserPolicy::class),
  

4. Custom Authentication Logic

• Override login logic by extending the FilamentAuthentication\Auth\Login class or using Filament’s built-in auth callbacks.

Integration Tips

With Filament’s Tenancy

If using spatie/laravel-tenancy, extend the UserResource to include tenant-specific fields:

public static function table(Table $table): Table
{
    return $table
        ->columns([
            // ... default columns
            TextColumn::make('current_tenant_id')->numeric(),
        ]);
}

With Filament Notifications

Trigger notifications on user creation/role assignment:

// app/Filament/Resources/UserResource.php
protected static function afterCreate(array $data): void
{
    Notification::send($data['user'], new UserCreatedNotification());
}

API Access

Expose user management via API by creating a Filament API resource:

php artisan make:filament-resource UserApiResource --api

Reuse the same logic as UserResource but restrict fields/methods.

Gotchas and Tips

Pitfalls

1. Missing Spatie Permissions Setup

   • If spatie/laravel-permission isn’t installed, the package will fail silently. Ensure you run:

     composer require spatie/laravel-permission
     php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"
     php artisan migrate
     

2. Role/Permission Caching

   • Spatie caches roles/permissions. Clear the cache after manual DB changes:

     php artisan cache:clear
     php artisan config:clear
     

3. Filament Resource Conflicts

   • Avoid naming conflicts with existing User resources. Use a unique namespace (e.g., App\Filament\Resources\AdminUserResource).

4. Password Hashing

   • The package uses Laravel’s default hashing. For custom hashing (e.g., bcrypt with custom cost), override the User model’s setPasswordAttribute.

Debugging

1. Permission Denied Errors

   • Check the filament-authentication.log (if enabled in config) or enable debug mode:

     // config/filament.php
     'debug' => env('FILAMENT_DEBUG', true),
     

   • Verify roles/permissions in the DB:

     SELECT * FROM model_has_roles WHERE model_type = 'App\Models\User';
     

2. Migration Issues

   • If migrations fail, rollback and re-run:

     php artisan migrate:rollback
     php artisan migrate --force
     

3. Resource Not Showing

   • Ensure the resource is registered in AdminPanelProvider and the user has the access admin panels permission.

Tips

1. Custom Role Names Modify default roles (e.g., super-admin) in the UserResource:

   // app/Filament/Resources/UserResource.php
   public static function getRelations(): array
   {
       return [
           Relationships\BelongsToMany::make('roles')
               ->relationshipName('roles')
               ->title('Roles')
               ->items([
                   'admin', 'editor', 'viewer', // Customize as needed
               ]),
       ];
   }
   

2. Bulk Role Assignment Use the table’s bulk edit feature to assign roles to multiple users without opening each record.

3. Audit Logging Enable Filament’s audit logs for user/role changes:

   // config/filament.php
   'audit_logging' => true,
   

4. Localization Publish translations for multi-language support:

   php artisan vendor:publish --tag=filament-authentication-translations
   

5. Testing Use Filament’s testing helpers to assert UI interactions:

   $this->actingAs($user)
       ->get('/admin/users')
       ->assertSee('Users');