Filament Badgeable Column Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require awcodes/filament-badgeable-column
   

   Ensure your Filament version matches the compatibility table (e.g., 4.x for Filament 5.x).

2. Publish the config (optional):

   php artisan vendor:publish --provider="Awcodes\FilamentBadgeableColumn\FilamentBadgeableColumnServiceProvider" --tag="config"
   

   Customize badge styles, colors, or default behavior in config/filament-badgeable-column.php.

3. First use case: Add a BadgeableColumn to a Filament table:

   use Awcodes\FilamentBadgeableColumn\Columns\BadgeableColumn;
   
   BadgeableColumn::make('status')
       ->badge('active')
       ->badge('pending', color: 'warning')
       ->badge('archived', color: 'gray'),
   

   Place this in your table’s columns() method.

Where to Look First

• README: Focus on the Usage section for basic syntax.
• Config: Check config/filament-badgeable-column.php for default badge styles/colors.
• Source: Review src/Columns/BadgeableColumn.php for advanced customization hooks.

Implementation Patterns

Core Workflows

1. Basic Badge Display:

   BadgeableColumn::make('user_type')
       ->badge('admin')
       ->badge('editor', color: 'info')
       ->badge('guest', color: 'gray'),
   

   • Dynamic badges: Use closures for runtime logic:

     ->badge(fn ($record) => $record->is_premium ? 'premium' : 'basic')
     

2. Conditional Badges:

   BadgeableColumn::make('status')
       ->badge('active', show: fn ($record) => $record->is_active)
       ->badge('inactive', show: fn ($record) => !$record->is_active),
   

3. Custom Badge Styling:

   • Override default colors via config or inline:

     ->badge('urgent', color: 'red.500', icon: 'heroicon-o-bell-slash')
     

   • Use Filament’s badge colors.

4. Integration with Filament Actions:

   • Combine with Actions\Action for contextual buttons:

     Table::make()
         ->columns([
             BadgeableColumn::make('priority')
                 ->badge('high')
                 ->badge('low'),
         ])
         ->actions([
             Action::make('escalate')
                 ->visible(fn ($record) => $record->priority === 'high'),
         ]),
     

5. Reusable Badge Sets:

   • Create a trait or helper method for consistent badges:

     protected function getStatusBadges(): array {
         return [
             'published' => 'success',
             'draft' => 'warning',
             'archived' => 'gray',
         ];
     }
     

Advanced Patterns

1. Badge Icons:

   ->badge('verified', icon: 'heroicon-o-check-circle')
   

2. Badge Tooltips:

   ->badge('pro', tooltip: 'Premium features unlocked')
   

3. Badge Groups:

   • Chain multiple badge() calls for multi-value fields (e.g., tags):

     BadgeableColumn::make('tags')
         ->badge(fn ($record) => $record->tags->first()?->name)
         ->badge(fn ($record) => $record->tags->last()?->name),
     

4. Dynamic Badge Content:

   ->badge(fn ($record) => "Level {$record->experience_level}")
   

5. Override Default Rendering: Extend the column class to modify badge HTML:

   use Awcodes\FilamentBadgeableColumn\Columns\BadgeableColumn;
   
   class CustomBadgeColumn extends BadgeableColumn {
       protected function getBadgeHtml(string $value): string {
           return '<span class="custom-badge">'.$value.'</span>';
       }
   }
   

Gotchas and Tips

Common Pitfalls

1. Version Mismatch:

   • Error: Class 'Awcodes\FilamentBadgeableColumn\Columns\BadgeableColumn' not found.
   • Fix: Ensure awcodes/filament-badgeable-column and filament/filament versions align (e.g., 4.x for Filament 5.x).

2. Badge Overlap:

   • Issue: Badges stack poorly on small screens.
   • Solution: Use ->badge(..., stack: false) or adjust CSS:

     .filament-tables-column-badge {
         display: block;
     }
     

3. Closure Performance:

   • Warning: Avoid heavy logic in badge() closures for large datasets.
   • Tip: Cache results or use eager-loaded relationships.

4. Config Overrides:

   • Gotcha: Inline color overrides take precedence over config defaults.
   • Tip: Use config('filament-badgeable-column.defaults') for global defaults.

5. Dynamic Data Changes:

   • Issue: Badges don’t update if underlying data changes (e.g., soft-deletes).
   • Fix: Refresh the table or use Table::make()->refresh() in actions.

Debugging Tips

1. Inspect Badge Rendering:

   • Temporarily add ->badge('debug', color: 'primary') to verify column rendering.

2. Check for Cached Views:

   • Clear Filament’s view cache:

     php artisan view:clear
     

3. Log Badge Values:

   • Debug closures with:

     ->badge(fn ($record) => {
         \Log::debug('Record:', [$record->toArray()]);
         return $record->status;
     })
     

Extension Points

1. Custom Badge Types:

   • Extend the Badge class to add new styles or behaviors:

     class CustomBadge extends \Awcodes\FilamentBadgeableColumn\Badge {
         public static function make(string $value): static {
             return new static($value, 'custom');
         }
     }
     

2. Badge Events:

   • Listen for badge rendering via Filament’s event system (e.g., BadgeRendered):

     event(new \Awcodes\FilamentBadgeableColumn\Events\BadgeRendered($badge, $column));
     

3. Localization:

   • Override badge labels in language files:

     'filament-badgeable-column' => [
         'badges' => [
             'active' => 'Active Status',
         ],
     ],
     

4. Testing:

   • Test badges with Filament’s testing helpers:

     $this->assertTableHasColumnInRow('status', 'active', 'badge');
     

Pro Tips

1. Consistent Naming:

   • Use kebab-case for badge values (e.g., user-role) to avoid CSS conflicts.

2. Dark Mode Support:

   • Ensure badge colors work in dark mode by using Filament’s dark variants:

     ->badge('active', color: 'green.500 dark:green.400')
     

3. Accessibility:

   • Add aria-label for screen readers:

     ->badge('verified', ariaLabel: 'Account verified')
     

4. Performance:

   • For tables with many badges, use ->badge(..., lazy: true) to defer rendering.

5. Documentation:

   • Annotate complex badge logic with PHPDoc:

     /**
      * @return string[] Possible badge values: 'active', 'pending', 'archived'
      */
     public function getStatusBadges(): array { ... }