Download the PHP package pradeepdev001/laravel-smart-filter without Composer

laravel-smart-filter

A powerful, elegant, and extensible Eloquent filtering package for Laravel 8, 9, 10, 11 & 12.

Stop writing repetitive when() chains. Let your URL do the talking.

Requirements

• PHP 8.1+
• Laravel 8, 9, 10, 11, or 12

Installation

The service provider and facade are registered automatically via Laravel's package discovery.

Publish the config (optional):

Quick Start

Add the Filterable trait to any Eloquent model:

Then in your controller:

Or chain on an existing query:

Filter Syntax

Equals

Not Equals

Comparisons

LIKE (contains)

IN / NOT IN

BETWEEN / NOT BETWEEN

NULL checks

Boolean

Sorting

Prefix with - for descending. Comma-separate for multiple columns.

Full-text Search

The fields searched are defined by $searchable on the model or searchable_fields in config.

Combining Filters

All filters are combined with AND logic. Mix freely:

Relationship Filtering

SmartFilter uses dot notation to filter across Eloquent relationships. No extra configuration needed — just use the relationship method name followed by the field you want to filter on.

Basic whereHas

Filter users who have at least one published post:

All Phase 1 operators work inside relationship filters:

Nested Relationships

Chain as many levels deep as you need:

Each dot segment is a relationship method name. The last segment is the field on the related model's table.

Many-to-Many

Works with BelongsToMany out of the box:

Existence Checks

Check whether a relationship exists or not, without filtering on a specific field:

Combining with Flat Filters

Relationship filters and flat filters compose naturally with AND logic:

Model Setup for Relationships

Define your Eloquent relationships as normal. No special configuration needed on the related model:

Note: The parent model's $filterable whitelist applies only to the parent's own columns. Fields inside a relationship subquery are validated independently, so posts.title will work even if title is not in the User model's $filterable.

Configuration

After publishing (vendor:publish --tag=smart-filter-config), config/smart-filter.php gives you global control:

Model-Level Configuration

Model properties always take precedence over global config:

Custom Operators

Implement OperatorContract and register it in a service provider:

Use it in the URL:

Or register via config:

Pagination

SmartFilter is fully compatible with all Eloquent pagination methods:

Testing Your Controllers

Pass a custom Request directly to smartFilter() to keep tests fast and HTTP-free:

Architecture

Data flow:

Roadmap

FAQ

Q: Does this prevent SQL injection?
A: Yes. All filter values are passed via PDO bound parameters through Eloquent. Field names are validated against an allow-list before interpolation. Input is additionally sanitised at parse time (null bytes and control characters stripped).

Q: Can I use this without the trait?
A: Yes. Resolve FilterBuilder from the container and call apply($builder, $collection) directly.

Q: What happens with unknown filter params?
A: By default they are silently skipped. Set $filterStrict = true on the model (or 'strict' => true in config) to throw InvalidFilterFieldException instead.

Q: Does the parent model's $filterable block relationship fields?
A: No. $filterable on the parent model only applies to the parent's own columns. Fields inside a relationship subquery (posts.title, company.city) use a permissive guard so they're never accidentally blocked by the parent's whitelist.

Q: Which relationship types are supported?
A: HasMany, BelongsTo, BelongsToMany, and HasOne. Any Eloquent relationship that supports whereHas works.

Q: Can I nest relationships more than one level?
A: Yes, unlimited depth. ?company.address.city=London works, as does ?org.department.team.lead_name=Alice.

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md. Please do not open public issues for vulnerabilities.

Changelog

See CHANGELOG.md.

License

MIT — see LICENSE.