可在 Laravel 中通过 Builder::macro() 为查询构造器动态添加可复用条件逻辑，支持在 AppServiceProvider、Tinker 或独立文件中注册，适配 Eloquent 和 Query Builder 两类实例，并天然支持链式调用。
如果您希望在 Laravel 框架中为查询构造器（Builder）动态添加可复用的条件逻辑，但又不希望每次重复编写 where 子句或封装成作用域（Scope），则可以利用 Laravel 提供的宏（Macro）机制对 Builder 类进行扩展。以下是实现此目标的具体操作步骤：
一、在服务提供者中注册 Builder 宏
Builder 宏需在应用启动早期注册，确保所有查询构造器实例（包括 Eloquent 和 Query Builder）均可识别该宏方法。注册位置必须为 AppServiceProvider 的 boot 方法，否则调用时会抛出 BadMethodCallException 异常。
1、打开 app/Providers/AppServiceProvider.php 文件。
2、在 boot 方法内部调用 Builder::macro()，传入宏名称与闭包函数。
3、闭包函数接收当前 Builder 实例作为第一个参数（即 $this），并可接受额外参数，返回 $this 以支持链式调用。
4、示例：注册一个名为 wherePublished 的宏，用于统一筛选已发布的记录：Builder::macro('wherePublished', function () { return $this->where('published', true); });
二、使用 Tinker 临时注册 Builder 宏
该方式适用于开发调试或快速验证宏逻辑是否符合预期，无需修改项目文件，注册后立即生效，但仅在当前 Tinker 会话中存在。
1、在终端执行 php artisan tinker 命令进入交互环境。
2、输入以下语句注册宏：use Illuminate\Database\Eloquent\Builder; Builder::macro('whereActiveYear', function ($year) { return $this->whereYear('created_at', $year); });
3、在模型上测试调用：$users = App\Models\User::query()->whereActiveYear(2026)->get();
4、确认结果是否正确返回创建于 2026 年的用户记录。
三、通过独立宏文件集中管理 Builder 宏
当项目中 Builder 宏数量增多时，将全部定义提取至单独文件可显著提升组织性与可维护性，避免 AppServiceProvider::boot() 方法臃肿，并便于团队协作与版本控制。
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
1、新建文件 app/Macros/BuilderMacros.php。
2、在该文件中逐条注册多个职责单一的宏，例如：Builder::macro('whereNotSoftDeleted', function () { return $this->whereNull('deleted_at'); });
3、在 AppServiceProvider 的 boot 方法中引入该文件：require_once app_path('Macros/BuilderMacros.php');
4、确保该文件无命名空间声明、无类定义，仅含 Builder::macro() 调用语句，且不包含任何 echo 或输出语句。
四、在 Eloquent 模型查询中调用 Builder 宏
宏注册完成后，所有通过 query()、newQuery() 或直接使用模型静态方法（如 User::where()）生成的 Builder 实例均可调用宏，语法与原生方法完全一致，且天然支持链式调用。
1、在控制器中创建基础查询：$query = App\Models\Post::query();
2、连续调用多个已注册宏：$posts = $query->wherePublished()->whereActiveYear(2026)->orderBy('created_at', 'desc')->get();
3、验证最终 SQL 是否包含对应 WHERE 条件，且结果集符合业务预期。
五、为不同 Builder 类型分别注册宏
Laravel 中存在两类 Builder：Eloquent Builder（Illuminate\Database\Eloquent\Builder）和 Query Builder（Illuminate\Database\Query\Builder）。二者均实现 Macroable，但注册宏时需明确指定目标类，否则可能因类型不匹配导致宏不可见。
1、为 Eloquent Builder 注册特有宏（如作用于模型关系）：use Illuminate\Database\Eloquent\Builder; Builder::macro('withTrashedIfAdmin', function () { if (auth()->check() && auth()->user()->is_admin) { return $this->withTrashed(); } return $this; });
2、为 Query Builder 注册底层 SQL 相关宏（如原生表达式封装）：use Illuminate\Database\Query\Builder; Builder::macro('whereJsonContainsAny', function ($column, array $values) { foreach ($values as $value) { $this->orWhereRaw("JSON_CONTAINS({$column}, ?)", [$value]); } return $this; });
3、在实际查询中区分调用：Eloquent 查询走 Eloquent Builder 宏，DB::table() 查询走 Query Builder 宏。
