README

A powerful, type-safe filtering system for Laravel applications. Filter Core provides a clean API for building complex database queries with automatic value sanitization, validation, and support for relations.

Features

6 Filter Types: Boolean, Integer, Text, Select, Date, Decimal filters
18 Match Modes: IS, IS_NOT, ANY, NONE, CONTAINS, GT, LT, BETWEEN, REGEX, EMPTY, DATE_RANGE, and more
AND/OR Logic: Complex nested filter groups with FilterSelection
Relation Filtering: Filter through Eloquent relationships with whereHas()
Collection Filtering: Apply the same filter logic to in-memory Collections
Date Filtering: Quick selections, relative ranges, fiscal years, timezone support
Decimal Filtering: Precision control, stored-as-integer support for prices
Quick Filter Presets: Database-driven, user-configurable date range presets
Value Sanitization: Automatic conversion of input values (e.g., "true" → true)
Value Validation: Laravel validation rules with descriptive error messages
Dynamic Filters: Create filters at runtime without class definitions
JSON Serialization: Persist and restore filter configurations with optional model binding
Debugging Tools: SQL preview, bindings interpolation, human-readable explanations

Installation

composer require ameax/filter-core

Publish the migrations:

php artisan vendor:publish --tag="filter-core-migrations"
php artisan migrate

Optionally publish the config:

php artisan vendor:publish --tag="filter-core-config"

Quick Start

1. Create a Filter

use Ameax\FilterCore\Filters\SelectFilter;

class StatusFilter extends SelectFilter
{
    public function column(): string
    {
        return 'status';
    }

    public function options(): array
    {
        return [
            'active' => 'Active',
            'inactive' => 'Inactive',
            'pending' => 'Pending',
        ];
    }
}

2. Add Filterable Trait to Model

use Ameax\FilterCore\Concerns\Filterable;

class User extends Model
{
    use Filterable;

    protected static function filterResolver(): \Closure
    {
        return fn () => [
            StatusFilter::class,
            CountFilter::class,
        ];
    }
}

3. Apply Filters

use Ameax\FilterCore\Data\FilterValue;

// Simple filter
$users = User::query()
    ->applyFilter(FilterValue::for(StatusFilter::class)->is('active'))
    ->get();

// Multiple filters with AND
$users = User::query()
    ->applyFilters([
        FilterValue::for(StatusFilter::class)->any(['active', 'pending']),
        FilterValue::for(CountFilter::class)->gt(10),
    ])
    ->get();

4. Use Filter Selections for Complex Logic

use Ameax\FilterCore\Selections\FilterSelection;
use Ameax\FilterCore\Selections\FilterGroup;

// AND logic (default)
$selection = FilterSelection::make()
    ->where(StatusFilter::class)->is('active')
    ->where(CountFilter::class)->gt(10);

// OR logic
$selection = FilterSelection::makeOr()
    ->where(StatusFilter::class)->is('active')
    ->where(StatusFilter::class)->is('pending');

// Nested: count > 10 AND (status = 'active' OR status = 'pending')
$selection = FilterSelection::make()
    ->where(CountFilter::class)->gt(10)
    ->orWhere(function (FilterGroup $g) {
        $g->where(StatusFilter::class)->is('active');
        $g->where(StatusFilter::class)->is('pending');
    });

$users = User::query()->applySelection($selection)->get();

5. Debug Your Filters

$selection = FilterSelection::make()
    ->forModel(User::class)
    ->where(StatusFilter::class)->is('active')
    ->where(CountFilter::class)->gt(10);

// SQL with placeholders
$selection->toSql();
// → "select * from `users` where `status` = ? and `count` > ?"

// SQL with values interpolated
$selection->toSqlWithBindings();
// → "select * from `users` where `status` = 'active' and `count` > 10"

// Human-readable explanation
$selection->explain();
// → "StatusFilter IS 'active' AND CountFilter GT 10"

// Full debug info
$selection->debug();
// → ['sql' => ..., 'sql_with_bindings' => ..., 'bindings' => [...], 'filters' => [...], 'explanation' => ...]

Documentation

Guide	Description
Getting Started	Installation and basic setup
Filter Types	All 6 filter types explained
Match Modes	All 19 match modes explained
Filter Selections	AND/OR logic with nested groups
Relation Filters	Filter through relationships
Collection Filtering	In-memory collection filtering
Dynamic Filters	Runtime filter creation
Validation	Input validation and sanitization
Advanced Usage	Custom logic and extensibility
Date Filter	Date filtering with timezone support

Quick Reference

Filter Types

Type	Use Case	Key Modes
`SelectFilter`	Predefined options	`is`, `any`, `none`
`IntegerFilter`	Numeric values	`gt`, `lt`, `between`
`TextFilter`	Text search	`contains`, `startsWith`, `regex`
`BooleanFilter`	True/False	`is`
`DateFilter`	Date/DateTime columns	`dateRange`, `notInDateRange`
`DecimalFilter`	Decimal/Float values	`gt`, `lt`, `between`

Date Filter

use Ameax\FilterCore\Filters\DateFilter;
use Ameax\FilterCore\DateRange\DateRangeValue;

// Static filter class
class CreatedAtFilter extends DateFilter
{
    public function column(): string
    {
        return 'created_at';
    }

    // Enable timezone conversion for DATETIME columns
    public function hasTime(): bool
    {
        return true;
    }
}

// Dynamic filter
$filter = DateFilter::dynamic('created_at')
    ->withColumn('created_at')
    ->withTime(); // DATETIME with timezone support

// Quick selections
DateRangeValue::today();
DateRangeValue::thisWeek();
DateRangeValue::thisMonth();
DateRangeValue::thisQuarter();
DateRangeValue::thisYear();

// Relative ranges
DateRangeValue::lastDays(30);
DateRangeValue::nextDays(7);
DateRangeValue::lastMonths(3);

// Specific periods
DateRangeValue::quarter(2, yearOffset: 0);  // Q2 this year
DateRangeValue::month(6, yearOffset: -1);   // June last year
DateRangeValue::fiscalYear(startMonth: 7);  // July-June fiscal year

// Custom ranges
DateRangeValue::between('2024-01-01', '2024-12-31');
DateRangeValue::from('2024-06-01');
DateRangeValue::until('2024-12-31');

Decimal Filter

use Ameax\FilterCore\Filters\DecimalFilter;

// For price columns stored as cents (integer)
class PriceFilter extends DecimalFilter
{
    public function column(): string
    {
        return 'price_cents';
    }

    public function storedAsInteger(): bool
    {
        return true; // User enters 19.99, query uses 1999
    }

    public function precision(): int
    {
        return 2;
    }
}

// Dynamic filter
$filter = DecimalFilter::dynamic('price')
    ->withColumn('price_cents')
    ->withStoredAsInteger(true)
    ->withPrecision(2);

Match Modes

// Equality
->is('value')           // = value
->isNot('value')        // != value

// Sets
->any(['a', 'b'])       // IN (a, b)
->none(['a', 'b'])      // NOT IN (a, b)

// Comparison
->gt(10)                // > 10
->gte(10)               // >= 10
->lt(100)               // < 100
->lte(100)              // <= 100
->between(10, 100)      // BETWEEN 10 AND 100

// Text
->contains('text')      // LIKE %text%
->startsWith('pre')     // LIKE pre%
->endsWith('fix')       // LIKE %fix
->regex('^pattern')     // REGEXP

// Null
->empty()               // IS NULL
->notEmpty()            // IS NOT NULL

Relation Filters

// In filterResolver
protected static function filterResolver(): \Closure
{
    return fn () => [
        StatusFilter::class,                    // Direct filter
        CompanyStatusFilter::via('company'),    // Filter through relation
    ];
}

// Usage
User::query()
    ->applyFilter(FilterValue::for(CompanyStatusFilter::class)->is('active'))
    ->get();

Dynamic Filters

use Ameax\FilterCore\Filters\SelectFilter;
use Ameax\FilterCore\Filters\DateFilter;
use Ameax\FilterCore\Filters\DecimalFilter;

// Select filter
$filter = SelectFilter::dynamic('status')
    ->withColumn('status')
    ->withOptions(['active' => 'Active', 'inactive' => 'Inactive']);

// Date filter with timezone
$filter = DateFilter::dynamic('created_at')
    ->withColumn('created_at')
    ->withTime()
    ->withPastOnly();

// Decimal filter for prices
$filter = DecimalFilter::dynamic('price')
    ->withColumn('price_cents')
    ->withStoredAsInteger(true)
    ->withPrecision(2);

JSON Serialization

// Save
$json = $selection->toJson();

// Load
$selection = FilterSelection::fromJson($json);

// With model binding for self-validation and execution
$selection = FilterSelection::make('Active Users', User::class)
    ->where(StatusFilter::class)->is('active');

$json = $selection->toJson();
$restored = FilterSelection::fromJson($json);
$restored->validate();  // Self-validates against User model
$users = $restored->execute();  // Self-executes on User model

Configuration

// config/filter-core.php
return [
    // User model for FilterPreset ownership
    'user_model' => \App\Models\User::class,

    // Timezone for date/datetime filter queries
    // When filtering "today" in Europe/Berlin, converts to UTC for DB
    'timezone' => 'Europe/Berlin',
];

Testing

composer test

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

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

ameax / filter-core

Maintainers

Details