Filament Dicebear Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require leek/filament-dicebear
   

   Publish the config (optional but recommended for customization):

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

2. Register in Panel Provider: Add the plugin and provider to your AppPanelProvider:

   use Leek\FilamentDiceBear\DiceBearPlugin;
   use Leek\FilamentDiceBear\DiceBearProvider;
   
   public function panel(Panel $panel): Panel {
       return $panel
           ->plugins([DiceBearPlugin::make()])
           ->defaultAvatarProvider(DiceBearProvider::class);
   }
   

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

   use Leek\FilamentDiceBear\Enums\DiceBearStyle;
   
   public static function table(Table $table): Table {
       return $table
           ->columns([
               AvatarColumn::make('avatar')
                   ->avatarProvider(DiceBearProvider::class)
                   ->avatarStyle(DiceBearStyle::Adventurer),
           ]);
   }
   

Implementation Patterns

Core Workflows

1. Dynamic Avatar Generation: Override the default avatar for a model in the getAvatar() method:

   public function getAvatar(): string {
       return DiceBearProvider::make()
           ->style(DiceBearStyle::Bottts)
           ->seed($this->name)
           ->generate();
   }
   

2. Per-Model Customization: Use the avatar() method in resources/tables to customize styles per model:

   AvatarColumn::make('avatar')
       ->avatarProvider(DiceBearProvider::class)
       ->avatarStyle(fn (User $record) => $record->isAdmin()
           ? DiceBearStyle::BigEars
           : DiceBearStyle::Initials),
   

3. Self-Hosted Integration: Configure the package to use a local DiceBear instance:

   // config/filament-dicebear.php
   'self_hosted' => [
       'enabled' => true,
       'url' => env('DICEBEAR_SELF_HOSTED_URL', 'http://dicebear.local'),
   ],
   

4. Caching Strategies: Leverage Filament’s built-in caching by extending the provider:

   class CustomDiceBearProvider extends DiceBearProvider {
       public function generate(): string {
           return cache()->remember(
               "dicebear_{$this->seed}_{$this->style->value}",
               now()->addDays(7),
               fn () => parent::generate()
           );
       }
   }
   

Integration Tips

• Filament Forms: Use DiceBearProvider in Form components for dynamic avatars:

  AvatarField::make('avatar')
      ->avatarProvider(DiceBearProvider::class)
      ->avatarStyle(DiceBearStyle::PixelArt),
  

• API Responses: Return DiceBear avatars in API responses:

  return UserResource::make($user)
      ->additional(['avatar': DiceBearProvider::make()
          ->seed($user->email)
          ->style(DiceBearStyle::Lorelei)
          ->generate()]);
  

Gotchas and Tips

Pitfalls

1. Caching Conflicts:

   • If using self-hosted DiceBear, ensure your cache key includes the seed and style to avoid stale avatars.
   • Clear cache when updating styles or seeds:

     php artisan cache:clear
     

2. Style Availability:

   • Not all 31 styles are visually distinct. Test styles like Initials or BigEars for readability.
   • Check the DiceBear documentation for style compatibility.

3. Self-Hosted Dependencies:

   • If using a self-hosted instance, ensure the endpoint is always available. Fallback to the default provider in case of failures:

     public function generate(): string {
         try {
             return parent::generate();
         } catch (\Exception $e) {
             return 'https://default-avatar-url.com';
         }
     }
     

4. Seed Collisions:

   • Use unique seeds (e.g., email + timestamp) to avoid duplicate avatars:

     ->seed($user->email . '-' . now()->timestamp)
     

Debugging

• Log Generation: Enable debug logs in config/filament-dicebear.php to inspect failed requests:

  'debug' => env('DICEBEAR_DEBUG', false),
  

• Validate URLs: Use browser dev tools to verify the generated DiceBear URLs are correct. Example:

  https://api.dicebear.com/6.x/adventurer/svg?seed=JohnDoe
  

Extension Points

1. Custom Providers: Extend DiceBearProvider to add logic (e.g., role-based styles):

   class RoleBasedDiceBearProvider extends DiceBearProvider {
       public function generate(): string {
           $style = $this->record->isAdmin()
               ? DiceBearStyle::BigEars
               : $this->style;
           return parent::withStyle($style)->generate();
       }
   }
   

2. Dynamic Style Resolution: Use closures for runtime style selection:

   AvatarColumn::make('avatar')
       ->avatarStyle(fn (User $record) => match ($record->tier) {
           'premium' => DiceBearStyle::Lorelei,
           default => DiceBearStyle::Initials,
       }),
   

3. Fallback Logic: Implement fallback styles or URLs in the provider:

   public function generate(): string {
       try {
           return parent::generate();
       } catch (\Exception) {
           return 'https://via.placeholder.com/80?text=' . urlencode($this->seed);
       }
   }
   

4. Configuration Overrides: Override config values per environment:

   // config/filament-dicebear.php
   'styles' => [
       'default' => env('DICEBEAR_DEFAULT_STYLE', DiceBearStyle::Adventurer),
   ],