Download the PHP package jerome/filterable without Composer

About Filterable

The Filterable package provides a robust, feature-rich solution for applying dynamic filters to Laravel's Eloquent queries. With a modular, trait-based architecture, it supports advanced features like intelligent caching, user-specific filtering, performance monitoring, memory management, and much more. It's suitable for applications of any scale, from simple blogs to complex enterprise-level data platforms.

Requirements

• PHP 8.2+
• Laravel 10.x, 11.x, or 12.x

Features

• Dynamic Filtering: Apply filters based on request parameters with ease
• Modular Architecture: Customize your filter implementation using traits
• Smart Caching: Both simple and intelligent caching strategies with automatic cache key generation
• User-Specific Filtering: Easily implement user-scoped filters
• Rate Limiting: Control filter complexity and prevent abuse
• Validation: Validate filter inputs before processing
• Permission Control: Apply permission-based access to specific filters
• Performance Monitoring: Track execution time and query performance
• Memory Management: Optimize memory usage for large datasets with lazy loading and chunking
• Query Optimization: Intelligent query building with column selection and relationship loading
• Logging: Comprehensive logging capabilities for debugging and monitoring
• Filter Chaining: Chain multiple filter operations with a fluent API
• Value Transformation: Transform input values before applying filters
• Custom Pre-Filters: Register filters to run before the main filters
• Comprehensive Debugging: Detailed debug information about applied filters and query execution
• Conditional Execution: Use Laravel's conditionable trait for conditional filter application
• Smart Error Handling: Graceful handling of filtering exceptions
• Flexible State Management: Monitor and manage the filter execution state
• Chainable Configuration: Fluent API for configuration with method chaining

Installation

To integrate the Filterable package into your Laravel project, install it via Composer:

The package automatically registers its service provider with Laravel's service container through auto-discovery (Laravel 5.5+).

For older Laravel versions, manually register the FilterableServiceProvider in your config/app.php file:

Usage

Creating a Filter Class

Create a new filter class using the Artisan command:

This command supports several options:

Examples:

The command generates a filter class in the app/Filters directory. Extend the base Filter class to implement your specific filtering logic:

Adding Custom Filters

To add a new filter, define a method within your filter class using camelCase naming, and register it in the $filters array:

Implementing the Filterable Trait and Interface

Apply the Filterable interface and trait to your Eloquent models:

Applying Filters

Basic usage:

In a controller:

Laravel 12 Support

For Laravel 12, which has moved to a more minimal initial setup, make sure to follow these additional steps:

1. Service Registration: If you're using a minimal Laravel 12 application, you may need to manually register the service provider in your bootstrap/providers.php file:

2. Invokable Controllers: If you're using Laravel 12's invokable controllers, here's how to apply filters:

3. Route Registration: Using the new routing style in Laravel 12:

Advanced Features

Feature Management

Selectively enable features for your filter:

Available Features

The Filterable package supports the following features that can be enabled or disabled:

Each feature can be enabled independently based on your specific needs:

User-Scoped Filtering

Apply filters that are specific to the authenticated user:

Pre-Filters

Apply pre-filters that run before the main filters:

Validation

Set validation rules for your filter inputs:

Permission Control

Define permission requirements for specific filters:

Rate Limiting

Control the complexity of filter requests:

Memory Management

Optimize memory usage for large datasets:

Query Optimization

Optimize database queries:

Caching

Configure caching behavior:

Logging

Configure and use logging:

Performance Monitoring

Track and analyze filter performance:

Filter Chaining

Chain multiple filter operations with a fluent API:

Value Transformation

Transform filter values before applying them:

Conditional Execution

Use Laravel's conditionable trait for conditional filter application:

State Management

Monitor and manage the filter execution state:

Debug Information

Get detailed information about the applied filters:

Error Handling

Customize exception handling for your filters:

Complete Example

Frontend Usage

Send filter parameters as query parameters:

Testing

Testing your filters using PHPUnit:

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Contributing

Contributions are welcome and greatly appreciated! If you have suggestions to make this package better, please fork the repository and create a pull request, or open an issue with the tag "enhancement".

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/amazing-feature)
3. Commit your Changes (git commit -m 'Add some amazing-feature')
4. Push to the Branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Authors

• [Jerome Thayananthajothy] - Initial work - Thavarshan

See also the list of contributors who participated in this project.

Acknowledgments

• Hat tip to Spatie for their query builder package, which inspired this project.