PHPackages                             madong/query - 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. [Search & Filtering](/categories/search)
4. /
5. madong/query

ActiveLibrary[Search & Filtering](/categories/search)

madong/query
============

The Madong Query component - A powerful query parameter parsing and filtering library

1.0.1(4mo ago)0244Apache-2.0PHPPHP >=8.1

Since Mar 11Pushed 2mo agoCompare

[ Source](https://github.com/madong-code/query)[ Packagist](https://packagist.org/packages/madong/query)[ RSS](/packages/madong-query/feed)WikiDiscussions main Synced 1w ago

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

Madong Query
============

[](#madong-query)

一个强大的查询参数解析和过滤库，为 PHP 8.1+ 项目提供灵活、类型安全的查询构建能力。

✨ 特性
----

[](#-特性)

- 🚀 **高性能**: 轻量级设计，最小化性能开销
- 🔒 **类型安全**: 使用 PHP 8.1+ 枚举提供编译时类型检查
- 🎯 **灵活配置**: 支持多种查询模式和参数格式
- 🛠 **易于集成**: 提供多种集成方式（Trait、依赖注入、门面）
- 📝 **优雅 API**: 直观的接口设计，降低学习成本
- 🧪 **完整测试**: 全面的测试覆盖
- 📦 **零依赖**: 仅依赖 Illuminate 组件
- 🎛 **高度可配置**: SelectInput 支持字段过滤、格式限定、自定义返回格式等

📦 安装
----

[](#-安装)

通过 Composer 安装：

```
composer require madong/query
```

### 环境要求

[](#环境要求)

- PHP >= 8.1
- illuminate/database >= 11.0
- illuminate/pagination >= 11.0

🚀 快速开始
------

[](#-快速开始)

### 基本使用

[](#基本使用)

```
use madong\query\QueryParamsManager;

// 创建管理器实例
$manager = new QueryParamsManager();

// 应用查询参数
$query = $manager->apply(User::query(), [
    'filters' => [
        ['field' => 'name', 'operator' => 'like', 'value' => 'John'],
        ['field' => 'age', 'operator' => 'gt', 'value' => 18]
    ],
    'sort' => ['created_at' => 'desc'],
    'limit' => 20
]);

// 获取结果
$users = $query->get();
```

### 使用 Trait（推荐）

[](#使用-trait推荐)

在 Controller 中使用：

```
use madong\query\traits\WithQueryParams;

class UserController extends Controller
{
    use WithQueryParams;

    public function index(Request $request)
    {
        $params = $request->all();

        return $this->paginateWithParams(User::query(), $params, [
            'keyword_fields' => ['name', 'email']
        ]);
    }
}
```

### 使用门面（CLI 环境）

[](#使用门面cli-环境)

```
use madong\query\QueryFacade;

$result = QueryFacade::paginate(User::class, $params);
```

📖 核心概念
------

[](#-核心概念)

### 查询参数格式

[](#查询参数格式)

支持多种查询参数格式：

#### 1. 标准 filters 格式

[](#1-标准-filters-格式)

```
$params = [
    'filters' => [
        ['field' => 'name', 'operator' => 'like', 'value' => 'John'],
        ['field' => 'status', 'operator' => 'eq', 'value' => 'active']
    ]
];
```

#### 2. 大写前缀格式

[](#2-大写前缀格式)

```
$params = [
    'LIKE_name' => 'John',
    'EQ_status' => 'active'
];
```

#### 3. 数组格式

[](#3-数组格式)

```
$params = [
    ['name', 'like', 'John'],
    ['status', 'eq', 'active']
];
```

### 支持的操作符

[](#支持的操作符)

操作符说明示例`eq`等于`['field' => 'status', 'operator' => 'eq', 'value' => 'active']``ne`不等于`['field' => 'status', 'operator' => 'ne', 'value' => 'deleted']``gt`大于`['field' => 'age', 'operator' => 'gt', 'value' => 18]``gte`大于等于`['field' => 'age', 'operator' => 'gte', 'value' => 18]``lt`小于`['field' => 'age', 'operator' => 'lt', 'value' => 60]``lte`小于等于`['field' => 'age', 'operator' => 'lte', 'value' => 60]``like`模糊匹配`['field' => 'name', 'operator' => 'like', 'value' => 'John']``ilike`不区分大小写模糊匹配`['field' => 'name', 'operator' => 'ilike', 'value' => 'john']``in`包含`['field' => 'id', 'operator' => 'in', 'value' => [1, 2, 3]]``not_in`不包含`['field' => 'id', 'operator' => 'not_in', 'value' => [4, 5, 6]]``between`范围`['field' => 'price', 'operator' => 'between', 'value' => [10, 100]]``not_between`非范围`['field' => 'price', 'operator' => 'not_between', 'value' => [10, 100]]``null`为空`['field' => 'deleted_at', 'operator' => 'null']``not_null`不为空`['field' => 'deleted_at', 'operator' => 'not_null']`### 枚举类型

[](#枚举类型)

#### Operator 枚举

[](#operator-枚举)

```
use madong\query\enum\Operator;

$operator = Operator::LIKE;
echo $operator->value; // 输出: like
```

#### QueryMode 枚举

[](#querymode-枚举)

```
use madong\query\enum\QueryMode;

$mode = QueryMode::STANDARD; // 标准模式
$mode = QueryMode::STRICT;   // 严格模式
```

#### ParamFormat 枚举

[](#paramformat-枚举)

```
use madong\query\enum\ParamFormat;

$format = ParamFormat::FILTERS;   // 标准 filters 格式
$format = ParamFormat::UPPERCASE; // 大写前缀格式
$format = ParamFormat::ARRAY;     // 三元素数组格式
$format = ParamFormat::WHERE;     // 直接 where 条件格式
$format = ParamFormat::AUTO;      // 自动检测格式
```

🎯 高级用法
------

[](#-高级用法)

### 自定义查询选项

[](#自定义查询选项)

```
$manager->apply(User::query(), $params, [
    'allowed_fields' => ['name', 'email', 'status'],  // 允许查询的字段
    'keyword_fields' => ['name', 'email'],            // 关键词搜索字段
    'default_sort' => ['created_at' => 'desc'],       // 默认排序
    'default_page' => 1,                              // 默认页码
    'default_page_size' => 20,                        // 默认每页数量
    'max_page_size' => 100                            // 最大每页数量
]);
```

### 关键词搜索

[](#关键词搜索)

```
$params = [
    'keyword' => 'John',
    'keyword_fields' => ['name', 'email', 'phone']
];

// 自动在指定字段中进行模糊搜索
$users = $manager->all(User::query(), $params, [
    'keyword_fields' => ['name', 'email']
]);
```

### 分页查询

[](#分页查询)

```
$result = $manager->paginate(User::query(), [
    'filters' => [
        ['field' => 'status', 'operator' => 'eq', 'value' => 'active']
    ],
    'page' => 1,
    'page_size' => 20
], [
    'keyword_fields' => ['name', 'email']
]);

// 返回格式
[
    'data' => [...],           // 数据列表
    'total' => 100,            // 总数
    'page' => 1,               // 当前页
    'page_size' => 20,         // 每页数量
    'last_page' => 5           // 最后一页
]
```

### 排序

[](#排序)

```
$params = [
    'sort' => [
        'created_at' => 'desc',  // 降序
        'name' => 'asc'          // 升序
    ]
];
```

### 多层查询

[](#多层查询)

```
$params = [
    'filters' => [
        ['field' => 'status', 'operator' => 'eq', 'value' => 'active'],
        ['field' => 'age', 'operator' => 'gt', 'value' => 18],
        ['field' => 'name', 'operator' => 'like', 'value' => 'John']
    ]
];
```

🔧 集成方式
------

[](#-集成方式)

### 1. Controller 集成

[](#1-controller-集成)

```
use madong\query\traits\WithQueryParams;

class AdminController extends Controller
{
    use WithQueryParams;

    public function index(Request $request)
    {
        return $this->paginateWithParams(User::query(), $request->all(), [
            'keyword_fields' => ['name', 'email']
        ]);
    }
}
```

### 2. Service 集成

[](#2-service-集成)

```
use madong\query\traits\WithServiceQuery;

class UserService extends BaseService
{
    use WithServiceQuery;

    public function getList(array $params): array
    {
        return $this->paginateWithParams(User::query(), $params, [
            'allowed_fields' => ['name', 'email', 'status']
        ]);
    }
}
```

### 3. DAO 集成

[](#3-dao-集成)

```
use madong\query\traits\WithDaoQuery;

class UserDao extends BaseDao
{
    use WithDaoQuery;

    public function search(array $params): Collection
    {
        return $this->allWithParams($this->getModel(), $params);
    }
}
```

### 4. 依赖注入

[](#4-依赖注入)

```
use madong\query\QueryParamsManager;

class UserController extends Controller
{
    public function __construct(
        private QueryParamsManager $queryParams
    ) {}

    public function index(Request $request)
    {
        return $this->queryParams->paginate(User::query(), $request->all());
    }
}
```

### 5. SelectInput 集成（灵活参数解析）

[](#5-selectinput-集成灵活参数解析)

`WithSelectInput` Trait 提供高度可配置的参数解析功能，适用于需要精确控制的场景。

#### 基本使用

[](#基本使用-1)

```
use madong\query\traits\WithSelectInput;

class UserController extends Controller
{
    use WithSelectInput;

    public function index(Request $request)
    {
        // 使用默认配置，返回标准格式
        [$where, $format, $limit, $field, $order, $page] = $this->selectInput($request);

        // 查询数据
        $list = User::where($where)
            ->orderByRaw($order)
            ->paginate($limit, ['*'], 'page', $page);

        return response()->json($list);
    }
}
```

#### 自定义配置

[](#自定义配置)

```
use madong\query\traits\WithSelectInput;
use madong\query\QuerySelectConfig;

class UserController extends Controller
{
    use WithSelectInput;

    public function index(Request $request)
    {
        // 创建自定义配置
        $config = QuerySelectConfig::make([
            'allowed_fields' => ['name', 'email', 'status', 'created_at'],
            'skip_fields' => ['password', 'token', 'deleted_at'],
            'keyword_fields' => ['name', 'email'],
            'enable_keyword_search' => true,
            'sort_fields' => ['name', 'email', 'created_at'],
            'default_sort' => ['created_at' => 'desc'],
            'default_page_size' => 20,
            'max_page_size' => 100,
        ]);

        // 使用自定义配置
        $result = $this->selectInputWithConfig($request, $config);
        $where = $result['where'];
        $order = $result['order'];
        // ...
    }
}
```

#### 配置选项

[](#配置选项)

选项类型默认值说明`return_format``string``'array'`返回格式：`array`、`object`、`compact``param_format``string``'auto'`参数格式：`filters`、`uppercase`、`array`、`where`、`auto``allowed_fields``array|null``null`允许的字段白名单`skip_fields``array``[]`跳过的字段黑名单`sort_fields``array|null``null`允许排序的字段`default_sort``array``[]`默认排序规则`default_page_size``int``10`默认每页数量`max_page_size``int``100`最大每页数量`default_page``int``1`默认页码`keyword_fields``array``[]`关键词搜索字段`enable_keyword_search``bool``false`是否启用关键词搜索`keyword_param``string``'keyword'`关键词参数名`enable_range_query``bool``true`是否启用范围查询`enable_like_query``bool``true`是否启用模糊匹配`auto_convert_datetime``bool``true`是否自动转换日期时间`skip_empty_values``bool``true`是否跳过空值`debug_mode``bool``false`是否启用调试模式#### 在 Crud 中使用（推荐）

[](#在-crud-中使用推荐)

```
class UserController extends Crud
{
    // 类属性配置
    protected ?array $selectInputConfig = [
        'allowed_fields' => ['name', 'email', 'status'],
        'skip_fields' => ['password', 'token'],
        'sort_fields' => ['name', 'created_at'],
        'default_sort' => ['created_at' => 'desc'],
    ];

    public function index(Request $request)
    {
        // 自动使用类属性配置
        [$where, $format, $limit, $field, $order, $page] = $this->selectInput($request);
        // ...
    }

    public function search(Request $request)
    {
        // 临时传入配置，不影响其他方法
        [$where, $format, $limit, $field, $order, $page] = $this->selectInput($request, [
            'keyword_fields' => ['name', 'email'],
            'enable_keyword_search' => true,
        ]);
        // ...
    }
}
```

**配置优先级**：方法参数配置 > 类属性配置 > 默认配置

🛠️ 核心类
------

[](#️-核心类)

### QueryParamsManager

[](#queryparamsmanager)

查询参数管理器，提供统一的查询处理入口。

```
use madong\query\QueryParamsManager;

$manager = new QueryParamsManager();

// 应用查询参数
$query = $manager->apply($modelOrQuery, $params, $options);

// 解析查询参数
$parsed = $manager->parse($params);

// 分页查询
$result = $manager->paginate($modelOrQuery, $params, $options);

// 查询所有
$all = $manager->all($modelOrQuery, $params, $options);

// 查询第一条
$first = $manager->first($modelOrQuery, $params, $options);
```

### QueryCondition

[](#querycondition)

查询条件对象，封装单个查询条件。

```
use madong\query\QueryCondition;

$condition = new QueryCondition('name', 'like', 'John');
echo $condition->field;    // name
echo $condition->operator; // like
echo $condition->value;    // John

// 静态工厂方法
$condition = QueryCondition::eq('status', 'active');
$condition = QueryCondition::like('name', 'John');
$condition = QueryCondition::in('id', [1, 2, 3]);
```

### QueryParamParser

[](#queryparamparser)

查询参数解析器，支持多种参数格式。

```
use madong\query\QueryParamParser;

$parser = new QueryParamParser();

// 解析参数
$conditions = $parser->parse($params);
```

### QueryBuilderHelper

[](#querybuilderhelper)

查询构建器辅助类，应用查询条件到构建器。

```
use madong\query\QueryBuilderHelper;

$helper = new QueryBuilderHelper();

$query = $helper->apply($query, $params, $options);
```

### QueryParamConverter

[](#queryparamconverter)

参数转换器，转换不同格式的参数。

```
use madong\query\QueryParamConverter;

$converter = new QueryParamConverter();

// 转换为标准格式
$standard = $converter->toStandard($params);

// 转换为数组格式
$array = $converter->toArray($params);
```

### QueryFacade

[](#queryfacade)

门面类，提供静态访问接口（适用于 CLI 环境）。

```
use madong\query\QueryFacade;

$result = QueryFacade::paginate(User::class, $params);
```

🧪 异常处理
------

[](#-异常处理)

### QueryException

[](#queryexception)

基础查询异常。

```
use madong\query\exception\QueryException;

try {
    // 查询操作
} catch (QueryException $e) {
    // 处理异常
}
```

### QueryParseException

[](#queryparseexception)

查询参数解析异常。

```
use madong\query\exception\QueryParseException;

try {
    $manager->apply(User::query(), $params);
} catch (QueryParseException $e) {
    // 处理解析异常
}
```

📚 完整示例
------

[](#-完整示例)

### 用户管理接口

[](#用户管理接口)

```
namespace App\Http\Controllers;

use madong\query\traits\WithQueryParams;
use App\Models\User;

class UserController extends Controller
{
    use WithQueryParams;

    public function index(Request $request)
    {
        $params = $request->all();

        $options = [
            'allowed_fields' => ['name', 'email', 'status', 'created_at'],
            'keyword_fields' => ['name', 'email'],
            'default_sort' => ['created_at' => 'desc'],
            'default_page_size' => 20,
            'max_page_size' => 100
        ];

        return $this->paginateWithParams(User::query(), $params, $options);
    }

    public function show($id, Request $request)
    {
        $params = $request->all();

        return $this->firstWithParams(User::query(), array_merge($params, [
            'filters' => [['field' => 'id', 'operator' => 'eq', 'value' => $id]]
        ]));
    }
}
```

### 高级查询示例

[](#高级查询示例)

```
$params = [
    'filters' => [
        ['field' => 'status', 'operator' => 'eq', 'value' => 'active'],
        ['field' => 'age', 'operator' => 'between', 'value' => [18, 60]],
        ['field' => 'name', 'operator' => 'like', 'value' => 'John'],
        ['field' => 'created_at', 'operator' => 'gte', 'value' => '2024-01-01']
    ],
    'sort' => [
        'created_at' => 'desc',
        'name' => 'asc'
    ],
    'page' => 1,
    'page_size' => 20
];

$result = $manager->paginate(User::query(), $params);
```

### 关键词搜索示例

[](#关键词搜索示例)

```
$params = [
    'keyword' => 'John Doe',
    'keyword_fields' => ['name', 'email', 'phone']
];

$users = $manager->all(User::query(), $params, [
    'keyword_fields' => ['name', 'email', 'phone']
]);
```

🎨 最佳实践
------

[](#-最佳实践)

### 1. 使用 Trait 简化代码

[](#1-使用-trait-简化代码)

```
// 推荐
class UserController extends Controller
{
    use WithQueryParams;

    public function index(Request $request)
    {
        return $this->paginateWithParams(User::query(), $request->all());
    }
}

// 不推荐
class UserController extends Controller
{
    public function index(Request $request)
    {
        $manager = new QueryParamsManager();
        return $manager->paginate(User::query(), $request->all());
    }
}
```

### 2. 配置允许查询的字段

[](#2-配置允许查询的字段)

```
$options = [
    'allowed_fields' => ['name', 'email', 'status']  // 只允许这些字段
];
```

### 3. 设置分页限制

[](#3-设置分页限制)

```
$options = [
    'default_page_size' => 20,
    'max_page_size' => 100  // 防止查询过多数据
];
```

### 4. 使用关键词搜索

[](#4-使用关键词搜索)

```
$options = [
    'keyword_fields' => ['name', 'email']  // 指定搜索字段
];
```

🔒 安全建议
------

[](#-安全建议)

1. **限制允许查询的字段**: 使用 `allowed_fields` 选项
2. **设置分页上限**: 使用 `max_page_size` 选项
3. **验证输入数据**: 对用户输入进行验证
4. **使用参数绑定**: 底层自动使用参数绑定防止 SQL 注入

📄 许可证
-----

[](#-许可证)

Apache-2.0 License

👨‍💻 作者
------

[](#‍-作者)

Mr. April -

🌐 官方网站
------

[](#-官方网站)

🤝 贡献
----

[](#-贡献)

欢迎提交 Issue 和 Pull Request！

📞 支持
----

[](#-支持)

如有问题，请提交 Issue 或联系作者。

---

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance81

Actively maintained with recent releases

Popularity15

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity43

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

Unknown

Total

1

Last Release

149d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/5b3656311e70db387052470f1c0a1e818d6f8ebf5e9ad1dc32139adf94873926?d=identicon)[kzhzjdyw666](/maintainers/kzhzjdyw666)

---

Top Contributors

[![madong-code](https://avatars.githubusercontent.com/u/97489662?v=4)](https://github.com/madong-code "madong-code (2 commits)")

### Embed Badge

![Health badge](/badges/madong-query/health.svg)

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

###  Alternatives

[laravel/scout

Laravel Scout provides a driver based solution to searching your Eloquent models.

1.7k57.2M661](/packages/laravel-scout)[yajra/laravel-oci8

Oracle DB driver for Laravel via OCI8

8793.3M27](/packages/yajra-laravel-oci8)[laravel/cashier

Laravel Cashier provides an expressive, fluent interface to Stripe's subscription billing services.

2.5k30.2M156](/packages/laravel-cashier)[pressbooks/pressbooks

Pressbooks is an open source book publishing tool built on a WordPress multisite platform. Pressbooks outputs books in multiple formats, including PDF, EPUB, web, and a variety of XML flavours, using a theming/templating system, driven by CSS.

45844.8k1](/packages/pressbooks-pressbooks)[api-platform/laravel

API Platform support for Laravel

58174.6k18](/packages/api-platform-laravel)[psalm/plugin-laravel

Psalm plugin for Laravel

3355.4M352](/packages/psalm-plugin-laravel)

PHPackages © 2026

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