Download the PHP package firevel/filterable without Composer

Laravel Filterable

A lightweight trait for Laravel Eloquent models that makes it easy to build dynamic, type‐safe filters on your queries. Instead of hard‐coding dozens of scopes or query clauses, simply declare which fields are “filterable” and let the trait handle operators, casting, and relationship logic for you.

Table of Contents

1. Installation
2. Quick Start
3. Configuration
   • Defining $filterable
   • Allowed Filter Types
   • Supported Operators
   • Validating Columns
4. Basic Usage
   • Filtering by Single Field
   • Filtering by Multiple Fields
   • Composite (“Virtual”) Filters
5. Advanced Filters
   • Filtering JSON Columns
   • Filtering Relationships
   • Boolean & Null Checks
6. Examples
7. Tips & Best Practices
8. Troubleshooting

Installation

Install via Composer:

Once installed, there are no service‐provider registrations or config publishes required. The trait is ready to use.

Quick Start

1. Add the Filterable trait to your Eloquent model.
2. Define a protected $filterable array, mapping each filter key to its type.
3. Call the filter([...]) scope on your queries.

Now you can do:

––

Configuration

Defining $filterable

In each model that uses the trait, declare a protected $filterable array. The keys are the names (or aliases) you wish to filter on, and the values specify the field’s type. For example:

• If a key corresponds to an actual database column, use its column name.
• If you want “virtual” filters (e.g. full_name that searches both first_name and last_name), see the Composite (“Virtual”) Filters section.

The trait will only apply filters for keys explicitly declared in $filterable; any others are ignored by default (or throw an exception if you enable column validation).

Allowed Filter Types

Supported Operators

By default, the trait allows the following operators for each filter type. To override operators on a field, simply pass an associative array ('[ operator ] => [ value ]').

Note: If you supply a plain scalar (e.g. 'foo') instead of ['=' => 'foo'], the trait assumes the = operator by default.

Validating Columns

By default, the trait will ignore any filters whose key is not in $filterable. If you’d rather throw an exception when an unknown filter is passed, enable column validation:

With $validateColumns = true, passing ->filter(['not_a_column' => ['=' => 5]]) will throw:

Basic Usage

Filtering by Single Field

Filter on one attribute by providing a key‐value pair. If you omit the operator, it defaults to =.

Filtering by Multiple Fields

Combine as many filters as you need; they are joined with AND logic:

Composite (“Virtual”) Filters

Sometimes you want a single filter key (e.g. name) that actually applies to multiple columns (like first_name OR last_name). You can achieve this by declaring a “scope”-type entry in $filterable and then adding a local scope method on your model.

Example: “name” → searches first_name OR last_name

1. Declare a scope filter key
   In User.php:

2. Use it in your code exactly like any other filter

   Under the hood, the trait sees 'name' => 'scope' and calls $query->name('Smith'), which in turn applies:

Why use a “scope”-type filter?

• Zero changes to the trait: the existing code already checks if ($filterType === 'scope') and executes the corresponding local scope.
• Keeps your trait logic simple: you don’t have to override the trait’s internal validation or operator parsing—your scopeName() takes full responsibility for how the filter behaves.
• Reusable & readable: everyone knows that “scopeX” is a local query modifier, and the trait simply defers to it.

Advanced Filters

Filtering JSON Columns

If you have a JSON column (e.g. meta), you can:

• Filter by exact JSON key‐value:

• Filter by array contents (for JSON arrays) by using type array:

Filtering Relationships

If you want to filter on related models (e.g. User hasMany Order), declare the key as relationship in $filterable. Then pass either:

1. A scalar/array (for simple has() checks).
2. A nested filter array to apply conditions on the related model.

Tip: If you need a more complex subquery on the relationship, you can chain useRelationshipQuery() before calling filter().

Boolean & Null Checks

• Boolean

• IS NULL / IS NOT NULL
  For any type (integer, string, date, etc.), you can check nulls via is or not with the literal 'null':

Examples

Below are a few real‐world scenarios illustrating how you might combine filters.

Tips & Best Practices

• Keep $filterable up to date: Every column or relationship you wish to filter on must appear in the array.

• Use strict column validation in production:

  This prevents typos or malicious filters from silently being ignored.

• Leverage composite (virtual) filters sparingly: Only create a custom scope if you truly need to combine two or more columns into one semantic filter.
• Avoid leading wildcards unless necessary:
  • LIKE '%foo%' is flexible but slow on large tables. Whenever possible, use LIKE 'foo%' or full‐text search.
• Paginate filtered results: Filtering can return large result sets. Always pair with →paginate() or →simplePaginate() to avoid memory issues.
• Test your JSON and relationship filters thoroughly—wrong syntax or missing indexes can lead to unexpected results or performance hits.

Troubleshooting

• “Filter column ‘xyz’ is not allowed.”
  You enabled protected $validateColumns = true and passed a key not in $filterable. Either add it to the array or disable validation.

• Operator ‘in’ is not allowed for type ‘integer’
  Check your $filterable type for that key. The in operator only works on integer, id, string, or json—not on date/datetime out of the box.

• Composite filter not working
  If you declared a key as 'scope' in $filterable (for example, 'name' => 'scope'), make sure you have a corresponding scopeName() method on the model. If the trait can’t find scopeName, it will skip your filter.

• Slow queries on large tables
  • Check if you’re using %…% wildcards (leading %) on very large text columns—those can’t use indexes.
  • Consider adding a full‐text index for complex search scenarios or switch to a dedicated search engine (Scout, Algolia, MeiliSearch).

With this simple trait, you can keep your controllers and repositories neat, DRY, and expressive—no more copy/pasting dozens of if ($request->has('…')) { … } checks. Happy filtering!