Laravel宏是运行时向Macroable类动态注入方法的机制，不修改源码、不继承，依赖macro/macroStatic方法，需在类首次使用前注册，否则抛出BadMethodCallException。
为什么 Laravel 宏不是“装饰器”或“插件”，而是运行时注入方法
宏的本质是在运行时向已存在的类（如 Collection、Builder、Request）动态添加静态或实例方法，不修改源码、不继承、不重写。它依赖 Laravel 的 Macroable trait，该 trait 为类提供了 macro 和 macroStatic 方法。关键点是：宏只对实现了 Macroable 的类生效，且注册必须在类首次被使用前完成（通常放在 AppServiceProvider::boot() 中），否则会抛出 BadMethodCallException。
如何在 Collection 上定义并调用一个宏
最常用场景是对 Collection 扩展实用方法，比如加一个 countBy 统计字段频次：
use Illuminate\Support\Collection;
Collection::macro('countBy', function ($key) {
return $this->groupBy($key)->map(fn ($group) => $group->count());
});
之后即可直接调用：
$users = collect([
['name' => 'Alice', 'role' => 'admin'],
['name' => 'Bob', 'role' => 'user'],
['name' => 'Charlie', 'role' => 'admin'],
]);
$roles = $users->countBy('role'); // ['admin' => 2, 'user' => 1]
- 闭包里的
$this指向当前 Collection 实例（非静态宏） - 宏函数接收的参数从第二个开始（第一个隐式为
$this） - 不能访问私有/受保护属性，仅能通过公开 API 操作实例
Builder 宏怎么写？注意查询构造器的“延迟执行”特性
Builder 宏常用于封装复杂 where 逻辑，比如加一个 whereActive：
use Illuminate\Database\Eloquent\Builder;
Builder::macro('whereActive', function () {
return $this->where('active', true);
});
然后在模型中使用：
User::query()->whereActive()->get();
注意：宏返回的是 $this（即 Builder 实例），所以支持链式调用；但宏内部不能提前执行 get() 或 first()，否则会破坏链式行为。若需执行查询，应定义为静态宏或单独服务类。
宏的生命周期和常见陷阱
宏注册是一次性的，且在容器解析类之后注册会失效。典型错误包括：
- 在控制器里调用
Collection::macro(...)—— 此时Collection可能已被加载，宏无效 - 试图给未 use
Macroable的类（如普通 Model）加宏 —— 会报Call to undefined method macro() - 宏中引用了未在闭包里
use的外部变量（如$config），导致运行时报错 - 宏名与现有方法冲突（如叫
map），Laravel 不会覆盖原方法，而是静默忽略新宏
真正容易被忽略的是：宏无法被 IDE 自动补全，也不参与 PHPStan/PHPStorm 的静态分析，写完务必手动测试边界情况（空集合、null 字段、关联关系等）。
