PHPackages                             apielf/hyperf-query-builder - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. apielf/hyperf-query-builder

ActiveLibrary[API Development](/categories/api)

apielf/hyperf-query-builder
===========================

Build Hyperf database queries from API requests

6.3.1.3(9mo ago)0483—0%[2 issues](https://github.com/daixinguo/hyperf-query-builder/issues)MITPHPPHP >=8.1

Since Mar 17Pushed 9mo ago1 watchersCompare

[ Source](https://github.com/daixinguo/hyperf-query-builder)[ Packagist](https://packagist.org/packages/apielf/hyperf-query-builder)[ RSS](/packages/apielf-hyperf-query-builder/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (3)Dependencies (6)Versions (4)Used By (0)

Hyperf Query Builder
====================

[](#hyperf-query-builder)

基于 API 请求构建 Hyperf 数据库查询。这个包允许你基于请求过滤、排序和包含 Eloquent 关联。`QueryBuilder`继承了 Hyperf 的默认 Eloquent 构建器，这意味着你所有喜欢的方法和宏仍然可用。查询参数名称尽可能地遵循[JSON API 规范](http://jsonapi.org/)。

目录
--

[](#目录)

- [安装](#%E5%AE%89%E8%A3%85)
- [配置](#%E9%85%8D%E7%BD%AE)
- [基本用法](#%E5%9F%BA%E6%9C%AC%E7%94%A8%E6%B3%95)
- [过滤](#%E8%BF%87%E6%BB%A4)
    - [基本过滤](#%E5%9F%BA%E6%9C%AC%E8%BF%87%E6%BB%A4)
    - [精确过滤](#%E7%B2%BE%E7%A1%AE%E8%BF%87%E6%BB%A4)
    - [部分匹配过滤](#%E9%83%A8%E5%88%86%E5%8C%B9%E9%85%8D%E8%BF%87%E6%BB%A4)
    - [关联表过滤](#%E5%85%B3%E8%81%94%E8%A1%A8%E8%BF%87%E6%BB%A4)
    - [范围过滤](#%E8%8C%83%E5%9B%B4%E8%BF%87%E6%BB%A4)
    - [自定义过滤器](#%E8%87%AA%E5%AE%9A%E4%B9%89%E8%BF%87%E6%BB%A4%E5%99%A8)
    - [软删除过滤](#%E8%BD%AF%E5%88%A0%E9%99%A4%E8%BF%87%E6%BB%A4)
    - [默认过滤器](#%E9%BB%98%E8%AE%A4%E8%BF%87%E6%BB%A4%E5%99%A8)
    - [忽略特定值](#%E5%BF%BD%E7%95%A5%E7%89%B9%E5%AE%9A%E5%80%BC)
- [排序](#%E6%8E%92%E5%BA%8F)
    - [基本排序](#%E5%9F%BA%E6%9C%AC%E6%8E%92%E5%BA%8F)
    - [默认排序](#%E9%BB%98%E8%AE%A4%E6%8E%92%E5%BA%8F)
    - [自定义排序](#%E8%87%AA%E5%AE%9A%E4%B9%89%E6%8E%92%E5%BA%8F)
- [包含关联](#%E5%8C%85%E5%90%AB%E5%85%B3%E8%81%94)
    - [基本关联](#%E5%9F%BA%E6%9C%AC%E5%85%B3%E8%81%94)
    - [嵌套关联](#%E5%B5%8C%E5%A5%97%E5%85%B3%E8%81%94)
    - [关联计数](#%E5%85%B3%E8%81%94%E8%AE%A1%E6%95%B0)
    - [自定义关联](#%E8%87%AA%E5%AE%9A%E4%B9%89%E5%85%B3%E8%81%94)
- [选择字段](#%E9%80%89%E6%8B%A9%E5%AD%97%E6%AE%B5)
- [追加属性](#%E8%BF%BD%E5%8A%A0%E5%B1%9E%E6%80%A7)
- [分页](#%E5%88%86%E9%A1%B5)
- [高级用法](#%E9%AB%98%E7%BA%A7%E7%94%A8%E6%B3%95)
    - [与现有查询结合](#%E4%B8%8E%E7%8E%B0%E6%9C%89%E6%9F%A5%E8%AF%A2%E7%BB%93%E5%90%88)
    - [条件查询](#%E6%9D%A1%E4%BB%B6%E6%9F%A5%E8%AF%A2)
    - [异常处理](#%E5%BC%82%E5%B8%B8%E5%A4%84%E7%90%86)
- [最佳实践](#%E6%9C%80%E4%BD%B3%E5%AE%9E%E8%B7%B5)
- [致谢](#%E8%87%B4%E8%B0%A2)

安装
--

[](#安装)

你可以通过 composer 安装此包：

```
composer require apielf/hyperf-query-builder
```

发布配置文件：

```
php bin/hyperf.php vendor:publish apielf/hyperf-query-builder
```

配置
--

[](#配置)

配置文件位于`config/autoload/query-builder.php`，你可以在其中自定义查询参数名称：

```
return [
    /*
     * 默认查询参数名称
     */
    'parameters' => [
        'include' => 'include',
        'filter' => 'filter',
        'sort' => 'sort',
        'fields' => 'fields',
        'append' => 'append',
    ],

    /*
     * 是否禁用无效过滤器查询异常
     */
    'disable_invalid_filter_query_exception' => false,
];
```

基本用法
----

[](#基本用法)

### 基于请求过滤查询：`/users?filter[name]=John`

[](#基于请求过滤查询usersfilternamejohn)

```
use ApiElf\QueryBuilder\QueryBuilder;

$users = QueryBuilder::for(User::class)
    ->allowedFilters('name')
    ->get();

// 所有名称中包含"John"的`User`
```

### 基于请求包含关联：`/users?include=posts`

[](#基于请求包含关联usersincludeposts)

```
$users = QueryBuilder::for(User::class)
    ->allowedIncludes('posts')
    ->get();

// 所有`User`及其`posts`关联
```

### 基于请求排序查询：`/users?sort=id`

[](#基于请求排序查询userssortid)

```
$users = QueryBuilder::for(User::class)
    ->allowedSorts('id')
    ->get();

// 所有`User`按id升序排序
```

### 选择查询字段：`/users?fields[users]=id,email`

[](#选择查询字段usersfieldsusersidemail)

```
$users = QueryBuilder::for(User::class)
    ->allowedFields(['id', 'email'])
    ->get();

// 获取的`User`只会有id和email字段
```

过滤
--

[](#过滤)

### 基本过滤

[](#基本过滤)

默认情况下，`filter`参数将使用部分匹配（LIKE 查询）进行过滤：

```
// GET /users?filter[name]=John
$users = QueryBuilder::for(User::class)
    ->allowedFilters('name')
    ->get();

// 等同于 $query->where('name', 'LIKE', '%John%')
```

你可以指定多个允许的过滤器：

```
$users = QueryBuilder::for(User::class)
    ->allowedFilters('name', 'email', 'age')
    ->get();
```

### 精确过滤

[](#精确过滤)

如果你需要精确匹配而不是部分匹配，可以使用`exact`过滤器：

```
use ApiElf\QueryBuilder\AllowedFilter;

// GET /users?filter[email]=john@example.com
$users = QueryBuilder::for(User::class)
    ->allowedFilters(AllowedFilter::exact('email'))
    ->get();

// 等同于 $query->where('email', 'john@example.com')
```

### 开头匹配过滤

[](#开头匹配过滤)

使用`beginsWithStrict`过滤器进行以指定字符串开头的匹配：

```
// GET /users?filter[username]=admin
$users = QueryBuilder::for(User::class)
    ->allowedFilters(AllowedFilter::beginsWithStrict('username'))
    ->get();

// 等同于 $query->where('username', 'LIKE', 'admin%')
```

### 结尾匹配过滤

[](#结尾匹配过滤)

使用`endsWithStrict`过滤器进行以指定字符串结尾的匹配：

```
// GET /users?filter[email]=@company.com
$users = QueryBuilder::for(User::class)
    ->allowedFilters(AllowedFilter::endsWithStrict('email'))
    ->get();

// 等同于 $query->where('email', 'LIKE', '%@company.com')
```

### 操作符过滤

[](#操作符过滤)

使用`operator`过滤器支持各种比较操作符：

```
use ApiElf\QueryBuilder\Enums\FilterOperator;

// GET /users?filter[age]=25 (大于等于25)
$users = QueryBuilder::for(User::class)
    ->allowedFilters(
        AllowedFilter::operator('age', FilterOperator::GREATER_THAN_OR_EQUAL)
    )
    ->get();

// GET /users?filter[score]=100 (小于100)
$users = QueryBuilder::for(User::class)
    ->allowedFilters(
        AllowedFilter::operator('score', FilterOperator::LESS_THAN)
    )
    ->get();

// 支持的操作符：EQUAL, LESS_THAN, GREATER_THAN, LESS_THAN_OR_EQUAL, GREATER_THAN_OR_EQUAL, NOT_EQUAL
```

### BelongsTo 关联过滤

[](#belongsto-关联过滤)

使用`belongsTo`过滤器专门处理 BelongsTo 关联：

```
// GET /posts?filter[author]=1
$posts = QueryBuilder::for(Post::class)
    ->allowedFilters(AllowedFilter::belongsTo('author'))
    ->get();

// 自动处理外键关联
```

你也可以为过滤器指定一个内部名称，这在字段名称与过滤器名称不同时很有用：

```
// GET /users?filter[email_address]=john@example.com
$users = QueryBuilder::for(User::class)
    ->allowedFilters(AllowedFilter::exact('email_address', 'email'))
    ->get();

// 等同于 $query->where('email', 'john@example.com')
```

### 部分匹配过滤

[](#部分匹配过滤)

虽然默认过滤器已经是部分匹配，但你也可以显式使用`partial`过滤器：

```
// GET /users?filter[name]=John
$users = QueryBuilder::for(User::class)
    ->allowedFilters(AllowedFilter::partial('name'))
    ->get();

// 等同于 $query->where('name', 'LIKE', '%John%')
```

### 关联表过滤

[](#关联表过滤)

你可以使用点符号语法过滤关联表中的属性：

```
// 假设 User 模型有一个 posts 关联
// GET /users?filter[posts.title]=Hyperf
$users = QueryBuilder::for(User::class)
    ->allowedFilters('posts.title')
    ->get();

// 等同于
// $query->whereHas('posts', function ($query) {
//     $query->where('title', 'LIKE', '%Hyperf%');
// })
```

你也可以使用精确匹配过滤器：

```
// GET /users?filter[posts.id]=1
$users = QueryBuilder::for(User::class)
    ->allowedFilters(AllowedFilter::exact('posts.id'))
    ->get();
```

关联过滤功能支持多层嵌套关联：

```
// GET /users?filter[posts.comments.author.name]=John
$users = QueryBuilder::for(User::class)
    ->allowedFilters('posts.comments.author.name')
    ->get();
```

如果你不想允许关联过滤，可以在创建过滤器时禁用它：

```
$users = QueryBuilder::for(User::class)
    ->allowedFilters(
        AllowedFilter::exact('name', null, null, false, false)
    )
    ->get();
```

### 范围过滤

[](#范围过滤)

你可以使用模型上定义的查询范围进行过滤：

```
// 在User模型中定义范围
public function scopePopular($query)
{
    return $query->where('votes', '>', 100);
}

// GET /users?filter[popular]=true
$users = QueryBuilder::for(User::class)
    ->allowedFilters(AllowedFilter::scope('popular'))
    ->get();
```

### 自定义过滤器

[](#自定义过滤器)

你可以使用回调函数创建完全自定义的过滤器：

```
// GET /users?filter[name]=John
$users = QueryBuilder::for(User::class)
    ->allowedFilters(AllowedFilter::callback('name', function ($query, $value) {
        $query->where('first_name', 'LIKE', "%{$value}%")
              ->orWhere('last_name', 'LIKE', "%{$value}%");
    }))
    ->get();
```

### 软删除过滤

[](#软删除过滤)

如果你的模型使用了软删除，你可以使用`trashed`过滤器：

```
// GET /users?filter[trashed]=with
$users = QueryBuilder::for(User::class)
    ->allowedFilters(AllowedFilter::trashed())
    ->get();

// 可能的值:
// 'with': withTrashed()
// 'only': onlyTrashed()
// 'without': withoutTrashed()
```

### 默认过滤器

[](#默认过滤器)

你可以为过滤器设置默认值，当请求中没有提供该过滤器时使用：

```
// 当请求中没有filter[name]参数时，默认过滤name为'John'
$users = QueryBuilder::for(User::class)
    ->allowedFilters(AllowedFilter::partial('name')->default('John'))
    ->get();
```

### 忽略特定值

[](#忽略特定值)

你可以配置过滤器忽略特定值：

```
// 忽略空字符串和null值
$users = QueryBuilder::for(User::class)
    ->allowedFilters(AllowedFilter::exact('name')->ignore(['', null]))
    ->get();
```

排序
--

[](#排序)

### 基本排序

[](#基本排序)

你可以使用`sort`参数对结果进行排序：

```
// GET /users?sort=name
$users = QueryBuilder::for(User::class)
    ->allowedSorts('name')
    ->get();

// 升序排序

// GET /users?sort=-name
$users = QueryBuilder::for(User::class)
    ->allowedSorts('name')
    ->get();

// 降序排序（注意前缀'-'）
```

你可以指定多个允许的排序字段：

```
$users = QueryBuilder::for(User::class)
    ->allowedSorts('name', 'email', 'created_at')
    ->get();
```

### 默认排序

[](#默认排序)

当请求中没有指定排序参数时，你可以设置默认排序：

```
// 默认按创建时间降序排序
$users = QueryBuilder::for(User::class)
    ->allowedSorts('name', 'email', 'created_at')
    ->defaultSort('-created_at')
    ->get();
```

你也可以使用`AllowedSort`对象设置默认排序：

```
use ApiElf\QueryBuilder\AllowedSort;

// 默认按创建时间降序排序
$users = QueryBuilder::for(User::class)
    ->allowedSorts('name', 'email', 'created_at')
    ->defaultSort(
        AllowedSort::field('created_at')
            ->defaultDirection(AllowedSort::DESCENDING)
    )
    ->get();
```

你可以设置多个默认排序：

```
// 默认先按状态升序，再按创建时间降序排序
$users = QueryBuilder::for(User::class)
    ->allowedSorts('name', 'email', 'status', 'created_at')
    ->defaultSorts('status', '-created_at')
    ->get();
```

### 自定义排序

[](#自定义排序)

你可以使用自定义排序逻辑：

```
use ApiElf\QueryBuilder\AllowedSort;
use ApiElf\QueryBuilder\Sorts\Sort;

class RandomSort implements Sort
{
    public function __invoke(QueryBuilder $query, bool $descending, string $property)
    {
        $query->inRandomOrder();
    }
}

// GET /users?sort=random
$users = QueryBuilder::for(User::class)
    ->allowedSorts(AllowedSort::custom('random', new RandomSort()))
    ->get();
```

你也可以使用回调函数创建自定义排序：

```
use ApiElf\QueryBuilder\AllowedSort;

// GET /users?sort=full_name
$users = QueryBuilder::for(User::class)
    ->allowedSorts(
        AllowedSort::callback('full_name', function ($query, $descending, $property) {
            $direction = $descending ? 'desc' : 'asc';
            $query->orderBy('first_name', $direction)
                  ->orderBy('last_name', $direction);
        })
    )
    ->get();
```

包含关联
----

[](#包含关联)

### 基本关联

[](#基本关联)

你可以使用`include`参数加载关联：

```
// GET /users?include=posts
$users = QueryBuilder::for(User::class)
    ->allowedIncludes('posts')
    ->get();

// 等同于 $query->with('posts')
```

你可以指定多个允许的关联：

```
$users = QueryBuilder::for(User::class)
    ->allowedIncludes('posts', 'permissions', 'roles')
    ->get();
```

### 嵌套关联

[](#嵌套关联)

你可以使用点符号包含嵌套关联：

```
// GET /users?include=posts.comments
$users = QueryBuilder::for(User::class)
    ->allowedIncludes('posts.comments')
    ->get();

// 等同于 $query->with('posts.comments')
```

### 关联计数

[](#关联计数)

你可以使用`count`方法包含关联计数：

```
use ApiElf\QueryBuilder\AllowedInclude;

// GET /users?include=posts_count
$users = QueryBuilder::for(User::class)
    ->allowedIncludes(AllowedInclude::count('posts_count', 'posts'))
    ->get();

// 等同于 $query->withCount('posts')
```

### 自定义关联

[](#自定义关联)

你可以创建自定义的关联包含逻辑：

```
use ApiElf\QueryBuilder\AllowedInclude;
use ApiElf\QueryBuilder\Includes\IncludeInterface;

class LatestPostsInclude implements IncludeInterface
{
    public function __invoke(QueryBuilder $query)
    {
        $query->with(['posts' => function ($query) {
            $query->latest()->limit(5);
        }]);
    }
}

// GET /users?include=latest_posts
$users = QueryBuilder::for(User::class)
    ->allowedIncludes(AllowedInclude::custom('latest_posts', new LatestPostsInclude()))
    ->get();
```

选择字段
----

[](#选择字段)

你可以使用`fields`参数选择要返回的字段：

```
// GET /users?fields[users]=id,name,email
$users = QueryBuilder::for(User::class)
    ->allowedFields(['id', 'name', 'email'])
    ->get();

// 只返回id、name和email字段
```

你也可以为关联选择字段：

```
// GET /users?fields[users]=id,name&fields[posts]=title,content
$users = QueryBuilder::for(User::class)
    ->allowedFields(['id', 'name', 'posts.title', 'posts.content'])
    ->allowedIncludes('posts')
    ->get();
```

追加属性
----

[](#追加属性)

你可以使用`append`参数追加模型访问器：

```
// 在User模型中定义访问器
public function getFullNameAttribute()
{
    return $this->first_name . ' ' . $this->last_name;
}

// GET /users?append=full_name
$users = QueryBuilder::for(User::class)
    ->allowedAppends('full_name')
    ->get();
```

分页
--

[](#分页)

QueryBuilder 与 Hyperf 的分页功能完全兼容：

```
// GET /users?page=2&page_size=10
$users = QueryBuilder::for(User::class)
    ->paginate($request->input('page_size', 15));

// 或者使用简单分页
$users = QueryBuilder::for(User::class)
    ->simplePaginate($request->input('page_size', 15));
```

高级用法
----

[](#高级用法)

### 与现有查询结合

[](#与现有查询结合)

你可以将 QueryBuilder 与现有查询结合使用：

```
$query = User::where('active', true);

$users = QueryBuilder::for($query) // 从现有的Builder实例开始
    ->withTrashed() // 使用你现有的作用域
    ->allowedIncludes('posts', 'permissions')
    ->where('score', '>', 42) // 链接任何Hyperf查询构建器方法
    ->get();
```

### 条件查询

[](#条件查询)

你可以根据条件添加过滤器、排序和包含：

```
$users = QueryBuilder::for(User::class)
    ->when($request->has('filter_active'), function ($query) {
        $query->allowedFilters('active');
    })
    ->when($request->has('include_posts'), function ($query) {
        $query->allowedIncludes('posts');
    })
    ->get();
```

### 异常处理

[](#异常处理)

默认情况下，当请求包含未允许的过滤器、排序或包含时，QueryBuilder 会抛出异常。你可以在配置文件中禁用这些异常：

```
// config/autoload/query-builder.php
return [
    // ...
    'disable_invalid_filter_query_exception' => true,
];
```

或者你可以在运行时禁用它们：

```
$users = QueryBuilder::for(User::class)
    ->allowedFilters('name')
    ->allowedSorts('name')
    ->allowedIncludes('posts')
    ->disableInvalidFilterQuery()
    ->get();
```

最佳实践
----

[](#最佳实践)

### 在控制器中使用

[](#在控制器中使用)

```
class UserController extends AbstractController
{
    public function index()
    {
        return QueryBuilder::for(User::class)
            ->allowedFilters(['name', 'email', AllowedFilter::exact('type')])
            ->allowedSorts(['name', 'created_at'])
            ->allowedIncludes(['posts', 'permissions'])
            ->allowedFields(['id', 'name', 'email', 'created_at'])
            ->paginate()
            ->toArray();
    }
}
```

### 创建专用的查询构建器类

[](#创建专用的查询构建器类)

对于复杂的查询，你可以创建专用的查询构建器类：

```
class UserQueryBuilder extends QueryBuilder
{
    public function __construct()
    {
        parent::__construct(User::query());

        $this->allowedFilters(['name', 'email', AllowedFilter::exact('type')])
            ->allowedSorts(['name', 'created_at'])
            ->allowedIncludes(['posts', 'permissions'])
            ->allowedFields(['id', 'name', 'email', 'created_at']);
    }
}

// 在控制器中使用
public function index()
{
    return (new UserQueryBuilder())->paginate();
}
```

[所有功能未完全经过测试，如果遇到 bug 请到 github 中提交 issues](https://github.com/daixinguo/hyperf-query-builder)
----------------------------------------------------------------------------------------------

[](#所有功能未完全经过测试如果遇到-bug-请到-github-中提交-issues)

致谢
--

[](#致谢)

这个包是基于[spatie/laravel-query-builder](https://github.com/spatie/laravel-query-builder)改写的，感谢原作者的出色工作。

###  Health Score

34

—

LowBetter than 77% of packages

Maintenance57

Moderate activity, may be stable

Popularity16

Limited adoption so far

Community4

Small or concentrated contributor base

Maturity48

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~67 days

Total

3

Last Release

284d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/770af69c5a5c1e2dccf6c24d5c7999c1a771a92373707c41f8c3aa006301bab1?d=identicon)[daixinguo](/maintainers/daixinguo)

---

Tags

apiquerybuilderfiltersortincludehyperf

### Embed Badge

![Health badge](/badges/apielf-hyperf-query-builder/health.svg)

```
[![Health](https://phpackages.com/badges/apielf-hyperf-query-builder/health.svg)](https://phpackages.com/packages/apielf-hyperf-query-builder)
```

###  Alternatives

[joskolenberg/laravel-jory

Create a flexible API for your Laravel application using json based queries.

4513.5k](/packages/joskolenberg-laravel-jory)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)