Filament Combobox Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require novadaemon/filament-combobox
   

   Ensure compatibility with your Filament version (3.x or 4.x).

2. First Use Case: Replace a standard Select field with Combobox in a Filament form:

   use Novadaemon\FilamentCombobox\Combobox;
   
   Combobox::make('field_name')
       ->options(['key1' => 'Label 1', 'key2' => 'Label 2'])
   

3. Where to Look First:

   • README for basic usage.
   • Filament Docs for Select field methods (since Combobox extends it).
   • GitHub Issues for edge cases or bugs.

Implementation Patterns

Core Workflows

1. Static Options: Use for fixed, non-database-backed choices (e.g., status flags, predefined tags):

   Combobox::make('status')
       ->options([
           'active' => 'Active',
           'inactive' => 'Inactive',
       ])
       ->required()
       ->default('active');
   

2. Eloquent Relationships: Fetch data dynamically from a model relationship (e.g., User::hasMany('Roles')):

   Combobox::make('roles')
       ->relationship('roles', 'name') // 'roles' = relationship, 'name' = display column
       ->searchable() // Enable search/filtering
       ->preload();   // Preload related data for performance
   

3. Query Modifiers: Customize the underlying query (e.g., filter active categories):

   Combobox::make('categories')
       ->relationship('categories', 'title')
       ->query(fn (Builder $query) => $query->where('is_active', true));
   

4. Multi-Select: Enable multiple selections (default behavior):

   Combobox::make('tags')
       ->options(['tag1' => 'Tag 1', 'tag2' => 'Tag 2'])
       ->multiple(); // Explicitly declare (redundant but clear)
   

5. Integration with Filament Tables: Use in table columns for inline editing:

   Table::make(...)
       ->columns([
           Tables\Columns\SelectColumn::make('status')
               ->options(['active' => 'Active', 'inactive' => 'Inactive'])
               ->combobox(), // Convert to combobox
       ]);
   

Advanced Patterns

• Conditional Logic: Combine with Filament’s visible()/required():

  Combobox::make('advanced_option')
      ->options(['opt1' => 'Option 1'])
      ->visible(fn (?User $record) => $record?->is_admin);
  

• Custom Styling: Override Blade templates or use CSS:

  Combobox::make('custom_styled')
      ->options(['opt1' => 'Option 1'])
      ->extraAttributes(['class' => 'bg-gray-100']);
  

• API Integration: Fetch options from an external API (use ->options() with a closure):

  Combobox::make('api_data')
      ->options(fn () => Http::get('https://api.example.com/data')->json());
  

Gotchas and Tips

Pitfalls

1. Relationship Caching:

   • Issue: ->relationship() may not update if the related model changes.
   • Fix: Use ->preload() or manually refresh the query:

     ->query(fn (Builder $query) => $query->fresh())
     

2. Search Performance:

   • Issue: Large datasets slow down the combobox.
   • Fix: Limit results with ->limit(10) or use database indexes.

3. Default Values:

   • Issue: Non-existent defaults (e.g., ->default('nonexistent')) may break.
   • Fix: Validate defaults against ->options() or use ->default(null).

4. Multi-Select Quirks:

   • Issue: ->multiple() may not persist if the model lacks a pivot table.
   • Fix: Ensure the relationship uses belongsToMany or morphToMany.

5. Filament 4.x Breaking Changes:

   • Issue: Some methods (e.g., ->searchable()) may behave differently in Filament 4.
   • Fix: Check the Filament 4 Upgrade Guide.

Debugging Tips

• Inspect Options: Dump the rendered options to debug:

  ->options(fn () => collect(['opt1' => 'Option 1'])->dump()->all())
  

• Check JavaScript Errors: Open browser dev tools (F12) to verify if the combobox’s JS is loading.

• Log Queries: Enable Laravel query logging to debug relationship issues:

  DB::enableQueryLog();
  // ... use combobox ...
  dd(DB::getQueryLog());
  

Extension Points

1. Custom Templates: Override the Blade view (resources/views/vendor/filament-combobox/...) for UI changes.

2. Add-on Methods: Extend the class to add custom logic:

   class CustomCombobox extends Combobox {
       public function customMethod() { ... }
   }
   

3. Event Listeners: Hook into Filament’s events (e.g., AfterFormSaved) to react to combobox changes:

   use Filament\Events\AfterFormSaved;
   
   AfterFormSaved::listen(function (AfterFormSaved $event) {
       if ($event->form->hasField('combobox_field')) {
           // Handle logic
       }
   });
   

4. Localization: Override labels/placeholders via Filament’s localization system:

   Combobox::make('field')
       ->label(__('filament-combobox::labels.custom_label'));
   

Config Quirks

• No Package Config: The package relies entirely on Filament’s config. Check config/filament.php for global settings.

• Asset Publishing: If extending views, publish assets:

  php artisan vendor:publish --tag=filament-combobox-assets