kblais/query-filter

Easily create filters for your Eloquent models.

v3.2.0 2024-04-16 12:11 UTC

Requires

• php: ^8.0
• illuminate/database: ^9.33|^10.0|^11.0
• illuminate/http: ^9.33|^10.0|^11.0
• illuminate/support: ^9.33|^10.0|^11.0
• spatie/laravel-package-tools: ^1.1

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.0
• larastan/larastan: ^2.9
• orchestra/testbench: ^7.0|^8.0|^9.0

MIT

• Killian Blais

README

Easily create filters for your Eloquent model.

Based on Jeffray Way's Laracast tutorial.

Installation

You can install the package via composer:

composer require kblais/query-filter

You can publish the config file with:

php artisan vendor:publish --provider="Kblais\QueryFilter\QueryFilterServiceProvider" --tag="query-filter-config"

This is the contents of the published config file:

return [
    'default-filters-source' => null,
];

Usage

A QueryFilter is a class to apply, based on an array or a Request, multiple conditions.

You can call any Eloquent method directly from filter methods.

use Kblais\QueryFilter\QueryFilter;

class PostFilter extends QueryFilter
{
    public function title($value)
    {
        return $this->where('foo', 'bar');
    }

    public function author($value)
    {
        return $this->whereHas('author', function ($builder) use ($value) {
            $this->where('name', $value);
        });
    }
}

To allow a model to use query filters, you have to add the Filterable trait on your model.

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Kblais\QueryFilter\Filterable;

class Post extends Model
{
    use Filterable;
}

You can then use the filter() scope from anywhere:

// From an array...
$filterInput = [
    'title' => 'Les Trois Mousquetaires',
];

$posts = Post::filter(PostFilter::make($filterInput))->get();

// ...Or in a controller action
public function index(PostFilter $filter)
{
    // Filter is automatically populated with Request data when injected
    return Post::filter($filter)->get();
}

If your filter parameters are always placed in an array key (for example filters), you can define the default-filters-source config key in the config file, or add a protected string $source = 'filters' in your QueryFilter.

Frequent issues

Call to an undefined method App\QueryFilters\YourFilter::anEloquentScope(). with PHPStan

To fix this error message, add the following DocBlock to your filter:

/**
 * @mixin \App\Models\ModelOfYourScope
 */

Testing

The test suite is composed of 3 tests: PHPCsFixer (coding style), PHPStan (static analysis) and PHPUnit (unit tests).

You can run all these tests running the following command:

composer tests

Changelog

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

Contributing

• Follow the PSR-2 Coding Standard. Use PHP-CS-Fixer to apply the conventions.
• Add tests for the features you add and bugs you discover.

Credits

• Killian BLAIS
• All Contributors

License

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