Getting Started

Minimal Steps

Installation

composer require webbingbrasil/filament-advancedfilter "^3.0"

Ensure your project uses Filament 3.x.

Register the Provider Add the service provider to config/app.php under providers:

Webbingbrasil\FilamentAdvancedFilter\FilamentAdvancedFilterServiceProvider::class,

Publish Translations (Optional)

php artisan vendor:publish --tag="filament-advancedfilter-translations"

First Use Case Add a filter to a Filament resource or page:

use Webbingbrasil\FilamentAdvancedFilter\Filters\BooleanFilter;

public static function getFilters(): array
{
    return [
        BooleanFilter::make('is_active')
            ->label('Active Status'),
    ];
}

Where to Look First

README.md for installation and basic usage.
Filters Documentation for available filter types (e.g., BooleanFilter, DateFilter, SelectFilter).
Source Code for customization or extending filters.

Implementation Patterns

Usage Patterns

Basic Filter Integration Attach filters to a Filament resource or page via getFilters():

public static function getFilters(): array
{
    return [
        BooleanFilter::make('is_active')
            ->label('Active')
            ->nullsAreUnknown(),
    ];
}

Conditional Filter Logic Use modifyQueryUsing to dynamically adjust queries:

BooleanFilter::make('is_active')
    ->modifyQueryUsing(fn (Builder $query, array $data) => $query->whereNotNull('is_active'))

Grouping Filters Organize filters into collapsible groups:

FiltersGroup::make()
    ->schema([
        BooleanFilter::make('is_active'),
        DateFilter::make('created_at'),
    ])
    ->collapsible()

Reusable Filter Configurations Create helper methods in a trait or service for consistent filter setups:

trait AdvancedFilters
{
    protected static function activeStatusFilter(): BooleanFilter
    {
        return BooleanFilter::make('is_active')
            ->label('Active')
            ->nullsAreUnknown();
    }
}

Integration with Filament Tables Combine with Filament’s built-in table filters for a seamless UX:

Table::make()
    ->columns([...])
    ->filters([
        BooleanFilter::make('is_active'),
        SelectFilter::make('status')->options(['draft', 'published']),
    ])

Workflows

Iterative Filter Refinement Start with basic filters (e.g., BooleanFilter) and gradually add complexity (e.g., DateRangeFilter, SelectFilter with dynamic options).
Testing Filters Test filters in isolation using Filament’s test utilities:
```
$this->getTable()->testFilters([
    'is_active' => true,
]);
```
Performance Optimization
- Use modifyQueryUsing to optimize database queries (e.g., avoid LIKE for large datasets).
- Cache filter options for SelectFilter if the source is expensive to compute.

Localization Publish translations and customize labels for non-English projects:

BooleanFilter::make('is_active')
    ->label(__('Status'))
    ->options([
        true => __('Active'),
        false => __('Inactive'),
    ]);

Integration Tips

Filament 3.x Compatibility: Ensure all Filament dependencies are up-to-date.
Custom Filter Logic: Extend base filters (e.g., extends BooleanFilter) to add domain-specific behavior.
Livewire Integration: Leverage Filament’s Livewire components for real-time filter updates.
Documentation: Add filter-specific docs in your project’s admin panel for end-users.

Gotchas and Tips

Pitfalls

Null Handling
- By default, BooleanFilter hides null values. Explicitly configure nullsAreUnknown(), nullsAreTrue(), or nullsAreFalse() to avoid unexpected behavior.
- Example pitfall: Assuming null values are treated as false when they’re hidden.
Query Performance
- Complex DateFilter or SelectFilter conditions (e.g., LIKE with wildcards) can slow down queries. Use modifyQueryUsing to optimize:
```
DateFilter::make('created_at')
    ->modifyQueryUsing(fn ($query, $data) => $query->whereDate('created_at', '>=', $data['start_date']))
```
Translation Conflicts
- If translations aren’t published, labels/options may default to English. Always publish translations for non-English projects:
```
php artisan vendor:publish --tag="filament-advancedfilter-translations"
```
Filter Overrides
- Custom filters extending base classes may conflict with future package updates. Test thoroughly after updates.
Livewire Caching
- Filters with dynamic options (e.g., SelectFilter with database-driven options) may cause Livewire to cache stale data. Use ->options(fn () => ...) to refresh options on each request.

Debugging

Filter Not Applying
- Check the modifyQueryUsing callback or the filter’s generated SQL in Laravel’s query log (config/logging.php).
- Verify the column name matches the database schema (case-sensitive in some databases).
UI Rendering Issues
- Clear Filament’s cache and view cache:
```
php artisan filament:cache:clear
php artisan view:clear
```
- Inspect browser console for JavaScript errors (e.g., missing translations).
Null Reference Errors
- Ensure null values are handled explicitly in filters. Example:
```
BooleanFilter::make('is_active')
    ->nullsAreUnknown()
    ->showUnknowns();
```

Tips

Custom Filter Icons Use Filament’s icon system to improve UX:

BooleanFilter::make('is_active')
    ->label('Active')
    ->icon('heroicon-o-check-circle');

Default Filter Values Set defaults for frequently used filters:
```
BooleanFilter::make('is_active')
    ->default(true);
```

Dynamic Filter Options Fetch options dynamically for SelectFilter:

SelectFilter::make('status')
    ->options(fn () => Status::query()->pluck('name', 'id'))
    ->searchable();

Filter Persistence Use Filament’s persistFilters to save filter states across sessions:
```
Table::make()
    ->persistFilters()
    ->filters([...]);
```

Extending Filters Create custom filters by extending base classes:

class CustomBooleanFilter extends BooleanFilter
{
    protected function setUp(): void
    {
        $this->label(__('Custom Status'));
        $this->nullsAreUnknown();
    }
}

Testing Filters Test filter logic with PHPUnit:

public function test_boolean_filter()
{
    $this->getTable()->testFilters([
        'is_active' => true,
    ]);
    $this->assertDatabaseHas('models', ['is_active' => true]);
}

Performance Monitoring Use Laravel Debugbar or Query Profiler to monitor filter impact on query performance:

if (app()->environment('local')) {
    \Barryvdh\Debugbar\LaravelDebugbar::info(['filters' => $this->getFilters()]);
}

Filament Advancedfilter Laravel Package