README

Filterable Package 是一个 Laravel 扩展包，旨在简化应用程序中对 Eloquent 模型的过滤。它提供了一个易于使用的接口来对 Eloquent 查询应用各种类型的过滤器，例如精确匹配、部分匹配（LIKE）、日期范围等，直接来自传入的请求。此扩展包对于构建需要动态过滤的 API 特别有用。

特性

• 易于集成：将 Filterable 特性应用于您的 Eloquent 模型以开始使用它。
• 多种过滤器：支持各种过滤器，如精确匹配、LIKE 搜索、大于、小于、IN 子句和日期范围。
• 自定义过滤器映射：轻松将请求参数映射到数据库中的不同列名。
• 灵活排序：允许根据请求参数动态排序结果。

安装

要安装此扩展包，请使用 Composer

composer require devaction-labs/filterable-package


## Usage

### Step 1: Apply the `Filterable` Trait to Your Model

Apply the `Filterable` trait to any Eloquent model you want to filter.

```php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use DevactionLabs\FilterablePackage\Traits\Filterable;

class Expense extends Model
{
    use Filterable;

    // Define any custom filter map or allowed sorts if necessary
    protected array $filterMap = [
        'name' => 'user_name', // Example: map 'name' request parameter to 'user_name' column
    ];

    protected array $allowedSorts = ['expense_date', 'amount']; // Example: allow sorting by these columns
}

步骤 2：在控制器中应用过滤器

使用由 Filterable 特性提供的 filtrable 范围在控制器方法中应用过滤器。

namespace App\Http\Controllers\Api\Finance;

use App\Http\Controllers\Controller;
use App\Http\Resources\ExpenseCollection;
use App\Models\Expense;
use DevactionLabs\FilterablePackage\Filter;

class ExpenseController extends Controller
{
    public function index(): ExpenseCollection
    {
        $expenses = Expense::query()
            ->with(['category', 'period'])
            ->filtrable([
                Filter::like('description', 'description'),
                Filter::exact('expense_date', 'expense_date'),
            ])
            ->orderBy('expense_date', 'desc')
            ->get();

        return new ExpenseCollection($expenses);
    }
}

可用过滤器

Filter::exact($attribute, $filterBy = null)

• 描述：过滤与提供的值完全匹配的列值。
• 示例： Filter::exact('status', 'status') 过滤与请求中 status 参数的值匹配的 status 列的记录。

Filter::like($attribute, $filterBy = null)

• 描述：过滤与提供的值相似的列值（使用 SQL LIKE）。
• 示例： Filter::like('name', 'search') 过滤包含请求中 search 参数值的 name 列的记录。

Filter::in($attribute, $filterBy = null)

• 描述：过滤列值在指定的值列表中的记录。
• 示例： Filter::in('category_id', 'categories') 过滤与请求中 categories 参数提供的任何值匹配的 category_id 列的记录。

Filter::gte($attribute, $filterBy = null)

• 描述：过滤列值大于或等于提供的值。
• 示例： Filter::gte('amount', 'min_amount') 过滤 amount 列大于或等于请求中 min_amount 参数值的记录。

Filter::lte($attribute, $filterBy = null)

• 描述：过滤列值小于或等于提供的值。
• 示例： Filter::lte('amount', 'max_amount') 过滤 amount 列小于或等于请求中 max_amount 参数值的记录。

自定义过滤器映射

您可以将请求参数映射到数据库中的不同列名。例如

protected array $filterMap = [
    'search' => 'description',
    'date' => 'expense_date',
];

现在，如果请求包含 filter[search]=Pizza，则查询将过滤 description 列以查找值 Pizza。

优势和差异化

• 增强代码可读性：以干净、可读的方式应用过滤器，而不会在控制器或模型中添加复杂的查询逻辑。
• 动态过滤：轻松处理单个请求中的多个过滤器，而无需手动解析输入。
• 可重用性：过滤器可以在不同的查询和模型之间重用，使您的代码更加简洁（DRY）。
• 灵活排序：允许根据请求参数动态排序结果，确保您的 API 能够满足客户端的需求。

在 API 控制器中的示例用法

public function index(): ExpenseCollection
{
    $expenses = Expense::query()
        ->with(['category', 'period'])
        ->filtrable([
            Filter::like('description', 'description'),
            Filter::exact('expense_date', 'expense_date'),
        ])
        ->orderBy('expense_date', 'desc')
        ->get();

    return new ExpenseCollection($expenses);
}

结论

《可筛选包》简化了在Laravel中筛选Eloquent模型的过程。通过利用这个包的强大功能，您可以在应用程序中创建高度灵活和动态的筛选解决方案，从而提高代码质量和可维护性。