Download the PHP package ysm/filterable without Composer

YSM Filterable

The YSM\Filterable package provides a flexible and reusable way to filter Eloquent queries in Laravel applications. It allows developers to apply dynamic query filters based on HTTP request parameters, with support for whitelisting, blacklisting, aliases, and default values. This package is designed to keep filtering logic separate from controllers and models, promoting clean code and adherence to the Single Responsibility Principle.

Table of Contents

• Installation
• Configuration
• Usage
  • Basic Usage
  • Advanced Use Cases
  • Using Aliases
  • Auto-Applying Filters
  • Whitelisting and Blacklisting Filters
  • Setting Default Filter Values
  • Debugging Applied Filters
• Contributing
• License

Installation

1. Install the Package via Composer: Install the YSM\Filterable package using Composer:

2. Publish Configuration (Optional): If the package includes a configuration file, publish it to customize settings:

   Note: If no service provider exists, you can skip this step as the package is ready to use after installation.

3. Requirements:
   • PHP 8.0 or higher
   • Laravel 8.x or higher

Configuration

The YSM\Filterable package does not require additional configuration out of the box. It integrates seamlessly with Laravel's Eloquent ORM and HTTP request handling. To use it, you need to:

1. Create a filter class that extends YSM\Filterable\Filterable.
2. Apply the InteractWithFilterable trait to your Eloquent models.

Usage

Basic Usage

The package provides an abstract Filterable class and a trait InteractWithFilterable to apply filters to Eloquent queries.

Step 1: Add the Trait to Your Model

Add the InteractWithFilterable trait to your Eloquent model:

This adds a filterable scope to the Post model, allowing you to apply filters using either a Filterable instance or a filter class name as a string.

Step 2: Create a Filter Class

Create a filter class that extends YSM\Filterable\Filterable:

Step 3: Use in a Controller

Apply the filter in a controller. You can use the filter in two ways:

Method 1: Using Filter Instance

Method 2: Using Filter Class Name (String)

Note: When using a string class name, the filterable method will automatically resolve the filter from Laravel's service container and validate that it implements the Filterable interface.

When to Use Each Method:

• Filter Instance: Use when you need to add additional configuration to the filter instance (aliases, defaults, etc.) or override existing behavior before applying it.
• String Class Name: Use for simple and direct applying the filter without needing to add additional configuration.

Example Request:

Response:

Advanced Use Cases

Using Aliases

Map request parameters to filter methods using the aliases method:

Controller:

Request:

This applies the category filter using the cat request parameter.

Auto-Applying Filters

Automatically apply filters without requiring request parameters:

Controller:

This ensures all queries return only published posts unless overridden.

Whitelisting and Blacklisting Filters

Restrict which filters can or cannot be applied:

Controller:

Request:

The created_at filter will be ignored due to the blacklist.

Setting Default Filter Values

Provide default values for filters:

Controller:

Request:

This returns only published blog posts if no parameters are provided.

Debugging Applied Filters

Retrieve applied filters for debugging:

Response:

Contributing

Contributions are welcome! Please submit pull requests or issues to the GitHub repository. Ensure your code follows PSR-12 standards.

License

This package is open-sourced under the MIT License.