aw-studio / laravel-model-index
Filterable, sortable, searchable index listing for laravel models
Requires
- illuminate/database: ^11
- illuminate/http: ^11
Requires (Dev)
- laravel/pint: ^1.19
- orchestra/testbench: ^9.9
- pestphp/pest: ^3.7
- spatie/laravel-ray: ^1.39
README
Overview
This package provides an easy to use Query Builder to filter, sort, search, and paginate Laravel models.
Usage
Install the package via composer:
composer require aw-studio/laravel-model-index
The model to which the index endpoint refers must have the following trait added:
class MyModel extends EloquentModel { use HasQueryIndex; }
Filtering
The Index Query Builder supports filtering from query parameters nearly out of the box. All you have to do is to configure which model attributes are filterable. This can be done when using the index in the controller:
public function index(Request $request){ MyModel::index() ->filterable(['name', 'age'] ->get(); }
Or if you'd like to resue the Index multiple times and always have the same filter options enabled, you may add a filterable
property or method to the Model which should return an array attribute names.
Filtering the index list is now as simple as adding the query parameter “filter” to the URL with the attribute name as the key and a value. For example:
http://localhost?filter[name]=John // or http://localhost?filter[age]=30
Advanced Filtering
For more sophisticated filters, you may use operators and logical operators in the query parameters. For example:
http://localhost?filter[age][$gte]=18&filter[age][$lte]=30
The following operators are supported:
$eq
- Equal$ne
- Not equal$gt
- Greater than$gte
- Greater than or equal$lt
- Less than$lte
- Less than or equal$in
- In$notIn
- Not in$contains
- Contains$notContains
- Not contains$between
- Between$startsWith
- Starts with$endsWith
- Ends with$null
- Null$notNull
- Not null
Logical operators can be used to combine filters. For example:
http://localhost?filter[$or][0][name][$contains]=John&filter[$or][1][name][$contains]=Doe
The following logical operators are supported:
$and
$or
Custom Filters
By default filter keys are supposed to match the column names of the model.
You can also define custom filter keys by using the filter
method on the Index query and define custom callbacks for the filter.
This also allows you to use model scopes for filtering or more complex queries e.g. in related models.
public function index(Request $request) { // http://localhost?filter[popular]=true return User::index() ->filter('popular', fn($query, $value) => $query->popular()) ->get(); // http://localhost?filer[user.name]=John return Post::index() ->filter('user.name', function ($query, $value) { $query->whereHas('user', fn($query) => $query->where('name', $value)); }) ->get(); }
Sorting
You can sort the index using query parameters. For example:
http://localhost?sort=name
You can also sort in descending order:
http://localhost?sort=-name // or http://localhost?sort=name:desc
Multiple columns can be sorted by separating them with a comma:
http://localhost?sort=name,-age
Searching
You can search the index using query parameters. For example:
http://localhost?search=John
This will search all configured columns for the term "John".
Configuring Searchable Columns
To configure which columns should be searchable, use the searchable
method on the
Index query:
public function index(Request $request) { return User::index() ->searchable(['name', 'email']) ->get(); }
Pagination
You can automatically paginate the index using query parameters by adding the page
query parameter to the URL or setting a per_page value in the query parameters. For example:
http://localhost?page=2 // or http://localhost?perPage=10
License
This project is licensed under the MIT License. See the LICENSE file for details.