README

Filament Dcat Filters

Bring Dcat Admin's powerful filter features to Filament

Built with PHP 8.3+ for Laravel 12 and Filament v4

A modern collection of enhanced filters inspired by Dcat Admin, combining intuitive UI components with powerful filtering capabilities for Filament admin panels.

English Documentation | 中文文档

Features

Core Filters

• 🎯 Scope Filter - Tab-style quick filters for common queries
• 📊 Range Filter - Simplified date/number range filtering (3 lines of code!)
• 📅 Date Component Filter - Filter by year, month, or day separately
• 🔍 SelectTable Filter - Modal table selector with search and pagination
• 🎭 Modal Select Filter - Dcat Admin style modal with full table display
• 🔢 Between Filter - Numeric range filtering shortcut
• 🙈 Hidden Filter - URL parameter-based filtering without UI

Quick Filters

• ⚡ LIKE Filter - Text search with wildcard control (supports NOT LIKE)
• 📋 IN Filter - Multiple value selection (supports NOT IN)
• 🔢 Comparison Filter - Comparison operators (>, <, >=, <=, =, !=)
• ✅ Boolean Filter - True/false/all toggle for boolean fields
• 🔘 Null Filter - NULL/NOT NULL value filtering
• 📝 Enum Filter - Auto-generate options from PHP 8.1+ Enum classes
• 🔍 FullText Filter - Search across multiple fields simultaneously
• 📆 Relative Date Filter - Pre-defined date range shortcuts

Specialized Filters

• 🗄️ JSON Filter - Query JSON/JSONB columns with path access
• 🏷️ FindInSet Filter - Query comma-separated values using FIND_IN_SET
• 🔤 Regex Filter - Pattern matching with regular expressions
• 📱 InputMask Filter - Formatted input with masks (phone, credit card, etc.)
• 📍 GeoLocation Filter - Geographic proximity filtering with Haversine formula
• 🔗 Filter Group - Combine filters with AND/OR logic

Advanced Features

• 🔄 Reset All Filters - One-click reset button for all active filters
• 💾 Filter State Persistence - Remember filter states across sessions
• 🔗 URL Query Parameter Sync - Shareable filter URLs without page reload
• 🔗 Cascading Select Filter - Dynamic dependent dropdowns
• ♿ Accessibility Support - ARIA labels and keyboard navigation
• 📋 Filter Presets - Save and load filter combinations
• 🔢 Scope Badge Counts - Display record counts on scope tabs
• 📤 Filter Export/Import - Share filter configurations via URL or JSON

Additional Features

• 🎨 Highly Customizable - Extensive customization options for each filter
• 📱 Mobile Friendly - Responsive design for all screen sizes
• 🌐 Bilingual Docs - Complete English and Chinese documentation
• ✅ Fully Tested - Comprehensive test coverage with 400+ tests

Version Compatibility

Filament	Filament Dcat Filters	PHP	Laravel
4.x	1.x	^8.3	^12.0

Installation

You can install the package via composer:

composer require cooper/filament-dcat-filters

Optionally, you can publish the config file:

php artisan vendor:publish --tag="filament-dcat-filters-config"

Optionally, you can publish the views:

php artisan vendor:publish --tag="filament-dcat-filters-views"

Quick Start

Scope Filter

Perfect for quick filtering with tab-style buttons:

use Cooper\FilamentDcatFilters\Filters\ScopeFilter;

ScopeFilter::make('status')
    ->scopes([
        'all' => 'All',
        'active' => 'Active',
        'inactive' => 'Inactive',
    ])

View detailed documentation →

Range Filter

Simplified date/number range filtering:

use Cooper\FilamentDcatFilters\Filters\RangeFilter;

RangeFilter::make('created_at')->datetime()

View detailed documentation →

SelectTable Filter

Modal table selector with search and pagination:

use Cooper\FilamentDcatFilters\Filters\SelectTableFilter;

SelectTableFilter::make('user_id')
    ->relationship('user', 'name')
    ->multiple()

View detailed documentation →

Date Component Filter

Filter by year, month, or day components:

use Cooper\FilamentDcatFilters\Filters\DateComponentFilter;

DateComponentFilter::make('created_at')->year()
DateComponentFilter::make('birth_date')->month()
DateComponentFilter::make('published_at')->day()

View detailed documentation →

Modal Select Filter

Dcat Admin style modal with full table display:

use Cooper\FilamentDcatFilters\Filters\ModalSelectFilter;

ModalSelectFilter::make('user_id')
    ->model(User::class, 'name', 'id')
    ->dialogTitle('Select User')
    ->displayColumns(['id' => 'ID', 'name' => 'Name', 'email' => 'Email'])
    ->searchable(['name', 'email'])
    ->multiple()

View detailed documentation →

Quick Filters

Built-in filters for common operations:

use Cooper\FilamentDcatFilters\Filters\{LikeFilter, InFilter, ComparisonFilter, BetweenFilter};

// LIKE search (with NOT LIKE support)
LikeFilter::make('title'),
LikeFilter::make('spam_keywords')->notLike(), // Exclude matches

// IN array (with NOT IN support)
InFilter::make('category_id')
    ->options(Category::pluck('name', 'id')->toArray()),
InFilter::make('blocked_users')->notIn(), // Exclude selected

// Comparison (>, <, =, >=, <=, !=)
ComparisonFilter::make('views')->gte()->label('Minimum Views'),

// Between (numeric range)
BetweenFilter::make('price')->label('Price Range'),

View detailed documentation →

Boolean Filter

Dedicated true/false/all toggle for boolean fields:

use Cooper\FilamentDcatFilters\Filters\BooleanFilter;

BooleanFilter::make('is_active')
    ->label('Status')
    ->trueLabel('Active')
    ->falseLabel('Inactive')

// Quick presets
BooleanFilter::active()      // is_active field
BooleanFilter::published()   // is_published field
BooleanFilter::enabled()     // is_enabled field

Null Filter

Filter for NULL or NOT NULL values:

use Cooper\FilamentDcatFilters\Filters\NullFilter;

NullFilter::make('deleted_at')
    ->nullLabel('Not Deleted')
    ->notNullLabel('Deleted')

// Quick presets
NullFilter::deleted()    // deleted_at field
NullFilter::assigned()   // Check if field is assigned
NullFilter::empty()      // Check if field is empty/filled

Enum Filter

Auto-generate options from PHP 8.1+ Enum classes:

use Cooper\FilamentDcatFilters\Filters\EnumFilter;

EnumFilter::make('status')
    ->enum(OrderStatus::class)
    ->multiple()
    ->exclude([OrderStatus::Cancelled])

FullText Filter

Search across multiple fields simultaneously:

use Cooper\FilamentDcatFilters\Filters\FullTextFilter;

FullTextFilter::make('search')
    ->searchIn(['name', 'email', 'phone'])
    ->placeholder('Search users...')
    ->minLength(2)
    ->debounce(300)

Relative Date Filter

Pre-defined date range shortcuts:

use Cooper\FilamentDcatFilters\Filters\RelativeDateFilter;

RelativeDateFilter::make('created_at')
    ->only(['today', 'yesterday', 'last_7_days', 'last_30_days', 'this_month'])

// Quick presets
RelativeDateFilter::common()     // Common date ranges
RelativeDateFilter::weekly()     // Week/month focused
RelativeDateFilter::reporting()  // Quarter/year focused

Hidden Filter

URL parameter-based filtering (no UI):

use Cooper\FilamentDcatFilters\Filters\HiddenFilter;

// Pre-filter by tenant
HiddenFilter::make('tenant_id')
    ->default(auth()->user()->tenant_id)
    ->eq()

View detailed documentation →

Reset All Filters

Add a one-click reset button:

use Cooper\FilamentDcatFilters\Concerns\HasResetFilters;

class ListUsers extends ListRecords
{
    use HasResetFilters;

    protected function getHeaderActions(): array
    {
        return [
            $this->getResetFiltersAction(),
        ];
    }
}

View detailed documentation →

Filter State Persistence

Remember filter states across sessions:

use Cooper\FilamentDcatFilters\Concerns\HasFilterPersistence;

class ListUsers extends ListRecords
{
    use HasFilterPersistence;

    protected string $filterPersistenceKey = 'users-list-filters';
}

View detailed documentation →

URL Query Parameter Sync

Shareable filter URLs:

use Cooper\FilamentDcatFilters\Concerns\SyncsFiltersToUrlWithoutHistory;

class ListUsers extends ListRecords
{
    use SyncsFiltersToUrlWithoutHistory;
}

View detailed documentation →

Cascading Select Filter

Dynamic dependent dropdowns:

use Cooper\FilamentDcatFilters\Filters\CascadingSelectFilter;

CascadingSelectFilter::make('location')
    ->levels([
        'country' => [
            'label' => 'Country',
            'options' => fn () => Country::pluck('name', 'id'),
        ],
        'state' => [
            'label' => 'State',
            'options' => fn ($country) => State::where('country_id', $country)->pluck('name', 'id'),
            'dependsOn' => 'country',
        ],
        'city' => [
            'label' => 'City',
            'options' => fn ($state) => City::where('state_id', $state)->pluck('name', 'id'),
            'dependsOn' => 'state',
        ],
    ])

View detailed documentation →

Documentation

Core Filters

• 📖 Scope Filter - Tab-style quick filters
• 📖 Range Filter - Date/number range filtering
• 📖 Date Component Filter - Year/Month/Day filtering
• 📖 SelectTable Filter - Modal table selector
• 📖 Modal Select Filter - Dcat Admin style modal table selector
• 📖 Quick Filters - LIKE, IN, GT, LT, BETWEEN filters

Specialized Filters

• 📖 JSON Filter - Query JSON/JSONB columns with path access
• 📖 FindInSet Filter - Query comma-separated values
• 📖 Regex Filter - Pattern matching with regular expressions
• 📖 InputMask Filter - Formatted input with masks
• 📖 GeoLocation Filter - Geographic proximity filtering
• 📖 Filter Group - Combine filters with AND/OR logic

Advanced Features

• 📖 Reset All Filters - One-click reset functionality
• 📖 Filter State Persistence - Session-based filter memory
• 📖 URL Query Parameter Sync - Shareable filter URLs
• 📖 Cascading Select Filter - Dynamic dependent dropdowns
• 📖 Accessibility - ARIA labels and keyboard support
• 📖 Advanced Features - API support, Hidden filters
• 📖 Concerns (Traits) - Filter presets, badge counts, export/import

Guides & References

• 📖 Usage Examples - Complete working examples
• 📖 Demo Guide - Interactive demonstrations
• 📖 Comparison with Dcat Admin - Feature comparison
• 📖 Package Structure - Package architecture
• 📖 Documentation Structure - Documentation organization
• 📖 Future Improvements - Roadmap and planned features

Facade Usage

You can also use the Facade for quick access:

use Cooper\FilamentDcatFilters\Facades\FilamentDcatFilters;

FilamentDcatFilters::scopeFilter('status')->scopes([...]);
FilamentDcatFilters::rangeFilter('created_at')->datetime();

Testing

composer test

Code Quality

# Format code
composer format

# Static analysis
composer analyse

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

If you discover any security-related issues, please email myxiaoao@gmail.com.

Credits

• Cooper
• Inspired by Dcat Admin
• All Contributors

License

The MIT License (MIT). Please see License File for more information.