soliudeen999/laravel-query-filter

A powerful and flexible query filter system for Laravel applications

dev-main 2025-11-28 09:38 UTC

Requires

• php: ^8.0
• illuminate/database: ^8.0|^9.0|^10.0
• illuminate/support: ^8.0|^9.0|^10.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.68
• orchestra/testbench: ^6.0|^7.0|^8.0
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^9.0|^10.0

MIT

• Soliudeen999

• search
• filter
• query
• laravel
• eloquent

README

A powerful and flexible query filter and search system for Laravel applications that allows you to easily filter and search your Eloquent models based on request parameters.

Installation

You can install the package via composer:

composer require soliudeen999/laravel-query-filter

Setup

Add the HasFilter trait to your model and define the filterable fields:

use Soliudeen999\QueryFilter\Traits\HasFilter;

class User extends Model
{
    use HasFilter;

    protected array $filterables = [
        'name',
        'email',
        'status',
        'role' => ['admin', 'user', 'guest'],
        'posts' => 'posts:title',
        'withTrashed' => ['with', 'only']
    ];
}

Usage

Basic Filtering

// Filter using request parameters automatically
$users = User::filter()->get();

// Filter with specific parameters
$users = User::filter(['status' => 'active'])->get();

// Filter multiple fields
$users = User::filter([
    'status' => 'active',
    'role' => 'admin'
])->get();

Advanced Filtering

Comparison Operators

The following operators are supported:

• gt (greater than)
• lt (less than)
• eq (equals)
• neq (not equals)
• gte (greater than or equal)
• lte (less than or equal)
• btw (between)
• in (in array)

// Using operators
$users = User::filter([
    'age' => ['gt' => 18, 'lt' => 65],
    'status' => ['in' => ['active', 'pending']],
    'price' => ['btw' => [100, 200]],
    'rating' => ['gte' => 4.5]
])->get();

Relationship Filtering

Define relationship filters in your $filterables array:

protected array $filterables = [
    'posts' => 'posts:relationship,title', // format: 'table:relationship,column'
    'comments' => 'comments:relationship,content'
];

// Usage
$users = User::filter([
    'posts' => 'Laravel', // Find users with posts containing 'Laravel' in title
    'comments' => ['active'] // Find users with these comment types
])->get();

Special Values Filtering

Define allowed values in your $filterables array:

protected array $filterables = [
    'role' => ['admin', 'user', 'guest'],
    'status' => ['active', 'inactive']
];

// Usage
$users = User::filter([
    'role' => 'admin',  // Will only filter if 'admin' is in allowed values
    'status' => 'active'
])->get();

Setup

Add the HasSearch trait to your model and define the searchable fields:

use Soliudeen999\QueryFilter\Traits\HasFilter;

class User extends Model
{
    use HasSearch;

    protected array $searchable = [
        'name',
        'email',
        'status',
        'posts:name'
    ];
}

Usage

Basic Filtering

// Filter using request parameters automatically
$users = User::search('what to look for')->get();

// Filter with specific parameters
$users = User::search('what to look for')->get();

// Filter multiple fields
$users = User::search('what to look for')->get();

Request Parameters

When using request parameters, you can filter using query string parameters:

/users?name=John&status=active&age[gt]=18&age[lt]=65&sort=-created_at

Best Practices

1. Always define the $filterables array in your model to specify which fields can be filtered
2. Use type hints and validation where possible
3. Keep the filter values consistent with your database schema
4. Use relationship filters for complex queries
5. Implement custom search scopes for specific search requirements

Error Handling

The package will throw exceptions for:

• Missing $filterables property
• Invalid relationship filter configurations
• Invalid operator usage
• Invalid between clause values

Make sure to handle these exceptions appropriately in your application.

Testing

composer test

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

Credits

• Soliudeen999
• All Contributors

License

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