Filament Jetstream Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require stephenjude/filament-jetstream
   php artisan filament-jetstream:install [--teams] [--api]
   

   • Use --teams for team support, --api for API token management.

2. Publish Migrations:

   php artisan vendor:publish --tag=filament-jetstream-migrations
   php artisan migrate
   

3. Configure User Model: Update App\Models\User to include required traits:

   use Filament\Jetstream\InteractsWithProfile;
   use Laravel\Sanctum\HasApiTokens; // Only if using API
   use Filament\Jetstream\InteractsWithTeams; // Only if using teams
   

4. Register Plugin: In App\Providers\FilamentServiceProvider:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugin(JetstreamPlugin::make());
   }
   

First Use Case

• Quick Start: Use the built-in Filament admin panel for user management, profiles, and authentication.
• Customize: Extend the default features (e.g., disable 2FA, modify team roles) via the JetstreamPlugin::make() configuration.

Implementation Patterns

Core Workflows

1. Authentication & Registration:

   • Leverage Filament’s native login/registration forms (no need for separate Blade templates).
   • Customize validation rules or UI via Filament’s form components.

2. Profile Management:

   • Extend the InteractsWithProfile trait to add custom profile fields:

     public static function getFilamentProfileFields(): array
     {
         return [
             TextInput::make('custom_field')->required(),
         ];
     }
     

3. Teams (Optional):

   • Use InteractsWithTeams for multi-tenancy.
   • Customize team roles or permissions via Role model or gates/policies.

4. API Tokens (Optional):

   • Generate and manage tokens via Filament’s UI.
   • Restrict token permissions in the plugin config:

     ->apiTokens(permissions: fn() => ['create', 'read'])
     

5. Two-Factor Authentication (2FA):

   • Enable/disable via config:

     ->twoFactorAuthentication(condition: fn() => true)
     

   • Customize recovery codes or passkey support.

Integration Tips

• Filament Panels: Integrate with existing Filament panels by registering the plugin in the panel configuration.
• Feature Flags: Use Laravel’s Feature gates to conditionally enable/disable features (e.g., teams in staging).
• Localization: Override default labels via Filament’s translation system:

  'filament-jetstream::profile/fields.name.label' => 'Custom Name',
  

• Custom Routes: Extend routes by publishing the plugin’s routes and adding custom middleware:

  php artisan vendor:publish --tag=filament-jetstream-routes
  

Gotchas and Tips

Pitfalls

1. Migration Conflicts:

   • If using Laravel’s default users table, ensure no column conflicts (e.g., profile_photo_path).
   • Fix: Rename columns in the published migrations or merge them manually.

2. Trait Overrides:

   • Avoid overriding methods in InteractsWithProfile/InteractsWithTeams unless necessary. Use Filament’s hooks or custom fields instead.
   • Example: Extend profile fields without modifying traits:

     public function getFilamentProfileWidgets(): array
     {
         return [
             StatsOverviewWidget::make()->columns(2),
             // Custom widgets here
         ];
     }
     

3. API Token Scopes:

   • Sanctum’s default scopes may not align with Filament’s permissions. Define custom scopes in HasApiTokens:

     public function getSanctumTokenableAttributes(): array
     {
         return ['*'];
     }
     

4. Team Invitation Bugs:

   • Duplicate team creation during registration can occur if not handled carefully.
   • Fix: Use the acceptTeamInvitation callback in the plugin config to enforce logic:

     ->teams(acceptTeamInvitation: fn($invitationId) => JetstreamPlugin::make()->defaultAcceptTeamInvitation())
     

5. Filament Version Mismatches:

   • Ensure compatibility with your Filament version (check the package’s composer.json for constraints).
   • Tip: Use filament/filament:^4.0 for stability.

Debugging

• Logs: Enable Filament’s debug mode in .env:

  FILAMENT_DEBUG=true
  

• Database: Verify migrations ran correctly:

  php artisan migrate:fresh --seed
  

• Plugin Config: Validate conditions in JetstreamPlugin::make() (e.g., condition: fn() => auth()->check()).

Extension Points

1. Custom Fields:

   • Add fields to the profile or team forms via Filament’s getFilament[Resource/Page]Fields() methods.

2. Event Listeners:

   • Listen to Filament’s events (e.g., UserRegistered) to trigger custom logic:

     Event::listen(UserRegistered::class, function ($user) {
         // Send welcome email
     });
     

3. Views:

   • Override default views by publishing assets:

     php artisan vendor:publish --tag=filament-jetstream-views
     

   • Modify resources/views/vendor/filament-jetstream/....

4. Testing:

   • Use Filament’s testing helpers:

     $this->actingAs($user)
          ->get('/filament/admin/resources/users')
          ->assertSuccessful();
     

Pro Tips

• Disable Features Gracefully:

  ->profilePhoto(condition: fn() => false) // Hide profile photo upload
  ->deleteAccount(condition: fn() => false) // Disable account deletion
  

• Passkeys: Enable passkey support (Laravel 11+):

  ->twoFactorAuthentication(enablePasskey: fn() => true)
  

• Performance: Lazy-load team members or profile data for large datasets using Filament’s QueryBuilder.
• Security: Restrict sensitive actions (e.g., password updates) to specific roles:

  ->updatePassword(condition: fn() => auth()->user()->isAdmin())
  

```markdown
### Config Quirks
1. **Feature Conditions**:
   - Conditions (e.g., `condition: fn() => Feature::active('teams')`) are evaluated **per request**. Cache feature checks if performance is critical:
     ```php
     ->teams(condition: fn() => cache()->remember('teams_enabled', now()->addHours(1), fn() => Feature::active('teams')))
     ```

2. **Plugin Initialization**:
   - The plugin **must** be registered in `FilamentServiceProvider` **before** the panel is returned. Order matters:
     ```php
     public function panel(Panel $panel): Panel
     {
         return $panel
             ->id('admin')
             ->plugin(JetstreamPlugin::make()) // Register first
             ->navigationGroups([...]);
     }
     ```

3. **Team Model Binding**:
   - Ensure `Team` model uses `Filament\Models\Contracts\HasTenants` and implements `HasTenants`:
     ```php
     class Team extends Model implements HasTenants
     {
         use InteractsWithTenants;
     }
     ```

4. **API Token Permissions**:
   - Permissions defined in `apiTokens(permissions: [...])` are **not** Sanctum scopes. Use Sanctum’s `HasApiTokens` for scope-based authorization.

5. **Translation Fallbacks**:
   - Default translations are in `resources/lang/vendor/filament-jetstream`. Override them in your app’s `lang` directory:
     ```bash
     php artisan vendor:publish --tag=filament-jetstream-translations
     ```