Filament Registration Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require tallcms/filament-registration
   

   Publish the package assets and config:

   php artisan vendor:publish --provider="TallCms\FilamentRegistration\FilamentRegistrationServiceProvider" --tag="filament-registration-config"
   php artisan vendor:publish --provider="TallCms\FilamentRegistration\FilamentRegistrationServiceProvider" --tag="filament-registration-migrations"
   

   Run migrations:

   php artisan migrate
   

2. Configure Edit config/filament-registration.php to set:

   • Default role assignment (default_role).
   • Captcha provider (e.g., cloudflare_turnstile or google_recaptcha_v3).
   • API keys for captcha services.

3. First Use Case Register a new user via the Filament registration form:

   • Visit /register (or your configured route).
   • Fill in the form (email, password, captcha).
   • Submit to create a user with the default_role.

Implementation Patterns

Core Workflows

1. Customizing the Registration Form Extend the default form using Filament’s form builder:

   use TallCms\FilamentRegistration\Forms\RegistrationForm;
   
   RegistrationForm::make()
       ->columns(2)
       ->addFields([
           // Custom fields (e.g., name, terms checkbox)
           TextInput::make('name')->required(),
           Checkbox::make('terms')->required()->label('Accept Terms'),
       ]);
   

2. Role Assignment Logic Override default role assignment in AppServiceProvider:

   use TallCms\FilamentRegistration\Events\Registering;
   
   Registering::macro('assignRole', function ($user, $roleName) {
       $user->assignRole($roleName);
   });
   

3. Captcha Integration Configure captcha in config/filament-registration.php:

   'captcha' => [
       'provider' => 'cloudflare_turnstile',
       'cloudflare_turnstile_site_key' => env('CLOUDFLARE_TURNSTILE_SITE_KEY'),
       'google_recaptcha_v3_site_key' => env('GOOGLE_RECAPTCHA_SITE_KEY'),
   ],
   

   Validate captcha in a custom form:

   use TallCms\FilamentRegistration\Concerns\ValidatesCaptcha;
   
   class CustomRegistrationForm extends RegistrationForm {
       use ValidatesCaptcha;
   }
   

4. Email Verification Extend the default email verification logic:

   use TallCms\FilamentRegistration\Events\Registered;
   
   Registered::listen(function ($user) {
       $user->sendEmailVerificationNotification();
   });
   

Integration Tips

• Laravel Fortify: Works seamlessly with Fortify’s registration system.
• Filament Panels: Register the form in a custom panel:

  use TallCms\FilamentRegistration\Pages\Register;
  
  Register::register();
  

• Multi-Auth: Use middleware to restrict registration to specific users:

  Register::middleware(['auth', 'can:register-users']);
  

Gotchas and Tips

Common Pitfalls

1. Captcha Validation Failures

   • Ensure API keys are correctly set in .env and config.
   • Debug captcha responses with:

     dd($request->input('cf-turnstile-response')); // Cloudflare
     dd($request->input('g-recaptcha-response')); // Google
     

2. Role Assignment Conflicts

   • If default_role is not assigned, verify:
     • The role exists in the database.
     • The assignRole macro is properly bound (check AppServiceProvider).

3. Migration Issues

   • Run php artisan migrate:fresh if the filament_registration table is corrupted.
   • Ensure the users table has a role_id column if using role assignment.

4. Form Submission Redirects

   • Override redirects in the Register page:

     public function getRedirectUrl(): string {
         return route('filament.pages.dashboard');
     }
     

Debugging Tips

• Log Registration Events Listen to events in AppServiceProvider:

  Registered::listen(function ($user) {
      \Log::info('User registered: ' . $user->email);
  });
  

• Disable Captcha Temporarily Set 'captcha' => ['enabled' => false] in config for testing.

• Custom Validation Extend the form’s validation rules:

  public static function getValidationRules(): array {
      return [
          ...parent::getValidationRules(),
          'name' => 'required|string|max:255',
      ];
  }
  

Extension Points

1. Custom Registration Logic Override the create method in a custom form:

   public function create(array $data): User {
       $user = parent::create($data);
       // Custom logic (e.g., send welcome email)
       return $user;
   }
   

2. Dynamic Role Assignment Use a closure in the config:

   'default_role' => function ($user) {
       return $user->email === '[email protected]' ? 'admin' : 'user';
   },
   

3. Multi-Language Support Translate form fields via Filament’s localization:

   TextInput::make('name')
       ->label(__('filament-registration::registration.name'))
       ->required(),