Filament Avatar Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require devaslanphp/filament-avatar
   

   Publish config (optional but recommended for customization):

   php artisan vendor:publish --tag=filament-avatar-config
   

2. Configure Default Provider Update config/filament.php to set the default avatar provider:

   'default_avatar_provider' => \Devaslanphp\FilamentAvatar\Core\FilamentUserAvatarProvider::class,
   

3. First Use Case Use the avatar in a Filament resource or widget:

   use Devaslanphp\FilamentAvatar\Facades\FilamentAvatar;
   
   FilamentAvatar::get($user); // Returns URL for the user's avatar
   

   Or in Blade:

   <img src="{{ FilamentAvatar::get($user) }}" alt="Avatar">
   

Implementation Patterns

Core Workflows

1. Dynamic Avatar Generation Use the facade or service container to fetch avatars dynamically:

   // In a Filament Resource Table
   Table::make([
       Tables\Columns\ImageColumn::make('avatar')
           ->url(fn ($record) => FilamentAvatar::get($record)),
   ]);
   

2. Customizing Providers Extend the base provider for custom logic:

   use Devaslanphp\FilamentAvatar\Contracts\AvatarProvider;
   
   class CustomAvatarProvider implements AvatarProvider {
       public function getAvatar($user): string {
           // Custom logic (e.g., fallback to UI Avatar if Gravatar fails)
           return Gravatar::get($user) ?? UIAvatar::get($user);
       }
   }
   

   Register in config/filament-avatar.php:

   'providers' => [
       'custom' => \App\Providers\CustomAvatarProvider::class,
   ],
   

3. Fallback Chains Configure fallback providers in config/filament-avatar.php:

   'fallbacks' => [
       'gravatar' => 'ui_avatar',
       'ui_avatar' => 'default',
   ],
   

4. Caching Avatars Leverage Laravel’s cache for performance:

   FilamentAvatar::get($user, cache: true); // Caches for 24h by default
   

   Customize cache duration in config:

   'cache' => [
       'enabled' => true,
       'duration' => 86400, // 24h in seconds
   ],
   

5. Integration with Filament Panels Use in user profile resources or widgets:

   use Filament\Widgets\StatsOverviewWidget;
   
   class UserProfileWidget extends StatsOverviewWidget {
       protected function getStats() {
           return [
               StatsOverviewWidget\Stat::make('Avatar', FilamentAvatar::get(auth()->user()))
                   ->icon('heroicon-o-photo'),
           ];
       }
   }
   

Gotchas and Tips

Pitfalls

1. Gravatar Rate Limits

   • Gravatar may throttle requests if used excessively. Cache aggressively or use ui_avatar as a fallback.
   • Monitor logs for 429 Too Many Requests errors.

2. Config Overrides

   • Ensure default_avatar_provider is set after the package’s config is published, or changes may not apply.
   • Verify config/filament-avatar.php exists post-publish:

     php artisan config:clear
     

3. UI Avatar Customization

   • The ui_avatar provider uses ui-avatars.com. Customize appearance via config:

     'ui_avatar' => [
         'background' => '#f0f0f0',
         'color' => '#333',
         'size' => '128',
     ],
     

   • Tip: Use size in pixels (e.g., 64, 128) for consistency.

4. User Model Requirements

   • The package expects a name or email field on the user model for Gravatar/UI Avatar generation.
   • Fix: Add a getter or accessor if your model uses a different field:

     public function getAvatarIdentifierAttribute() {
         return $this->username; // Fallback to username if email/name missing
     }
     

5. Filament Resource Caching

   • If using cache: true in Filament resources, clear the cache when user avatars change:

     public static function getCachedModelsUsing(): array {
         return [User::class];
     }
     

Debugging

1. Log Provider Selection Enable debug logging in config/filament-avatar.php:

   'debug' => true,
   

   Check storage/logs/laravel.log for provider resolution flow.

2. Test Fallbacks Locally Mock Gravatar failures to test fallback logic:

   // In a test
   $this->partialMock(Gravatar::class, function ($mock) {
       $mock->shouldReceive('get')->andReturn(null);
   });
   

3. Avatar URL Validation Use Laravel’s Str::startsWith() to verify URLs:

   $avatar = FilamentAvatar::get($user);
   $this->assertTrue(
       Str::startsWith($avatar, ['https://www.gravatar.com', 'https://ui-avatars.com'])
   );
   

Extension Points

1. Add New Providers Implement Devaslanphp\FilamentAvatar\Contracts\AvatarProvider:

   class LocalStorageAvatarProvider implements AvatarProvider {
       public function getAvatar($user): string {
           return Storage::disk('public')->url("avatars/{$user->id}.jpg");
       }
   }
   

   Register in config/filament-avatar.php:

   'providers' => [
       'local' => \App\Providers\LocalStorageAvatarProvider::class,
   ],
   

2. Customize Avatar Generation Override the FilamentUserAvatarProvider class to modify behavior:

   class CustomFilamentUserAvatarProvider extends \Devaslanphp\FilamentAvatar\Core\FilamentUserAvatarProvider {
       protected function resolveProvider($user) {
           if ($user->isAdmin()) {
               return config('filament-avatar.providers.admin');
           }
           return parent::resolveProvider($user);
       }
   }
   

   Update the config to use your custom provider.

3. Webhook-Based Updates Trigger avatar regeneration on user updates via model observers:

   class UserObserver {
       public function saved(User $user) {
           cache()->forget("filament-avatar-{$user->id}");
       }
   }