Filament Facehash Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require saade/filament-facehash
   

   Run php artisan vendor:publish --provider="Saade\FilamentFacehash\FacehashServiceProvider" if customization is needed.

2. First Use Case: Replace default Filament avatars in your admin panel by adding the provider and plugin to your Panel configuration:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->defaultAvatarProvider(FacehashProvider::class)
           ->plugins([
               FacehashPlugin::make(),
           ]);
   }
   

   This immediately replaces all user avatars in Filament with deterministic, SVG-based facehash avatars.

3. Where to Look First:

   • Playground: Test configurations interactively at facehash.saade.dev.
   • Facehash Docs: Core functionality (e.g., variants, color palettes) is documented here.
   • Filament Plugin API: Check FacehashPlugin::make() for available methods.

Implementation Patterns

Core Workflows

1. Basic Integration:

   • Register the provider and plugin in panel() as shown above. No additional setup is required for default behavior.

2. Dynamic Configuration: Use the fluent API to customize avatars per panel or tenant:

   FacehashPlugin::make()
       ->size(fn (User $user) => $user->isAdmin() ? 50 : 40) // Dynamic sizing
       ->variant(fn (User $user) => $user->prefersDarkMode() ? Variant::Solid : Variant::Gradient);
   

3. Model-Specific Avatars: Extend the trait for custom logic (e.g., override hash generation):

   use Saade\FilamentFacehash\HasFacehashAvatar;
   
   class User extends Authenticatable
   {
       use HasFacehashAvatar;
   
       public function getFacehashAttributes(): array
       {
           return [
               'name' => $this->full_name, // Custom attribute
               'color' => $this->theme_color, // Dynamic color
           ];
       }
   }
   

4. Conditional Avatars: Disable facehash for specific users/models:

   public function getFacehashAvatarUrl(): ?string
   {
       return $this->shouldUseFacehash ? parent::getFacehashAvatarUrl() : null;
   }
   

5. Caching: Leverage Filament’s built-in caching for avatars by implementing ShouldCacheAvatar:

   use Saade\FilamentFacehash\Concerns\ShouldCacheAvatar;
   
   class User extends Authenticatable
   {
       use ShouldCacheAvatar;
   }
   

Integration Tips

• Theme Consistency: Use ->colors() to match your app’s brand palette.
• Performance: SVG avatars are lightweight; no image processing required.
• Fallbacks: Combine with Filament\Panel::defaultAvatarProvider() for hybrid setups:

  ->defaultAvatarProvider(function ($record) {
      return $record->avatar_url ?: FacehashProvider::make($record);
  });
  

Gotchas and Tips

Pitfalls

1. Deterministic Hashes:

   • Same input (e.g., name="John") always produces the same avatar. Use unique attributes (e.g., email) if collisions are a concern:

     ->hashAttributes(['name', 'email'])
     

2. Initials Override:

   • Setting ->initial(false) hides letters entirely. Ensure name or other attributes are still provided for consistency.

3. SVG Rendering:

   • Rare edge cases may require forcing SVG output in Filament’s Avatar component:

     Avatar::make('user')
         ->avatar($user->facehash_avatar_url)
         ->width(40)
         ->height(40)
         ->circle();
     

4. Plugin Registration:

   • Forgetting to add FacehashPlugin::make() to panel()->plugins() will silently ignore the provider.

Debugging

• Avatar Not Updating?: Clear Filament’s cache (php artisan filament:cache-reset) or check for cached responses.
• Blank Avatars: Verify name or other hash attributes are non-empty. Log the generated hash:

  dd(Facehash::generate(['name' => $user->name]));
  

Configuration Quirks

1. Size Limits:
   • Extremely large sizes (e.g., ->size(200)) may impact performance. Test in the playground first.
2. Color Palette:
   • Ensure colors are valid CSS hex values. Use ->colors() with an array of strings:

     ->colors(['#hex1', '#hex2']) // Not ['rgb(0,0,0)', ...]
     

3. Variant Enums:
   • Only Variant::Gradient and Variant::Solid are supported. Custom variants require extending the facehash package.

Extension Points

1. Custom Hash Generation: Override getFacehashAttributes() in your model to modify input data:

   public function getFacehashAttributes(): array
   {
       return [
           'name' => strtolower($this->name),
           'seed' => $this->created_at->timestamp, // Add entropy
       ];
   }
   

2. Plugin Events: Listen for avatar generation via Filament’s event system:

   FacehashPlugin::make()
       ->listeningForAvatarEvents();
   // Then handle in EventServiceProvider:
   protected $listen = [
       'saade.facehash.generating' => [YourListener::class],
   ];
   

3. Multi-Panel Support: Register different configurations per panel:

   // admin-panel.php
   FacehashPlugin::make()->variant(Variant::Solid);
   
   // customer-panel.php
   FacehashPlugin::make()->variant(Variant::Gradient);