PHPackages                             mitoop/laravel-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. [Database & ORM](/categories/database)
4. /
5. mitoop/laravel-query-builder

ActiveLibrary[Database & ORM](/categories/database)

mitoop/laravel-query-builder
============================

v2.11.0(3mo ago)3131MITPHP

Since May 10Pushed 3mo ago2 watchersCompare

[ Source](https://github.com/mitoop/laravel-query-builder)[ Packagist](https://packagist.org/packages/mitoop/laravel-query-builder)[ RSS](/packages/mitoop-laravel-query-builder/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (2)Versions (19)Used By (0)

Laravel Query Builder
=====================

[](#laravel-query-builder)

**Laravel Query Builder** 是一个基于接口设计、具备高扩展性的渐进式搜索构建包，旨在让 Laravel 中的复杂搜索变得**更简单、更清晰、更优雅**。

它将搜索逻辑从控制器中彻底解耦，使列表搜索功能的开发更加集中、可维护，同时支持高度复用和灵活扩展。

本包的设计灵感来源于 [zhuzhichao/laravel-advanced-search](https://github.com/matrix-lab/laravel-advanced-search) 和 [spatie/laravel-query-builder](https://github.com/spatie/laravel-query-builder)，并结合实际业务需求进行了增强与重构。

---

特性
--

[](#特性)

- **DSL 搜索规则**：集中定义搜索逻辑，支持声明式、结构化、可复用的规则。
- **支持排序与分页**：可自定义排序字段，兼容 `paginate()`、`get()` 等链式调用。
- **值处理器(ValueResolver)**：统一处理输入值转换，避免重复闭包。
- **字段类型灵活**：支持 JSON 字段、关联字段、表别名字段。
- **高级扩展**：支持原生 SQL、闭包、自定义操作符、模型 Scope。
- **接口驱动**：几乎所有功能可通过自定义类替换，实现高度扩展。

---

环境需求
----

[](#环境需求)

- PHP >= 8.2
- Laravel ^11.0 | ^12.0

---

安装
--

[](#安装)

```
composer require mitoop/laravel-query-builder
```

---

快速上手
----

[](#快速上手)

### 创建 Filter 类

[](#创建-filter-类)

Filter 类用于集中定义搜索逻辑，可通过 Artisan 快速生成：

```
php artisan make:filter UserFilter
```

```
class UserFilter extends AbstractFilter
{
    protected array $allowedSorts = ['id'];

    protected function rules(): array
    {
        return [];
    }
}
```

调用示例：

```
$users = User::filter(UserFilter::class)->paginate();
```

返回的是原生 Eloquent 查询构建器，仍支持链式调用 `with()`、`paginate()`、`get()` 等。

---

DSL 搜索规则
--------

[](#dsl-搜索规则)

### 传统写法（控制器硬编码）

[](#传统写法控制器硬编码)

```
if ($request->filled('name')) {
    $query->where('name', $request->input('name'));
}
if ($request->filled('email')) {
    $query->where('email', 'like', '%'.$request->input('email').'%');
}
```

### 使用 DSL（集中在 Filter 中）

[](#使用-dsl集中在-filter-中)

```
protected function rules(): array
{
    return [
        'name',
        'email|like' => new Like,
    ];
}
```

### DSL 优势

[](#dsl-优势)

- **集中管理**：所有规则在 `rules()` 中定义，控制器无需关心细节。
- **结构化**：清晰、易于阅读和维护。
- **高复用**：支持自定义操作符和值处理器，可在多个 Filter 中复用。
- **可扩展**：轻松支持 JSON、关联字段、模型 Scope 等复杂查询。

---

### 规则格式

[](#规则格式)

```
[前端字段名]:[数据库字段]|[操作符]

```

- 冒号用于前端字段与数据库字段映射（可选）
- 竖线用于指定操作符（可选）
- 支持索引数组、关联数组混合定义

示例：

```
protected function rules(): array
{
    return [
        'name', // 默认 eq
        'email|like' => $this->value('email', fn($email)=> "%{$email}%"),
        'created_at|between' => new DateRange,
        'nickname:profile->nickname|like' => new Like,
        'position$name|like' => new Like,
    ];
}
```

---

### 支持的操作符

[](#支持的操作符)

- 基础：`eq`, `ne`, `gt`, `lt`, `gte`, `lte`, `like`, `in`, `not_in`, `between`, `is_null`, `not_null`
- JSON：`json_contains`
- 自定义操作符：在 `AppServiceProvider` 注册

```
app(OperatorFactoryInterface::class)->register('new_operator', fn($app) => new NewOperator);
```

---

### 值处理器 ValueResolver

[](#值处理器-valueresolver)

用于统一处理输入值，例如模糊搜索或日期范围：

```
class Like implements ValueResolver
{
    public function __construct(protected string $prefix = '%', protected string $suffix = '%') {}

    public function resolve($value): string
    {
        return $this->prefix.$value.$this->suffix;
    }
}

class DateRange implements ValueResolver
{
    public function resolve($value): ?array
    {
        if (! is_array($value) || count($value) !== 2) return null;

        try {
            [$start, $end] = $value;
            $start = Carbon::parse($start)->startOfDay();
            $end = Carbon::parse($end)->endOfDay();
        } catch (Throwable) {
            return null;
        }

        return [$start, $end];
    }
}
```

使用示例：

```
protected function rules(): array
{
    return [
        'email|like' => new Like,
        'created_at|between' => new DateRange,
    ];
}
```

> 如果前端传入值为 `null` 或空数组，该规则会自动跳过，避免无效查询。

---

### 高级规则支持

[](#高级规则支持)

- **原生 SQL**：`DB::raw(...)`
- **闭包查询**：

```
function (Builder $builder) {
    $builder->where('is_verified', true);
}
```

- **模型 Scope**：支持 `scopeXxx()` 或 `#[Scope]` 注解
- **关键词搜索**：

```
$this->whenValue('keyword', function(Builder $builder, $keyword) {
    $builder->whereAny(['name', 'email'], 'like', "%{$keyword}%");
});
```

---

### 排序：sorts 方法

[](#排序sorts-方法)

默认通过请求参数 `sorts` 提取排序条件，例如：

```
sorts=-id,name

```

- 字段前加 `-` 表示降序，其他为升序
- 可通过 `$allowedSorts` 限制允许排序字段

```
protected array $allowedSorts = ['id', 'name', 'created_at'];
```

- 自定义请求参数：

```
SortResolver::sortFieldUsing('order_by');
```

- 完全自定义排序：

```
protected function sorts(): array
{
    return [
        'id' => 'desc',
        'created_at asc',
    ];
}
```

---

### 生命周期钩子

[](#生命周期钩子)

- **booting()**：执行构建逻辑前调用，适合设置默认参数

```
public function booting(): void
{
    $this->data['status'] ??= 'active';
}
```

- **boot()**：构建逻辑正式开始前调用，适合动态注册过滤器或修改行为

```
public function boot(): void
{
    if (method_exists($this, 'with')) {
        $this->builder->with($this->with());
    }
}
```

---

### 完整示例：UserFilter

[](#完整示例userfilter)

```
use Mitoop\LaravelQueryBuilder\Filters\AbstractFilter;
use Mitoop\LaravelQueryBuilder\Operators\Like;

class UserFilter extends AbstractFilter
{
    protected array $allowedSorts = ['id', 'created_at'];

    protected function rules(): array
    {
        return [
            'id',
            'name|like'  => new Like,
            'email|like' => new Like,
            'status|in',
            'created_from:created_at|gte',
            'created_to:created_at|lte',
            'created_at|between' => new DateRange,
            'nickname:profile->nickname|like' => new Like,
            'tag:profile->tags|json_contains',
            'position$name|like' => new Like,
            'u.name',
            new Scope('active'),
            $this->whenValue('keyword', function (Builder $builder, $keyword) {
                $builder->whereAny(['name', 'email'], 'like', "%{$keyword}%");
            }),
            'keyword|like_any' => new LikeAny(['name', 'email']),
            DB::raw('users.score > 100'),
            function (Builder $builder) {
                $builder->where('is_verified', true);
            },
        ];
    }
}
```

控制器使用：

```
$users = User::filter(UserFilter::class)->paginate();
```

---

贡献
--

[](#贡献)

有什么新的想法和建议，欢迎提交 [issue](https://github.com/mitoop/laravel-query-builder/issues) 或 [Pull Requests](https://github.com/mitoop/laravel-query-builder/pulls)。

---

协议
--

[](#协议)

MIT

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance82

Actively maintained with recent releases

Popularity16

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

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 ~19 days

Recently: every ~47 days

Total

18

Last Release

93d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/1645a978f51dcbbc8e50a17bf7daaa12fd1b01a4b19784d0010325d78c9b53f8?d=identicon)[Mitoop](/maintainers/Mitoop)

---

Top Contributors

[![mitoop](https://avatars.githubusercontent.com/u/7368344?v=4)](https://github.com/mitoop "mitoop (84 commits)")

---

Tags

laravelquery

### Embed Badge

![Health badge](/badges/mitoop-laravel-query-builder/health.svg)

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

###  Alternatives

[anourvalar/eloquent-serialize

Laravel Query Builder (Eloquent) serialization

11223.5M33](/packages/anourvalar-eloquent-serialize)[statamic-rad-pack/runway

Eloquently manage your database models in Statamic.

135224.7k7](/packages/statamic-rad-pack-runway)[api-platform/laravel

API Platform support for Laravel

58171.5k14](/packages/api-platform-laravel)[duncanmcclean/statamic-cargo

Comprehensive e-commerce addon for Statamic. Build bespoke e-commerce sites without the complexity.

3416.9k](/packages/duncanmcclean-statamic-cargo)

PHPackages © 2026

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