Fin Avatar Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require finity-labs/fin-avatar
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="FinityLabs\FinAvatar\FinAvatarServiceProvider"
   

2. Register the Avatar Provider In your AppServiceProvider or Filament panel configuration:

   use FinityLabs\FinAvatar\Facades\FinAvatar;
   
   Filament::registerAvatarProvider(FinAvatar::class);
   

3. First Use Case Replace default Filament avatars in a UserResource:

   use FinityLabs\FinAvatar\Avatar;
   
   public static function table(Table $table): Table
   {
       return $table
           ->columns([
               Avatar::make('avatar')
                   ->size(40)
                   ->color('primary')
                   ->fallback('👤'),
           ]);
   }
   

Key Files to Review

• config/fin-avatar.php (customization options)
• src/Avatar.php (core class for customization)
• routes/web.php (generated /fin-avatar endpoint)

Implementation Patterns

Core Workflow

1. Generate Avatars Locally Use the dedicated route (/fin-avatar) to generate SVGs on-demand:

   // In a controller or service
   $avatarUrl = FinAvatar::generate('john.doe@example.com', [
       'size' => 64,
       'color' => '#3b82f6',
       'shape' => 'circle',
   ]);
   

2. Filament Integration

   • Resources/Tables: Replace Avatar::make() with FinAvatar::make().
   • Widgets: Use in StatsOverviewWidget or ChartWidget for user avatars.
   • Forms: Attach to TextInput or Select fields for profile pictures.

3. Caching Strategy Leverage browser caching via Cache-Control headers (configured in config/fin-avatar.php):

   'cache' => [
       'enabled' => true,
       'ttl' => 31536000, // 1 year
   ],
   

4. Dynamic Customization Pass options dynamically in templates:

   <x-fin-avatar
       :email="$user->email"
       :size="32"
       color="success"
       shape="rounded"
   />
   

Advanced Patterns

• Fallback Logic: Combine with Filament\Forms\Components\FileUpload for hybrid avatars:

  Avatar::make('avatar')
      ->fallback(fn ($record) => $record->profile_photo_url)
  

• Theming: Override default colors via config or CSS variables:

  'colors' => [
      'primary' => '#10b981',
      'secondary' => '#3b82f6',
  ],
  

• Batch Generation: Pre-generate avatars for users during imports:

  $users->each->generateAvatar(); // Custom method
  

Gotchas and Tips

Common Pitfalls

1. Route Conflicts

   • Ensure /fin-avatar doesn’t clash with existing routes. Override the route in config/fin-avatar.php:

     'route' => 'filament.fin-avatar',
     

   • Verify the route is registered in routes/web.php after installation.

2. Caching Headers

   • If avatars don’t update, clear browser cache or adjust ttl in config.
   • Disable caching during development:

     'cache' => ['enabled' => env('APP_ENV') !== 'local'],
     

3. Email Normalization

   • The package normalizes emails (lowercase, trim). Handle edge cases explicitly:

     FinAvatar::generate(strtolower(trim($email)));
     

4. SVG Injection Risks

   • Sanitize dynamic inputs (e.g., size or color) if accepting user-provided values:

     $size = (int) min(256, abs((int) $request->size));
     

Debugging Tips

• Check Generated SVG: Inspect the /fin-avatar route output for malformed SVGs.
• Log Missing Dependencies: Enable debug mode in config/fin-avatar.php:

  'debug' => [
      'log_missing_fonts' => true,
  ],
  

• Test Edge Cases:
  • Empty/NULL emails → Use ->fallback().
  • Non-ASCII emails → Ensure UTF-8 support in your Laravel config.

Extension Points

1. Custom Shapes Extend the FinAvatar class to add shapes (e.g., polygons):

   namespace App\Extensions;
   
   use FinityLabs\FinAvatar\Avatar;
   
   class PolygonAvatar extends Avatar
   {
       protected function getShapeSvg(): string
       {
           return '<polygon points="..." />';
       }
   }
   

2. Font Integration Override default fonts by publishing assets:

   php artisan vendor:publish --tag=fin-avatar-assets
   

   Then update resources/views/vendor/fin-avatar/fonts.blade.php.

3. Filament Policy Integration Restrict avatar generation to authenticated users:

   FinAvatar::middleware(['auth:sanctum']);
   

4. Analytics Track avatar generation (e.g., for GDPR compliance logs):

   event(new AvatarGenerated($email, $options));
   

   Register in FinAvatarServiceProvider.

Performance Notes

• Lazy Loading: Use loading="lazy" in Blade for offscreen avatars.
• CDN Caching: Deploy the /fin-avatar route behind a CDN for global caching.
• Asset Optimization: Minify SVG output by extending FinAvatar::render().

```markdown
### Laravel-Specific Quirks
1. **Queue Jobs for Batch Processing**
   Dispatch avatar generation as a job to avoid timeouts:
   ```php
   GenerateAvatarJob::dispatch($user->email, $options);

2. Artisan Commands Create a command to regenerate all avatars:

   php artisan fin:avatar:regenerate --users="1,2,3"
   

3. Testing Mock the avatar service in tests:

   $this->partialMock(FinAvatar::class, function ($mock) {
       $mock->shouldReceive('generate')
            ->andReturn('/path/to/mock.svg');
   });
   

4. Filament 5.x Migration Update Avatar usage from:

   Filament\Tables\Columns\AvatarColumn
   

   to:

   FinityLabs\FinAvatar\Columns\AvatarColumn
   

   in Filament 5.x projects.