Getting Started

Minimal Setup

Installation

composer require howdu/filament-record-switcher

Publish the config (if needed):

php artisan vendor:publish --provider="Howdu\FilamentRecordSwitcher\FilamentRecordSwitcherServiceProvider"

Enable for a Resource Add the trait to your Filament resource class:

use Howdu\FilamentRecordSwitcher\Concerns\HasRecordSwitcher;

class PostResource extends Resource
{
    use HasRecordSwitcher;
    // ...
}

First Use Case
- Navigate to any record in your resource.
- Click the page title (now a dropdown button).
- Search or browse records to quickly switch between them.

Implementation Patterns

Core Workflow

Resource Integration
- Apply HasRecordSwitcher to any Filament resource.
- Customize via $recordSwitcher property in the resource class:
```
protected static ?string $recordSwitcher = 'custom'; // or 'default'
```
Search & Navigation
- Default Behavior: Dropdown shows all records with search/filtering.
- Customization: Override getRecordSwitcherQuery() to modify the query:
```
public function getRecordSwitcherQuery(): Builder
{
    return parent::getRecordSwitcherQuery()
        ->where('is_active', true);
}
```

Styling & UX

Use $recordSwitcherIcon to change the dropdown icon:

protected static string $recordSwitcherIcon = 'heroicon-o-chevron-down';

Disable for specific records via canAccessRecordSwitcher():

public static function canAccessRecordSwitcher(): bool
{
    return auth()->user()->can('switch_records');
}

Multi-Resource Projects
- Group resources by namespace or prefix in the dropdown using $recordSwitcherGroup:
```
protected static ?string $recordSwitcherGroup = 'Admin';
```

Advanced Patterns

Dynamic Permissions: Use canAccessRecordSwitcher() to gate access per record/user.

Custom Actions: Extend the dropdown with custom actions via getRecordSwitcherActions():

public function getRecordSwitcherActions(): array
{
    return [
        Action::make('archive')
            ->label('Archive Record')
            ->action(fn (Record $record) => $record->update(['is_active' => false])),
    ];
}

Lazy Loading: For large datasets, implement pagination in getRecordSwitcherQuery():
```
return parent::getRecordSwitcherQuery()->paginate(20);
```

Gotchas and Tips

Common Pitfalls

Query Performance
- Issue: Slow dropdown rendering with large datasets.
- Fix: Add ->select('id', 'title', 'slug') to limit columns or use ->with(['relationship']) sparingly.
- Tip: Cache the query results if the dataset rarely changes:
```
return Cache::remember("record-switcher-{$this->getModel()}", now()->addHours(1), fn() => parent::getRecordSwitcherQuery());
```

Permission Conflicts

Issue: Dropdown shows records the user can’t access.

Fix: Override canAccessRecordSwitcher() or filter the query:

public function getRecordSwitcherQuery(): Builder
{
    return parent::getRecordSwitcherQuery()->whereIn('id', fn($q) => $q->select('id')->from('posts')->where('user_id', auth()->id()));
}

Styling Overrides
- Issue: Dropdown styles clash with custom Filament themes.
- Fix: Use the $recordSwitcherClass property to add custom classes:
```
protected static string $recordSwitcherClass = 'filament-record-switcher-custom';
```
- Tip: Inspect the generated HTML (via browser dev tools) to target specific elements.
Relationships & Eager Loading
- Issue: N+1 queries when loading related data.
- Fix: Eager load relationships in getRecordSwitcherQuery():
```
return parent::getRecordSwitcherQuery()->with(['author', 'category']);
```
- Warning: Avoid over-eager-loading to keep the dropdown performant.

Debugging Tips

Log Queries: Temporarily add ->toSql() to getRecordSwitcherQuery() to debug:
```
\Log::info($this->getRecordSwitcherQuery()->toSql());
```
Check Permissions: Use dd($this->canAccessRecordSwitcher()) to verify access logic.
Clear Cache: If changes don’t reflect, run:
```
php artisan optimize:clear
```

Extension Points

Custom Dropdown Content

Override getRecordSwitcherDropdownItems() to replace the default list:

public function getRecordSwitcherDropdownItems(): array
{
    return [
        DropdownItem::make('Custom Item')
            ->url(fn () => route('custom.path'))
            ->icon('heroicon-o-external-link'),
    ];
}

Event Listeners
- Listen for record-switcher.before-switch to intercept navigation:
```
event(new RecordSwitcherEvent($record));
```
- Publish the config to access event names:
```
php artisan vendor:publish --tag=filament-record-switcher-config
```

Testing

Test dropdown interactions with:

$this->getFilament()->actingAs($user)
    ->get($resource->getUrl())
    ->assertSeeInDropdown($record->title);

Use assertSoftDeletes() for soft-deleted records if applicable.

Pro Tips

Combine with Filament Actions: Add a "Quick Edit" action to the dropdown:

public function getRecordSwitcherActions(): array
{
    return [
        Action::make('edit')
            ->label('Quick Edit')
            ->icon('heroicon-o-pencil')
            ->url(fn (Record $record) => $this->getUrl('edit', ['record' => $record])),
    ];
}

Localization: Translate labels via Filament’s translation system:

protected static ?string $recordSwitcherLabel = __('filament-record-switcher::labels.switch_record');

Dark Mode: Ensure icons/styles work in dark mode by testing with Filament’s dark mode toggle.


```markdown
### Config Quirks
- **Default vs. Custom**: The `default` switcher uses Filament’s global search styling, while `custom` provides a blank slate for styling.
- **Grouping**: Groups are alphabetically sorted by default. Override `getRecordSwitcherGroupSort()` to customize:
  ```php
  public static function getRecordSwitcherGroupSort(): array
  {
      return ['Admin', 'Content', 'Settings'];
  }

Empty State: Customize the "no results" message via:

protected static ?string $recordSwitcherEmptyState = __('No records found.');

Filament Record Switcher Laravel Package