Filament User Laravel Package

Getting Started

Minimal Setup

1. Prerequisites: Ensure filament-shield is installed (composer require bezhansalleh/filament-shield).
2. Installation: Run composer require 3x1io/filament-user.
3. Publish Config/Translations:

   php artisan vendor:publish --tag="filament-user-config"
   php artisan vendor:publish --tag="filament-user-translations"
   

4. Clear Cache:

   php artisan optimize:clear
   

5. Publish Resource (optional but recommended for customization):

   php artisan filament-user:publish
   

   Set publish_resource = true in config/filament-user.php.

First Use Case

• Access the User Resource: Navigate to /admin/resources/users in your Filament admin panel.
• Default Features: Out-of-the-box CRUD for users, with fields like name, email, password, is_admin, and last_login_at.

Implementation Patterns

Core Workflows

1. User Management:

   • Create/Edit Users: Use the Filament UI to manage users via the resource panel.
   • Bulk Actions: Leverage Filament’s built-in bulk actions (e.g., delete, toggle is_admin) via the table actions dropdown.

2. Authentication Integration:

   • Login/Registration: The package assumes Laravel’s default auth system. Extend App\Models\User if using custom fields.
   • Password Reset: Uses Laravel’s default password reset flow (no additional setup needed).

3. Role/Permission Sync:

   • Filament-Shield Integration: Roles/permissions from filament-shield are automatically reflected in the is_admin field. Customize via:

     // config/filament-user.php
     'shield_roles' => ['admin', 'editor'], // Sync these roles to `is_admin`
     

4. Custom Fields:

   • Extend the Resource: After publishing (publish_resource = true), modify app/Filament/Resources/UserResource.php to add fields:

     public static function form(Form $form): Form
     {
         return $form
             ->schema([
                 // Default fields...
                 TextInput::make('custom_field')->required(),
             ]);
     }
     

5. API Access:

   • Expose via API: Use Filament’s API resources or create a separate API resource to interact with users programmatically.

Integration Tips

• Laravel Fortify/Passport: Works seamlessly with Laravel’s auth packages. No conflicts if using filament-shield for permissions.
• Multi-Tenancy: Add tenant-specific logic in the UserResource (e.g., filter users by tenant_id):

  public static function table(Table $table): Table
  {
      return $table
          ->query(fn (Builder $query) => $query->where('tenant_id', auth()->user()->tenant_id));
  }
  

• Notifications: Trigger custom notifications on user creation/update via Filament’s afterCreate/afterUpdate hooks:

  protected static function afterCreate(User $record): void
  {
      Notification::route('mail', $record->email)->notify(new WelcomeNotification());
  }
  

Gotchas and Tips

Pitfalls

1. Missing filament-shield:

   • Error: Class 'FilamentShield\FilamentShield' not found.
   • Fix: Install filament-shield first (composer require bezhansalleh/filament-shield).

2. Resource Not Publishing:

   • Issue: Resource doesn’t appear after filament-user:publish.
   • Debug: Check publish_resource in config/filament-user.php is set to true and run composer dump-autoload.

3. Field Conflicts:

   • Problem: Custom fields in UserResource clash with default fields.
   • Solution: Override the resource fully by copying the published file to app/Filament/Resources/ and modifying it.

4. Permission Denied:

   • Cause: is_admin field not syncing with filament-shield roles.
   • Fix: Ensure shield_roles in config/filament-user.php matches your filament-shield role names.

Debugging

• Log User Actions: Add logging in UserResource hooks:

  protected static function afterSave(User $record): void
  {
      \Log::info("User updated: {$record->email}", ['action' => 'update']);
  }
  

• Check Queries: Use Laravel Debugbar to inspect queries if users aren’t filtering correctly.

Extension Points

1. Custom Auth Logic:

   • Override app/Providers/FilamentUserServiceProvider.php to extend auth logic:

     public function boot(): void
     {
         User::observe(UserObserver::class);
     }
     

2. Dynamic Fields:

   • Use Filament’s dynamic forms to show/hide fields based on conditions:

     TextInput::make('api_token')
         ->visible(fn ($record) => $record->is_admin),
     

3. Webhooks:

   • Trigger external actions (e.g., Slack notifications) via Filament’s afterCreate/afterDelete:

     protected static function afterCreate(User $record): void
     {
         Http::post('https://slack.com/webhook', ['text' => "New user: {$record->email}"]);
     }
     

4. Testing:

   • Use Filament’s testing helpers to assert user management:

     $this->filament()->actingAs(User::factory()->create(['is_admin' => true]))
         ->get('/admin/resources/users')
         ->assertOk();
     

Config Quirks

• shield_roles Array: Must match exactly the role names defined in filament-shield. Case-sensitive.
• Default Sorting: Override table sorting in UserResource:

  public static function table(Table $table): Table
  {
      return $table->defaultSort('created_at', 'desc');
  }
  

• Translation Keys: Customize labels via resources/lang/vendor/filament-user/ after publishing translations.