Filament Svg Avatar Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require voltra/filament-svg-avatar
   

2. Publish the config (optional, for customization):

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

3. Register as a plugin in your PanelProvider:

   use Voltra\FilamentSvgAvatar\FilamentSvgAvatarPlugin;
   
   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               FilamentSvgAvatarPlugin::make()
                   ->backgroundColor('#3b5998')
                   ->textColor('#e9ebee'),
           ]);
   }
   

First Use Case

Replace default Gravatar/URL-based avatars with inline SVG avatars (no external HTTP requests). Ideal for:

• Admin panels where user avatars are displayed frequently.
• Offline-first apps to avoid dependency on external services.

Implementation Patterns

1. Plugin Integration (Recommended)

• Pros: Zero-config, automatic SVG rendering, customizable via plugin methods.
• Workflow:

  FilamentSvgAvatarPlugin::make()
      ->backgroundColor('#ff0000') // Override globally
      ->textColor('#ffffff')
      ->svgSize(600); // Optional: Adjust SVG dimensions
  

• Use when: You want minimal setup and consistent styling across all avatars.

2. Provider Override (Advanced)

• Use case: Need full control (e.g., dynamic SVG generation per user).
• Steps:
  1. Set the provider in PanelProvider:

     ->defaultAvatarProvider(\Voltra\FilamentSvgAvatar\Filament\AvatarProviders\RawSvgAvatarProvider::class)
     

  2. Publish the override view:

     php artisan vendor:publish --tag=filament-svg-avatar-core-overrides
     

• Pros: Supports custom logic (e.g., per-user SVG templates).

3. Dynamic Configuration

• Per-resource customization:

  use Voltra\FilamentSvgAvatar\Filament\AvatarProviders\SvgAvatarsProviders;
  
  SvgAvatarsProviders::make()
      ->backgroundColor('#00ff00') // Override for specific resources
      ->textColor('#000000');
  

• Use when: Different resources need distinct avatar styles.

4. Service Contract Extension

• Extend functionality by implementing SvgAvatarServiceContract:

  class CustomSvgAvatarService implements SvgAvatarServiceContract {
      public function generateSvg(string $initials, array $config): string {
          // Custom SVG logic (e.g., add icons, shapes)
          return '<svg>...</svg>';
      }
  }
  

• Bind in a service provider:

  $this->app->scoped(SvgAvatarServiceContract::class, CustomSvgAvatarService::class);
  

• Use when: You need to modify SVG generation (e.g., add team logos).

Gotchas and Tips

Pitfalls

1. Font Availability:

   • SVGs rely on system fonts. If the font isn’t available, fall back to a default (e.g., Arial).
   • Fix: Use config(['filament-svg-avatar.fontFamily' => 'sans-serif']) or embed fonts via CSS.

2. Plugin vs. Provider Conflicts:

   • If using both FilamentSvgAvatarPlugin and a custom provider, register the provider after the plugin:

     ->plugins([FilamentSvgAvatarPlugin::make()])
     ->defaultAvatarProvider(CustomProvider::class);
     

3. Caching Issues:

   • SVG avatars are generated on-demand. For large-scale apps, cache the output:

     Cache::remember("svg_avatar_{$userId}", now()->addHours(1), fn() => $svg);
     

4. Migration Quirks:

   • Filament v4/v5 migrations may require updating the override view:

     php artisan vendor:publish --tag=filament-svg-avatar-core-overrides --force
     

Debugging Tips

• Inspect SVG Output: Use browser dev tools to verify SVG content (check for src/alt attribute leaks).
• Log Config: Add this to debug config values:

  \Log::info('SVG Avatar Config:', config('filament-svg-avatar'));
  

• Test Locally: Use php artisan filament:serve to test changes without deploying.

Extension Points

1. Custom SVG Templates:

   • Override the resources/views/vendor/filament-svg-avatar/avatar.blade.php template to modify SVG structure.
   • Example: Add a border or shadow:

     <svg ... style="filter: drop-shadow(0 0 4px rgba(0,0,0,0.3));">
     

2. Dynamic Colors:

   • Use a service to fetch colors from a database:

     $color = User::find($userId)->theme_color ?? '#3b5998';
     FilamentSvgAvatarPlugin::make()->backgroundColor($color);
     

3. Fallback Logic:

   • Combine with filament-support to handle missing avatars:

     use Filament\Support\Facades\FilamentSupport;
     
     FilamentSupport::avatar($user)->defaultImage('placeholder.svg');
     

Performance

• Optimize SVG Size: Reduce svgSize in config (default: 500) to 300 for faster rendering.
• Lazy Load: Defer SVG generation until the avatar is visible (e.g., using Intersection Observer).

Accessibility

• Ensure SVGs include aria-label for screen readers:

  <svg aria-label="{{ $user->name }} avatar" ...>