Filament People Laravel Package

Getting Started

Minimal Setup

1. Install via Composer

   composer require rectitude-open/filament-people
   

2. Publish Configuration & Migrations

   php artisan vendor:publish --provider="RectitudeOpen\FilamentPeople\FilamentPeopleServiceProvider"
   

3. Run Migrations

   php artisan migrate
   

4. Register the Plugin Add to app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \RectitudeOpen\FilamentPeople\FilamentPeoplePlugin::make(),
           ]);
   }
   

First Use Case

Create a member profile by navigating to Filament Admin → People → Members and clicking "Create Member". Fill in basic fields (name, email, role) and save. The plugin auto-generates a profile page at /admin/people/{member} with avatar, bio, and contact details.

Implementation Patterns

Core Workflows

1. Member Management

   • CRUD Operations: Use Filament’s built-in table actions (edit, delete, view) for members.
   • Bulk Actions: Leverage Filament’s bulk select to assign roles or update statuses.
   • Custom Fields: Extend the Member model via $fillable or add custom attributes in the plugin’s config:

     'custom_fields' => [
         'department' => 'string',
         'hire_date' => 'date',
     ],
     

2. Profile Customization

   • Avatar Handling: Use filament/spatie-laravel-medialibrary (dependency) to upload avatars. Override the avatar field in config/filament-people.php:

     'avatar' => [
         'disk' => 'public',
         'model' => \Spatie\MediaLibrary\HasMedia::class,
     ],
     

   • Bio Editor: Replace the default textarea with a rich editor (e.g., filament/tinymce) by modifying the Biography widget in the plugin’s resources.

3. Role & Permission Integration

   • Sync with Laravel’s built-in roles or use spatie/laravel-permission:

     // In FilamentPeopleServiceProvider::boot()
     $this->app->make(\RectitudeOpen\FilamentPeople\Contracts\RoleResolver::class)
         ->setResolver(function ($member) {
             return $member->roles->first()?->name ?? 'guest';
         });
     

4. API & External Integrations

   • Expose member data via API by publishing the plugin’s routes:

     php artisan vendor:publish --tag="filament-people-routes"
     

   • Sync with HR systems (e.g., BambooHR) by extending the Member model’s syncWithExternalSystem() method.

Gotchas and Tips

Pitfalls

1. Dependency Conflicts

   • Ensure filament/spatie-laravel-medialibrary and spatie/laravel-permission (if used) are installed and configured before installing filament-people. Run composer require for each dependency explicitly.
   • Fix: Check composer.json for version constraints and resolve conflicts with composer why-not <package>.

2. Migration Issues

   • The members table migration assumes a default schema. Customize via:

     php artisan vendor:publish --tag="filament-people-migrations"
     

     Then modify database/migrations/[timestamp]_create_members_table.php.
   • Tip: Use php artisan migrate:fresh if schema changes break the app.

3. Avatar Upload Limits

   • Default storage (public disk) may hit size limits. Configure in config/filesystems.php:

     'disks' => [
         'public' => [
             'driver' => 's3',
             'url' => env('AWS_URL'),
             'visibility' => 'public',
         ],
     ],
     

   • Workaround: Use filament/media-library for advanced upload handling.

4. Role Resolution Edge Cases

   • If RoleResolver returns null, the plugin defaults to 'guest'. Override in app/Providers/FilamentPeopleServiceProvider:

     $this->app->singleton(\RectitudeOpen\FilamentPeople\Contracts\RoleResolver::class, function () {
         return new class implements RoleResolver {
             public function resolve($member): string {
                 return $member->hasRole('admin') ? 'admin' : 'member';
             }
         };
     });
     
     

Debugging Tips

• Log Missing Dependencies: Add to AppServiceProvider:

  public function boot()
  {
      if (!class_exists(\Spatie\MediaLibrary\HasMedia::class)) {
          Log::error('filament-people requires spatie/laravel-medialibrary');
      }
  }
  

• Inspect Plugin Views: Override templates by publishing assets:

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

  Then modify resources/views/vendor/filament-people/....

Extension Points

1. Custom Member Attributes Add to config/filament-people.php:

   'member_attributes' => [
       'slack_username' => 'string',
       'timezone' => 'string',
   ],
   

   Then extend the Member model:

   public function getSlackUsernameAttribute()
   {
       return $this->attributes['slack_username'] ?? null;
   }
   

2. Hooks for Pre/Post Actions Use Filament’s event system to intercept member creation/updates:

   // In EventServiceProvider
   protected $listen = [
      \RectitudeOpen\FilamentPeople\Events\MemberCreated::class => [
          \App\Listeners\SendWelcomeEmail::class,
      ],
   

];

3. **Localization**
Publish translations:
```bash
php artisan vendor:publish --tag="filament-people-translations"

Then extend resources/lang/vendor/filament-people/....

4. Testing Use the plugin’s test utilities in tests/TestCase.php:

   use RectitudeOpen\FilamentPeople\Testing\TestsFilamentPeople;
   
   class MemberTest extends TestCase {
       use TestsFilamentPeople;
   
       public function test_member_creation()
       {
           $member = $this->createMember(['name' => 'John Doe']);
           $this->assertDatabaseHas('members', ['name' => 'John Doe']);
       }
   }