README

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:

composer require firevel/filterable

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.

// In app/Models/User.php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Firevel\Filterable\Filterable;

class User extends Model
{
    use Filterable;

    /**
     * Specify which fields (or “virtual” keys) can be filtered,
     * along with their data types.
     */
    protected $filterable = [
        'id'         => 'id',
        'first_name' => 'string',
        'last_name'  => 'string',
        'email'      => 'string',
        'created_at' => 'datetime',
    ];
}

Now you can do:

$users = User::filter([
    'first_name' => ['like' => '%Smith%'],
    'created_at' => ['>'    => '2023-01-01'],
])->get();

––

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:

protected $filterable = [
    'id'            => 'id',
    'first_name'    => 'string',
    'last_name'     => 'string',
    'email'         => 'string',
    'created_at'    => 'datetime',
    'is_active'     => 'boolean',
    'meta'          => 'json',
    'roles'         => 'relationship',
];

• 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.

Operator Aliases

To avoid using special characters in URLs, you can use text-based aliases for comparison operators:

• gt for > (greater than)
• gte for >= (greater than or equal)
• lt for < (less than)
• lte for <= (less than or equal)
• ne for <> (not equal)
• eq for = (equal)

These aliases work exactly the same as their symbolic counterparts:

// Using symbolic operators
$users = User::filter([ 'age' => ['>' => 25] ])->get();

// Using alias operators (URL-friendly)
$users = User::filter([ 'age' => ['gt' => 25] ])->get();

// Both produce: SELECT * FROM users WHERE age > 25

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:

class User extends Model
{
    use Filterable;

    protected $validateColumns = true;

    protected $filterable = [
        'id'       => 'id',
        'email'    => 'string',
        'status'   => 'string',
    ];
}

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

Exception: Filter column 'not_a_column' is not allowed.

Basic Usage

Filtering by Single Field

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

// 1) Simple equality (defaults to '=')
$users = User::filter([ 'id' => 5 ])->get();
// → SELECT * FROM users WHERE id = 5;

// 2) Explicit operators
$users = User::filter([ 'created_at' => ['>' => '2024-01-01'] ])->get();
// → SELECT * FROM users WHERE created_at > '2024-01-01';

// 3) LIKE operator for strings
$users = User::filter([ 'email' => ['like' => '%@example.com'] ])->get();
// → SELECT * FROM users WHERE email LIKE '%@example.com';

Filtering by Multiple Fields

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

$filters = [
    'first_name' => ['like' => '%John%'],
    'created_at' => ['>='   => '2025-01-01'],
    'status'     => ['='    => 'active'],
];

$users = User::filter($filters)->get();
// → SELECT * FROM users
//    WHERE first_name LIKE '%John%'
//      AND created_at >= '2025-01-01'
//      AND status = 'active';

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:

   use Illuminate\Database\Eloquent\Model;
   use Firevel\Filterable\Filterable;
   
   class User extends Model
   {
       use Filterable;
   
       protected $filterable = [
           'first_name' => 'string',
           'last_name'  => 'string',
           'email'      => 'string',
           'created_at' => 'datetime',
   
           // “name” isn’t a real column; mark it as a custom scope
           'name'       => 'scope',
       ];
   
       // Add a local scopeName() to combine first_name OR last_name
       // The second parameter ($allFilters) provides access to all filters
       public function scopeName($query, $value, $allFilters = [])
       {
           $query->where(function ($q) use ($value) {
               $q->where('first_name', 'like', "%{$value}%")
                 ->orWhere('last_name',  'like', "%{$value}%");
           });
       }
   }

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

   // Will invoke scopeName() internally
   $users = User::filter([
       'name'       => ['like' => 'Smith'], 
       'created_at' => ['>'    => '2025-01-01']
   ])->get();

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

   WHERE (first_name LIKE '%Smith%' OR last_name LIKE '%Smith%')
     AND created_at > '2025-01-01'

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.

Scope Method Naming Convention

The trait supports two naming conventions for scope methods and uses Laravel's Str::studly() for conversion:

1. Prefixed (recommended): scopeFilter{Name} — e.g., scopeFilterSearch for filter key search
2. Simple: scope{Name} — e.g., scopeSearch for filter key search

The prefixed convention is checked first and is recommended to avoid conflicts with reserved Laravel method names like query, where, get, etc.

// Recommended: use scopeFilter prefix to avoid conflicts
protected $filterable = [
    'query' => 'scope',  // Safe! Won't conflict with $query->query()
];

public function scopeFilterQuery($query, $value, $allFilters = [])
{
    // Your custom filter logic
}

// Also supported for backward compatibility
protected $filterable = [
    'name' => 'scope',
];

public function scopeName($query, $value, $allFilters = [])
{
    // Your custom filter logic
}

Filter names with underscores are converted using StudlyCase:

Note: dots are not converted the same way—Str::studly() only treats - and _ as word separators, so a key like user.role would studly-case to User.role (literal dot kept), which can never match a real PHP method name. Don't use dots in 'scope'-type filter keys; use underscores instead (e.g. user_role).

Accessing Other Filters in Scope Methods

Scope filter methods receive two parameters:

1. $value - The specific value for this filter
2. $allFilters - The complete array of all filters being applied

This allows you to create conditional logic based on other filters:

protected $filterable = [
    'search'     => 'scope',
    'category'   => 'string',
    'status'     => 'string',
];

public function scopeSearch($query, $value, $allFilters = [])
{
    $query->where(function ($q) use ($value, $allFilters) {
        $q->where('title', 'like', "%{$value}%")
          ->orWhere('description', 'like', "%{$value}%");

        // Apply different search logic if category filter is present
        if (isset($allFilters['category'])) {
            $q->orWhere('tags', 'like', "%{$value}%");
        }
    });
}

Advanced Filters

Filtering JSON Columns

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

• Filter by exact JSON key‐value:

  protected $filterable = [
      'meta' => 'json',
      // … other fields …
  ];

  // Get users whose JSON “meta->role” equals “admin”
  $users = User::filter([ 'meta->role' => ['=' => 'admin'] ])->get();
  // → SELECT * FROM users WHERE JSON_EXTRACT(meta, '$.role') = 'admin';

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

  protected $filterable = [
      'tags' => 'array', // assumes tags is a JSON array column
  ];

  // Check if JSON array contains a value using 'in' operator
  $users = User::filter([ 'tags' => ['in' => 'premium'] ])->get();
  // → SELECT * FROM users WHERE JSON_CONTAINS(tags, '"premium"');
  
  // Check if JSON array contains ANY of multiple values
  $users = User::filter([ 'tags' => ['in' => 'premium,vip'] ])->get();
  // → SELECT * FROM users WHERE (JSON_CONTAINS(tags, '"premium"') OR JSON_CONTAINS(tags, '"vip"'));
  
  // Exact match on the entire array using '=' operator
  $users = User::filter([ 'tags' => ['=' => '["premium","vip"]'] ])->get();
  // → SELECT * FROM users WHERE tags = '["premium","vip"]';

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.

// In User.php
protected $filterable = [
    'email'      => 'string',
    'orders'     => 'relationship',
];

// In Order.php (no special setup required)
class Order extends Model { /* … */ }

// 1) Just check that a user has at least one order:
$usersWithAnyOrder = User::filter([ 'orders' => ['>' => 0] ])->get();
// → SELECT * FROM users 
//    WHERE ( SELECT COUNT(*) FROM orders WHERE orders.user_id = users.id ) > 0;

// 2) Filter by a condition on the order itself:
$filters = [
    'orders.status' => ['=' => 'shipped'],
    'email'         => ['like' => '%@example.com'],
];
$users = User::filter($filters)->get();
// → SELECT * FROM users
//    WHERE EXISTS (
//      SELECT 1 FROM orders 
//       WHERE orders.user_id = users.id 
//         AND status = 'shipped'
//    ) 
//      AND email LIKE '%@example.com';

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

// Define a custom where clause for the related model
$relatedWhere = function ($query) {
    $query->where('price', '>', 100);
};

User::useRelationshipQuery($relatedWhere)
    ->filter([ 'orders' => ['in' => [1,2,3]] ])
    ->get();

For a relationship-type filter, in matches against the related model's primary key (so [1,2,3] above means "has an order whose id is 1, 2, or 3"), combined with the useRelationshipQuery() closure when one is set.

Boolean & Null Checks

• Boolean

  protected $filterable = [
      'is_active' => 'boolean',
  ];

  // Accepts true/false, "1"/"0", "true"/"false" (case insensitive)
  $activeUsers   = User::filter(['is_active' => ['=' => 'true']])->get();
  $inactiveUsers = User::filter(['is_active' => ['=' => '0']])->get();

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

  // Users with no email
  $usersNoEmail = User::filter([ 'email' => ['is' => 'null'] ])->get();
  
  // Users where deleted_at IS NOT NULL (soft‐deleted)
  $trashed = User::filter([ 'deleted_at' => ['not' => 'null'] ])->get();

Examples

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

// 1) Find all “admin” users created in the last 30 days,
//    whose email domain is “example.com” and have placed at least one “shipped” order.

$filters = [
    'role'       => ['='    => 'admin'],
    'created_at' => ['>='   => now()->subDays(30)->toDateString()],
    'email'      => ['like' => '%@example.com'],
    'orders.status' => ['=' => 'shipped'],
];

$admins = User::filter($filters)
    ->orderBy('created_at', 'desc')
    ->paginate(15);


// 2) Search by “full name” (composite filter: first_name OR last_name),
//    and also filter by a JSON metadata key:
$filters = [
    'name'           => ['like' => 'Doe'],         // see “Composite Filters”
    'meta->department'=> ['='  => 'engineering'],  // JSON column
    'status'         => ['='    => 'active'],
];

$users = User::filter($filters)->get();


// 3) Get all products whose "tags" JSON array includes "sale" or "new":
$filters = [
    'tags' => ['in' => 'sale,new'],  // checks if array contains any of these values
];

$productsOnSaleOrNew = Product::filter($filters)->get();

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:

  protected $validateColumns = true;

  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 ‘date’ (or boolean)
  Check your $filterable type for that key. The in operator only works on integer, id, float, string, json, array, and relationship—not on date/datetime/boolean 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 scopeFilterName() (recommended) or scopeName() method on the model. If neither method exists, the trait throws Scope method 'scopeFilterName' or 'scopeName' not found on model. rather than silently skipping the 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!