README

Laravel Query Filter

Laravel query filter通过请求查询字符串提供了一种优雅的方式来过滤资源。您可以在查询字符串中指定条件来过滤eloquent模型和资源。

安装与使用

通过composer安装

composer require omalizadeh/laravel-query-filter

创建一个过滤器类

php artisan make:filter FilterClassName

在模型中添加特性

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasMany;
use Illuminate\Database\Eloquent\Relations\HasOne;
use Omalizadeh\QueryFilter\Traits\HasFilter;

class User extends Model
{
    use HasFilter;

    public function profile(): HasOne
    {
        return $this->hasOne(Profile::class);
    }

    public function posts(): HasMany
    {
        return $this->hasMany(Post::class);
    }
}

在过滤器类中设置可过滤的属性、关系和其他选项

<?php

namespace App\Filters;

use Omalizadeh\QueryFilter\ModelFilter;

class UserFilter extends ModelFilter
{
    protected function selectableAttributes(): array
    {
        return [
            'id',
            'phone'
        ];
    }

    protected function sortableAttributes(): array
    {
        return [
            'id',
            'created_at',
            'updated_at'
        ];
    }

    protected function summableAttributes(): array
    {
        return [
            'views'
        ];
    }

    protected function filterableAttributes(): array
    {
        return [
            'id',
            'phone',
            'is_active'
        ];
    }

    protected function filterableRelations(): array
    {
        return [
            'profile' => [
                'gender',
                'first_name'
            ],
            'posts' => [
                'post_body' => 'body'
            ]
        ];
    }

    protected function loadableRelations(): array
    {
        return [
            'profile'
        ];
    }
}

通过JSON格式的过滤器参数进行资源过滤，分页和排序作为查询字符串中的q发送

api/users?q={
    "page": {
        "limit": 20,
        "offset": 0
    },
    "sorts": [
        {
            "field": "id",
            "dir": "desc"
        }
    ],
    "filters": [
        [
            {
                "field": "is_active",
                "op": "=",
                "value": true
            }
        ]
    ],
    "sums": ["views"],
    "withs": ["profile"]
}

在控制器中

public function index(UserFilter $userFilter)
{
    $userFilterResult = User::filter($userFilter);
    
    // total resources count based on filters
    $count = $userFilterResult->count();
    
    // total sum of given attributes in filter if there is any
    $sums = $userFilterResult->sums();
    
    // Get query results as collection (paginated if there is pagination in filters)
    $users = $userFilterResult->data();
    
    // do stuff and return response
}

可用运算符

查询字符串格式

示例条件

(`is_active` = 1 OR `phone` like "%912%") AND (`first_name` like "%omid%")

那么JSON过滤器将是

{
    "page": {
        "limit": 20,
        "offset": 0
    },
    "sorts": [
        {
            "field": "id",
            "dir": "desc"
        }
    ],
    "filters": [
        [
            {
                "field": "is_active",
                "op": "=",
                "value": 1
            },
            {
                "field": "phone",
                "op": "like",
                "value": "912"
            }
        ],
        [
            {
                "field": "first_name",
                "op": "like",
                "value": "omid",
                "has": true
            }
        ]
    ]
}

许可证

Laravel Query Filter是开源软件，根据MIT许可证授权。