Laravel Model Util

Laravel 常用模型工具集：封装一些常用、但 Laravel 本身没有或实现起来麻烦的能力，开箱即用。

特性

• 请求过滤器 QueryFilter：请求参数自动映射为 Eloquent 查询条件，支持操作符、&& / || 组合、排序、分页、时间范围、随机取 N 条及关联表过滤。
• 批量操作 BatchHelper：批量更新（CASE WHEN）、批量插入、批量插入或更新（upsert）、批量删除、批量软删除 / 恢复。
• 模型层工具：树形结构、排序重排、多语言字段、字段加解密 / 脱敏、操作审计、状态机、唯一编号生成。
• 通用辅助：统一 API 响应、防重复提交（幂等）、经纬度距离与附近查询、SQL 日志。
• 模型 Trait（UseFilter）：一行接入 ->filter() 作用域。

环境要求

• PHP >= 7.3
• Laravel 8.x ~ 12.x

安装

composer require lyn_huang/laravel-model-util

安装后 Laravel 会自动发现并注册 ModelUtilServiceProvider，无需手动配置。

配置（可选）

发布配置文件：

php artisan vendor:publish --tag=model-util-config

发布后生成 config/model_util.php，可配置多态关联映射、操作审计表名、SQL 日志等（各配置项详解见 安装与配置）。

不发布也能用——包内部已合并默认配置，config('model_util.*') 直接可读。使用操作审计（RecordsActivity）时还需 php artisan vendor:publish --tag=model-util-migrations。

快速上手

以请求过滤器为例，三步接入：

1. 新建过滤器类（方法名即请求参数名，可隐藏数据库真实字段名）：

<?php
// app/Filters/UserFilter.php
namespace App\Filters;

use LynHuang\LaravelModelUtil\Filter\QueryFilter;

class UserFilter extends QueryFilter
{
    // 请求参数 ?cname=黄 时触发
    public function cname($value)
    {
        // 真实字段为 name，默认使用 like 模糊匹配
        $this->analyzeParam('name', 'lk:' . $value);
    }
}

2. 在模型中接入 Trait（建议放在 BaseModel）：

<?php
// app/Models/BaseModel.php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use LynHuang\LaravelModelUtil\Traits\UseFilter;

class BaseModel extends Model
{
    use UseFilter;
}

3. 控制器中使用：

<?php
// app/Http/Controllers/UserController.php
namespace App\Http\Controllers;

use App\Filters\UserFilter;
use App\Models\User;
use Illuminate\Http\Request;

class UserController extends Controller
{
    public function index(Request $request)
    {
        // 传入 $request 自动读取全部请求参数（推荐，HTTP 场景）
        $filter = new UserFilter($request);
        // 等效 SQL: select * from users where name like '%黄%'
        return User::query()->filter($filter)->paginate($filter->getPerPage());
    }
}

QueryFilter 构造函数兼容两种传参：new UserFilter($request)（HTTP 场景，自动读取全部请求参数）或 new UserFilter(['cname' => '黄'])（数组，便于 CLI / 队列 / 手动指定参数）。

文档导航

License

MIT