Filament Identity Column Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require filafly/filament-identity-column
   php artisan filament:assets
   

   Verify package auto-discovery is enabled in composer.json under "extra": { "laravel": { "providers": [...] } }.

2. First Use Case: Add to a Filament Table column:

   use Filafly\IdentityColumn\Tables\Columns\IdentityColumn;
   
   IdentityColumn::make('user')
       ->avatar('avatar_url')
       ->primary('name')
       ->secondary('email')
       ->size('md');
   

   For Infolists:

   use Filafly\IdentityColumn\Infolists\Components\IdentityEntry;
   
   IdentityEntry::make('user')
       ->avatar('avatar_url')
       ->primary('name')
       ->secondary('email')
       ->size('md');
   

3. Where to Look First:

   • Documentation: Focus on the Basic Usage section in the README.
   • Source Code: Explore src/Tables/Columns/IdentityColumn.php and src/Infolists/Components/IdentityEntry.php for method signatures and default behaviors.
   • Examples: Check the Filafly GitHub for usage examples in real projects.

Implementation Patterns

Common Workflows

1. Dynamic Avatar Sources: Use closures for dynamic avatar paths (e.g., Gravatar, storage paths):

   ->avatar(fn ($record) => $record->profile_photo_url ?? 'default-avatar.png')
   

2. Conditional URLs: Dynamically set primary/secondary URLs based on record state:

   ->primaryUrl(fn ($record) => $record->is_active ? route('users.show', $record) : null)
   

3. Reusable Components: Create a trait or base class for consistent identity columns across tables:

   trait UsesIdentityColumn {
       protected function identityColumn(string $field): IdentityColumn {
           return IdentityColumn::make($field)
               ->avatar('avatar_url')
               ->size('sm')
               ->primaryUrl(fn ($record) => route('users.edit', $record));
       }
   }
   

4. Infolist Integration: Use IdentityEntry in Infolists for consistent UI across pages:

   Infolist::make()
       ->schema([
           IdentityEntry::make('user')
               ->avatar('avatar_url')
               ->primary('full_name')
               ->secondary('role'),
       ]);
   

5. Custom Avatar Shapes: Override avatar shape dynamically:

   ->avatarShape(fn ($record) => $record->is_admin ? 'circular' : 'rounded')
   

Integration Tips

• Filament Tables: Combine with other Filament features like sorting, searching, and actions:

  IdentityColumn::make('user')
      ->sortable()
      ->searchable()
      ->primaryUrl(fn ($record) => route('users.show', $record))
      ->action(EditAction::make());
  

• Livewire Integration: Ensure the column works seamlessly with Livewire by leveraging Filament’s built-in Livewire support. No additional setup is required.

• Testing: Test avatar rendering with mocked records:

  $record = new User(['avatar_url' => 'test.jpg', 'name' => 'Test User']);
  $column = IdentityColumn::make('user')->avatar('avatar_url')->primary('name');
  $this->assertStringContainsString('Test User', $column->getState());
  

Gotchas and Tips

Pitfalls

1. Avatar Path Resolution:

   • Issue: Relative paths (e.g., storage/avatars/user.jpg) may not resolve correctly in production.
   • Fix: Use absolute URLs or root-relative paths (e.g., /storage/avatars/user.jpg).
   • Debug: Check browser dev tools (Network tab) to verify avatar paths are loading.

2. Closure Evaluation:

   • Issue: Closures in avatar(), primary(), or primaryUrl() are evaluated per record, not once. This can cause performance overhead if closures are complex.
   • Fix: Cache results if closures are expensive:

     ->avatar(fn ($record) => Cache::remember("avatar_{$record->id}", now()->addHours(1), fn () => $record->generateAvatarUrl()))
     

3. URL Generation:

   • Issue: primaryUrl() or secondaryUrl() may fail if the route/model binding is incorrect.
   • Debug: Use dd() or Log::debug() to inspect the generated URL:

     ->primaryUrl(fn ($record) => {
         Log::debug('Generating URL for:', $record);
         return route('users.show', $record);
     })
     

4. Size Classes:

   • Issue: Custom size() values (e.g., 'custom') may not render as expected if CSS is not overridden.
   • Fix: Extend the package’s Tailwind classes or add custom CSS:

     /* resources/css/filament/identity-column.css */
     .custom-identity-column { /* Your custom styles */ }
     

5. Infolist vs. Table Behavior:

   • Issue: IdentityEntry in Infolists may behave slightly differently than IdentityColumn in Tables (e.g., hover effects, click handling).
   • Fix: Test both contexts early in development.

Debugging Tips

1. Inspect Rendered HTML: Use browser dev tools to verify the column’s structure and identify missing classes/attributes.

2. Log Column State: Override getState() in custom columns to log values:

   public function getState(): array {
       $state = parent::getState();
       Log::debug('IdentityColumn state:', $state);
       return $state;
   }
   

3. Disable Caching: Temporarily disable Filament’s asset caching to rule out stale CSS/JS:

   php artisan filament:assets --purge
   

Extension Points

1. Custom Avatar Component: Override the default avatar rendering by publishing and modifying the view:

   php artisan vendor:publish --tag="filafly-identity-column:views"
   

   Edit resources/views/vendor/filafly/identity-column/avatar.blade.php.

2. Add Tooltips: Extend the column to include tooltips for secondary text:

   IdentityColumn::make('user')
       ->avatar('avatar_url')
       ->primary('name')
       ->secondary('email')
       ->secondaryTooltip(fn ($record) => "Email: {$record->email}")
       ->size('md');
   

   (Requires custom CSS/JS for tooltip implementation.)

3. Accessibility: Enhance accessibility by adding ARIA labels or keyboard navigation:

   ->avatarAttributes(['aria-label' => 'User avatar'])
   ->primaryAttributes(['aria-label' => 'User name'])
   

4. Dark Mode Support: Ensure avatar/column styles work in dark mode by using Tailwind’s dark: variants or custom CSS:

   .dark .identity-column-avatar {
       filter: brightness(0) invert(1);
   }