Download the PHP package obrainwave/laravel-query-filters without Composer

Laravel Query Filters

A lightweight Laravel package for advanced Eloquent filtering, including global search, relationship filtering, operators, pagination, sorting, and custom filter classes.

Installation

Publish the config (optional):

Configuration

All defaults are in config/query-filters.php:

Basic Usage

You can filter Eloquent models directly using the filter() scope.

To use the query filters in your Laravel models, you must add the Filterable trait to the model. For example:

Once the trait is added, you can call the filter() method on your model statically:

• Without Filterable, filter() won’t exist on your model.
• You can optionally define $allowedFilters in the model or rely on the config for auto-generated filters. If your $allowedFilters is protected, you have to define a public get method to access it. For example:

If you know what you are doing, you can probably just leave $allowedFilters as public property

Or you can actually allow all table columns to be filtered by setting the default value in config/query-filters.php

And also supports laravel paginate and simplePaginate

URL Parameters

Filters also work directly from URL query parameters:

Which you can pass directly from your request helper or injected Illuminate\Http\Request

Using Laravel Query Methods

After applying filters with the package, you can continue to use all standard Laravel query builder and Eloquent methods. For example:

• ->get() → retrieves all matching records.
• ->paginate() → retrieves paginated results with page links.
• ->simplePaginate() → retrieves simpler pagination without total count.
• ->first() → retrieves the first matching record.

This allows you to combine filtering with any Laravel query workflow seamlessly.

Features

1. Global Search

Search across multiple columns using a single query parameter:

Customize global search columns in your model:

Or provide a method:

2. Allowed Filters

Only specified filters are applied:

You can also set global defaults in the config.

3. Operators

Filter with operators like gt, gte, lt, lte, between, and like:

4. Relationship Filtering

Filter nested relationships using dot notation:

• Use or: prefix for OR conditions.
• Supports arrays of values (multiple OR conditions).
• Supports operators (gt, lt, between, like).

It also supports relationship filtering and can accept arrays of values. This allows you to filter related models based on multiple possible values. For example:

5. Sorting

Sort using query string or programmatically:

• Prefix - for descending.
• Only columns defined in allowed_columns are applied.

6. Pagination

Pagination works out-of-the-box with per-page overrides:

OR

• per_page from URL has top priority.
• Config default is fallback.
• max_per_page is enforced.

7. Custom Filter Classes

If you need full control, generate a filter class and handle your custom logic in it:

The auto method automatically generates filters for your model. It uses either the model’s database columns or the columns you specify in the config, so you can quickly enable filtering without defining each field manually.

Example UserFilter:

Then use automatically by chaining your class method(s) to your model:

• Your filter class is detected by convention (UserFilter for User model).
• All features (pagination, sorting, relationships, operators) work seamlessly.
• Supports chaining:

8. Chaining

The filter returns a query builder proxy, so you can chain additional methods from your Custom Filter Class:

9. Case-insensitive Filtering

By default, filters are case-insensitive (exact or like) except when configured otherwise (strict).

10. Extending & Customization

• Override getAllowedFilters() in your model.
• Override getGlobalSearchKey() or $globalSearchKey in your model.
• Override getGlobalSearchColumns() or $globalSearchColumns.
• Define per-filter matching using filter_modes config.

Example: Full Feature Usage

Installation Notes

• Requires PHP 8+
• Supports Laravel 9, 10, 11, 12
• No additional dependencies for filtering.
• Works out-of-the-box with Eloquent models.

License

MIT License.

Contributing

We welcome contributions from everyone! If you have ideas, bug fixes, or improvements, feel free to open an issue or submit a pull request. Whether it’s enhancing filters, adding new features, or improving documentation, your contributions are highly appreciated.