Fluxui Avatar Laravel Package

Getting Started

Minimal Steps

1. Install the package in a Laravel 11 + Livewire 4 + Flux UI project:

   composer require agenticmorf/fluxui-avatar
   

2. Publish the config to customize storage and validation:

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

3. Choose a storage driver (disk or Spatie Media Library) by updating config/fluxui-avatar.php and running migrations.
4. Drop the Livewire component into your profile page:

   <livewire:avatar-manager />
   

5. Verify the avatar appears in the Flux UI header automatically—no manual template changes needed.

First Use Case

Profile Page Integration Add <livewire:avatar-manager /> to your profile view (e.g., resources/views/profile.blade.php). The component handles:

• File upload with Flux UI styling
• Validation (file type/size)
• Preview during upload
• Removal of existing avatars

Implementation Patterns

Core Workflows

1. Avatar Display Use <flux:avatar /> anywhere in your app. The package automatically resolves the authenticated user’s avatar URL or falls back to initials.

   <flux:avatar size="md" circle />
   

2. Upload Management The <livewire:avatar-manager /> component handles:

   • File selection with Flux UI’s <flux:file-upload>
   • Real-time preview via Livewire reactivity
   • Validation (types/size) with user feedback
   • Storage via the configured adapter (disk/Spatie)

3. Storage Integration

   • Disk Driver: Stores paths in avatar_path column (default: public/avatars/).
   • Spatie Driver: Uses spatie/laravel-medialibrary with avatars collection.

Integration Tips

• Customize Validation: Extend the config in fluxui-avatar.php:

  'accepted_types' => ['jpg', 'png', 'gif'],
  'max_file_size'  => 5120, // 5MB
  

• Override Views: Publish and modify views:

  php artisan vendor:publish --tag=fluxui-avatar-views
  

• Manual Avatar Resolution: Use the AvatarStorage facade to fetch URLs:

  use AgenticMorf\FluxuiAvatar\Facades\AvatarStorage;
  
  $url = AvatarStorage::getUrl($user);
  

Livewire Component Patterns

• Dependency Injection: The AvatarManager component injects AvatarStorageInterface via boot() (no manual resolution).
• Reactivity: Use wire:model.live for real-time previews:

  <flux:file-upload wire:model.live="photo" />
  

• Error Handling: Validate in rules() method:

  public function rules(): array
  {
      return [
          'photo' => 'nullable|image|mimes:jpg,png|max:2048',
      ];
  }
  

Gotchas and Tips

Pitfalls

1. Namespace Shadowing Recursion

   • Issue: Shadowing <flux:avatar> in the shadowed view causes infinite loops.
   • Fix: Delegate to Flux’s original template:

     @include('flux::avatar.index', ['src' => $avatarUrl])
     

2. Spatie Media Library Setup

   • Issue: Forgetting singleFile() in registerMediaCollections() causes duplicate avatars.
   • Fix: Ensure your User model includes:

     $this->addMediaCollection('avatars')->singleFile();
     

3. Disk Driver Paths

   • Issue: Avatars not appearing if avatar_path column is misconfigured.
   • Fix: Verify the directory in config matches your storage path (e.g., public/avatars).

4. Livewire 4 Migration

   • Issue: Using #[LivewireProperty] or WithFileUploads trait (v3 syntax).
   • Fix: Remove annotations; use public properties and use Livewire\Features\SupportFileUploads.

Debugging Tips

• Check Storage Adapter: Temporarily log the resolved URL in AvatarStorageInterface:

  public function getUrl(User $user): ?string
  {
      $url = $this->resolveUrl($user);
      \Log::debug("Avatar URL for {$user->id}: {$url}");
      return $url;
  }
  

• Validate Config: Ensure FLUXUI_AVATAR_DRIVER in .env matches your config.
• Clear Cached Views: If avatars don’t update, run:

  php artisan view:clear
  

Extension Points

1. Custom Storage Adapters Implement AgenticMorf\FluxuiAvatar\Contracts\AvatarStorageInterface for new backends (e.g., S3):

   class S3Adapter implements AvatarStorageInterface
   {
       public function store(File $file, User $user): void
       {
           // Custom S3 logic
       }
       // ...
   }
   

   Bind it in the service provider:

   $this->app->when(AvatarStorageInterface::class)
       ->needs(S3Adapter::class)
       ->give(fn() => new S3Adapter());
   

2. Override Avatar Logic Extend the AvatarManager component to add features (e.g., cropper):

   public function mount()
   {
       $this->photo = null;
       $this->cropperEnabled = config('fluxui-avatar.cropper', false);
   }
   

3. Custom Initials Logic Override the generateInitials() method in your shadowed avatar.blade.php:

   @php
       $initials = Str::of($name)->take(2)->upper()->replace([' ', '-'], '');
   @endphp
   

Configuration Quirks

• Default Avatar: Set a custom fallback URL in config:

  'default_avatar' => 'https://example.com/default-avatar.png',
  

• Disk Permissions: Ensure the avatars directory is writable:

  chmod -R 755 storage/app/public/avatars
  

• Spatie Migrations: Run migrations after installing spatie/laravel-medialibrary:

  php artisan migrate