README

Laravel Filter Query

安装

composer require yoursjarvis/laravel-filter-query

可搜索特质

这是一个Laravel 9特质，它为使用它的模型添加了一个scopeSearch()方法。该scopeSearch()方法允许您根据提供的术语搜索数据库记录。

如何使用

1. 将可搜索特质添加到您的模型中

use YoursJarvis\FiltersQueryString\Searchable;

class MyModel extends Model
{
  use Searchable;

  protected $searchable = ['column_name_1', 'column_name_2'];
}

2. 在查询中使用scopeSearch()方法

<?php

namespace App\Http\Controllers\Api;

use App\Models\Test;
use Illuminate\Http\Request;

class MyController extends Controller
{
    public function index(Request $request)
    {
      if ($request->has('q')) {
        $data = MyModel::search($request->q);
      }

        $data->filters($request->filters);
        return response()->json(['data' => $data->get()], 200);
    }
}

这将返回所有包含搜索词example的记录，这些记录位于column_name_1或column_name_2列中。

查询约定

public_url/index?q=value_that_you_want_search

方法细节

scopeFilter(Builder $builder, array $search_terms = []): Builder scopeSearch()方法负责根据提供的搜索词搜索数据库记录。该方法接受两个参数

• $builder - 代表当前查询构建器实例的Illuminate\Database\Eloquent\Builder实例。
• $search_terms - 包含要使用的搜索词的关联数组。数组应包含一个键为search_term，值为搜索词。

该方法返回一个代表修改后的查询构建器实例的Illuminate\Database\Eloquent\Builder实例。

scopeSearch()方法遍历在$searchable属性中定义的每个列，并添加一个where或orWhere子句到查询构建器实例。如果过滤器包含点（.），则假定该过滤器是关系，并使用orWhereRelation()方法搜索相关表。否则，它将搜索当前表。

结论

可搜索特质是任何需要根据搜索词搜索特定记录的Laravel模型的实用补充。它提供了一种简单灵活的方式来根据任意数量的列过滤数据库记录，并且可以轻松定制以满足您的特定需求。

可过滤特质

可过滤特质是一个Laravel特质，它为使用它的模型添加了一个scopeFilters()方法。该scopeFilters()方法允许您根据提供的术语过滤数据库记录。

如何使用

1. 将可过滤特质添加到您的模型中

use Filterable;

class MyModel extends Model
{
    use Filterable;
}

1. 在控制器方法中使用scopeFilters()方法

<?php

namespace App\Http\Controllers\Api;

use App\Models\Test;
use Illuminate\Http\Request;

class MyController extends Controller
{
    public function index(Request $request)
    {
      if ($request->has('filters')) {
        $data = MyModel::filters($request->q);
      }

      return response()->json(['data' => $data->get()], 200);
    }
}

这将返回所有与过滤器查询中提供的过滤器标准匹配的记录。

查询约定

您只需使用以下约定在查询中传递可过滤字段和值

public_url/index?filters[0]=field,value
public_url/index?filters[0]=is_active,0

上述查询转换成Eloquent查询如下

MyModal::query()->where($column, '=', $value);

对于其他查询，请遵循以下提到的约定

between: public_url/index?filters[0]=field,value_value
not between: public_url/index?filters[0]=field,value!value
greater: public_url/index?filters[0]=field,>value
greater_or_equal: public_url/index?filters[0]=field,>=value
less: public_url/index?filters[0]field,<=value
less_or_equal: public_url/index?filters[0]field,<=value
with_trashed: public_url/index?filters[0] = trashed,only,
only_trashed: public_url/index?filters[0] = trashed,with

方法细节

scopeFilters(Builder $builder, $filter_terms): Builder scopeFilters()方法负责根据提供的过滤术语过滤数据库记录。该方法接受两个参数

• $builder - 代表当前查询构建器实例的Illuminate\Database\Eloquent\Builder实例。

• $filter_terms - 包含要使用的过滤术语的字符串数组。每个过滤术语应采用column_name, filter_value的格式。

该方法返回一个代表修改后的查询构建器实例的Illuminate\Database\Eloquent\Builder实例。

scopeFilters()方法遍历每个定义的过滤术语，并根据过滤值的格式向查询构建器实例添加过滤子句。过滤值可以是以下之一

• 简单的字符串值：该方法向查询构建器实例添加一个包含列名、过滤运算符和过滤值的where子句。

  • 查询示例：:- public_url/index?filters[0]=is_active,0

• 以>开头的字符串值：:- 方法向查询构建实例添加一个WHERE子句，包含列名和>运算符，后跟筛选值。

  • 查询示例：:- public_url/index?filters[0]=price,>1000

• 以>=开头的字符串值：:- 方法向查询构建实例添加一个WHERE子句，包含列名和>=运算符，后跟筛选值。

  • 查询示例：:- public_url/index?filters[0]=price,>=1000

• 以<开头的字符串值：:- 方法向查询构建实例添加一个WHERE子句，包含列名和<运算符，后跟筛选值。

  • 查询示例：:- public_url/index?filters[0]=price,<1000

• 以<=开头的字符串值：:- 方法向查询构建实例添加一个WHERE子句，包含列名和<=运算符，后跟筛选值。

  • 查询示例：:- public_url/index?filters[0]=price,<=1000

• 包含_的字符串值：:- 方法假设筛选值是范围，并向查询构建实例添加一个WHERE BETWEEN子句，包含列名和用下划线(_)分隔的范围值。

  • 查询示例：:- public_url/index?filters[0]=price,1000_2000

• 包含!的字符串值：:- 方法假设筛选值是范围，并向查询构建实例添加一个WHERE BETWEEN子句，包含列名和用感叹号(!)分隔的范围值。

  • 查询示例：:- public_url/index?filters[0]=price,4000!7000

• 值为trashed,only的字符串：:- 方法向查询构建实例添加一个onlyTrashed子句，以仅筛选软删除的记录。

  • 查询示例：:- public_url/index?filters[0]=trashed,only

• 值为trashed,with的字符串：:- 方法向查询构建实例添加一个withTrashed子句，以包含软删除的记录。

  • 查询示例：:- public_url/index?filters[0]=trashed,with

使用多个筛选器

public_url/index?filters[0]=price,>1000&filters[1]=status,paid,&filters[2]=is_active,0

结论

Filterable特性是任何需要根据特定筛选术语筛选数据库记录的Laravel 9模型的实用补充。它提供了一种简单灵活的方式来根据任何数量的列和筛选运算符筛选记录，并且可以轻松自定义以适应您的特定需求。

可排序特性

Sortable特性提供了一个作用域方法，可以用于根据一个或多个列对Eloquent查询结果进行排序。

用法

要使用sortable特性，您可以将它添加到Eloquent模型中，如下所示

use YoursJarvis\FiltersQuery\Sortable;

class MyModel extends Model
{
    use Sortable;

    // ...
}

一旦添加了特性，您就可以使用sortBy作用域方法来排序查询结果

<?php

namespace App\Http\Controllers\Api;

use App\Models\Test;
use Illuminate\Http\Request;

class MyController extends Controller
{
  public function index(Request $request)
  {
    $data = MyModel::sortBy($request->sort_by);

    return response()->json(['data' => $data->get()], 200);
  }
}

这将按提供的顺序对数据进行排序。

如果您在sortBy中不提供任何参数，则默认情况下结果将按模型的created_at列的降序排序。

查询约定

您只需使用以下约定在查询中传递可过滤字段和值

public_url/index?sort_by=price,desc

Use `sortBy` trait at the starting of your method and then perform your custom logic otherwise it's might over right your custom logic.