Download the PHP package devaction-labs/filterable-package without Composer

Filterable Package

A Laravel package for filterable traits and classes. This package provides powerful, dynamic query filtering capabilities directly from incoming requests, especially useful when developing flexible and dynamic APIs.

Features

• Easy Integration: Apply the Filterable trait to your Eloquent models.
• Flexible Filters: Exact, like, in, between, greater than (gte, gt), less than (lte, lt), JSON, and relationship filters.
• Dynamic Sorting: Customize sorting behavior directly from requests.
• Relationship Filters: Use advanced conditional logic like whereAny, whereAll, and whereNone for relational queries.
• JSON Support: Directly filter JSON columns with dot-notation.
• Performance Optimizations: Built-in caching and efficient query construction.
• Date Handling: Smart handling of date fields with Carbon integration.

Installation

Usage

Step 1: Add the Filterable Trait

Step 2: Applying Filters in Controllers

Available Filters

Direct Filters

• Exact Match: Filter::exact('status', 'status')
• LIKE Match: Filter::like('description', 'search')
• IN Clause: Filter::in('category_id', 'categories')
• Greater Than or Equal: Filter::gte('amount', 'min_amount')
• Less Than or Equal: Filter::lte('amount', 'max_amount')
• Between: Filter::between('created_at', 'date_range')

JSON Filters

• Exact Match: Filter::json('data', 'user.name', '=', 'user_name')
• LIKE Match: Filter::json('data', 'user.name', 'LIKE', 'user_name')

Relationship Filters

• Simple Relationship:

• Conditional Logic (whereAny, whereAll, whereNone):

Customizing Pagination and Sorting

Use the provided methods to paginate and sort easily:

• - (minus) prefix indicates descending sorting (e.g., -amount).

Defining Default Sorting and Allowed Sorts in Model:

Custom Filter Mapping

Easily map request parameters to database columns:

Now, using the parameter filter[display_name]=John will filter on the name column.

Advanced Features

Date Handling

The Filterable package provides sophisticated date handling capabilities:

You can also specify if you want to compare with the start or end of the day:

Custom LIKE Patterns

Customize the pattern used for LIKE filters to match your search requirements:

JSON Field Filtering with Database-Specific Optimizations

The package automatically applies the correct JSON extraction syntax based on your database:

Advanced Relationship Filtering with Conditional Logic

Apply complex conditions to your relationship filters:

Performance Optimizations

The Filterable trait includes several performance optimizations:

• Efficient caching of attribute and relationship validations
• Optimized handling of relationship filters
• Smart deduplication of eager-loaded relationships
• Specialized handling for simple equality relationship filters

These optimizations are automatically applied when you use the trait, ensuring your filterable queries remain performant even with complex filter combinations.

Complete Usage Example

Here's a comprehensive example showing how to use multiple features together:

Supported Databases for JSON Filters

• MySQL
• PostgreSQL
• SQLite

The package automatically detects the database driver from your configuration.

Testing

Contributing

Please see CONTRIBUTING.md for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• DevAction Labs
• All Contributors

License

The MIT License (MIT). Please see License File for more information.