Profile Filament Plugin Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require rawilk/profile-filament-plugin
   php artisan vendor:publish --tag="profile-filament-migrations"
   php artisan vendor:publish --tag="profile-filament-config"
   php artisan migrate
   

2. Panel Registration (in AdminPanelProvider):

   use Rawilk\ProfileFilament\ProfileFilamentPlugin;
   
   public function panel(Panel $panel): Panel {
       return $panel
           ->plugin(ProfileFilamentPlugin::make());
   }
   

3. User Model Setup:

   use Rawilk\ProfileFilament\Auth\Multifactor\Concerns\InteractsWithMultiFactorAuthentication;
   use Rawilk\ProfileFilament\Auth\Multifactor\Contracts\HasMultiFactorAuthentication;
   
   class User extends Authenticatable implements HasMultiFactorAuthentication {
       use InteractsWithMultiFactorAuthentication;
   }
   

4. Custom Login Page (optional but recommended for MFA):

   use Filament\Auth\Pages\Login;
   use Rawilk\ProfileFilament\Auth\Login\Concerns\HandlesLoginForm;
   
   class CustomLogin extends Login {
       use HandlesLoginForm;
   }
   

   Register in panel provider:

   ->login(CustomLogin::class)
   

First Use Case

Enable basic profile + MFA with email provider:

ProfileFilamentPlugin::make()
    ->multiFactorAuthentication([
        \Rawilk\ProfileFilament\Auth\Multifactor\Providers\EmailAuthenticationProvider::make(),
    ]);

Implementation Patterns

Core Workflows

1. Profile Management:

   • Extend the default profile page by publishing views:

     php artisan vendor:publish --tag="profile-filament-views"
     

   • Customize fields via plugin configuration:

     ProfileFilamentPlugin::make()
         ->profileFields([
             \Filament\Forms\Components\TextInput::make('custom_field')
                 ->required(),
         ]);
     

2. MFA Integration:

   • Provider Chaining: Combine multiple MFA methods:

     ->multiFactorAuthentication([
         \Rawilk\ProfileFilament\Auth\Multifactor\Providers\AppAuthenticationProvider::make(),
         \Rawilk\ProfileFilament\Auth\Multifactor\Providers\WebAuthnAuthenticationProvider::make(),
     ])
     

   • Passkey Support: Enable WebAuthn for passwordless login:

     ->multiFactorAuthentication([
         \Rawilk\ProfileFilament\Auth\Multifactor\Providers\WebAuthnAuthenticationProvider::make()
             ->withPasskeyLogin(),
     ])
     

3. Authentication Pipeline:

   • Customize login logic via pipeline:

     ProfileFilamentPlugin::make()
         ->sendLoginThrough([
             \App\Actions\Auth\Login\CustomValidation::class,
             \Rawilk\ProfileFilament\Auth\Login\AuthenticationPipes\AttemptToAuthenticateUser::class,
         ]);
     

4. Session Management:

   • Override session handling:

     ProfileFilamentPlugin::make()
         ->sessionManagement([
             \Rawilk\ProfileFilament\Auth\Session\Concerns\HandlesSessionTimeout::class,
             \App\Actions\Auth\Session\CustomLogout::class,
         ]);
     

Integration Tips

• Filament Pages: Extend existing pages (e.g., ProfilePage) by publishing views and overriding methods.
• Event Listeners: Hook into MFA events for custom logic:

  event(new \Rawilk\ProfileFilament\Events\MultiFactorAuthenticated($user));
  

• Testing: Use the provided test helpers:

  $this->actingAs($user)
       ->withMfaEnabled()
       ->assertCanAccessProfile();
  

Gotchas and Tips

Common Pitfalls

1. MFA Provider Conflicts:

   • ❌ Error: "MFA providers already registered"
   • ✅ Fix: Ensure no duplicate providers in multiFactorAuthentication() array.

2. Missing User Model Trait:

   • ❌ Error: Call to undefined method User::hasMultiFactorAuthentication()
   • ✅ Fix: Add InteractsWithMultiFactorAuthentication trait to your User model.

3. Login Page Mismatch:

   • ❌ Error: MFA challenge not triggered
   • ✅ Fix: Always use HandlesLoginForm trait in custom login pages.

4. Database Migrations:

   • ❌ Error: Column not found: mfa_secret
   • ✅ Fix: Run migrations after publishing:

     php artisan migrate
     

Debugging Tips

• Enable Debug Mode:

  ProfileFilamentPlugin::make()
      ->debug(true); // Logs MFA/Profile events to Laravel logs
  

• Check MFA Status:

  $user->hasMultiFactorAuthentication(); // Returns bool
  $user->getMultiFactorAuthenticationProviders(); // Returns array of enabled providers
  

• Reset MFA:

  $user->disableMultiFactorAuthentication();
  $user->forceDeleteMultiFactorAuthentication();
  

Extension Points

1. Custom MFA Providers:

   • Extend AbstractAuthenticationProvider:

     class CustomProvider extends AbstractAuthenticationProvider {
         public function verify($user, $code) { ... }
         public function generateCode($user) { ... }
     }
     

2. Profile Widgets:

   • Add custom widgets to the profile page:

     ProfileFilamentPlugin::make()
         ->profileWidgets([
             \App\Widgets\CustomProfileWidget::class,
         ]);
     

3. Session Customization:

   • Override session timeout logic:

     ProfileFilamentPlugin::make()
         ->sessionManagement([
             \App\Actions\Auth\Session\CustomTimeout::class,
         ]);
     

4. Email Templates:

   • Publish and override email templates:

     php artisan vendor:publish --tag="profile-filament-views"
     

   • Customize paths in config/profile-filament.php:

     'email' => [
         'prefix' => 'app.Emails.',
         'paths' => [
             resource_path('views/vendor/profile-filament/emails'),
         ],
     ],
     

Configuration Quirks

• Default Values: The plugin uses sensible defaults (e.g., TOTP length = 6, email code expiry = 5 minutes). Override in config/profile-filament.php:

  'mfa' => [
      'app' => [
          'secret_length' => 8,
      ],
      'email' => [
          'code_expiry_minutes' => 10,
      ],
  ],
  

• Passkey Requirements: WebAuthn requires HTTPS in production. Test locally with:

  ->webAuthn([
      'require_https' => env('APP_ENV') !== 'local',
  ]);
  

• Rate Limiting: MFA attempts are rate-limited by default (5 attempts/minute). Adjust in config:

  'mfa' => [
      'rate_limiting' => [
          'max_attempts' => 3,
          'decay_minutes' => 2,
      ],
  ],