只有继承 macroable trait 的类才支持 macro，如 Collection、builder、request、response、str、arr；controller、model、app 门面等不支持。
Macro 不是“动态添加方法”的通用方案，而是 laravel 内部为特定类（如 Collection、Builder、Request）预留的扩展机制；直接对 IlluminateSupportFacadesLaravel 或任意类调用 macro 会报错。
哪些类真正支持 Macro？
Laravel 只有继承了 Macroable trait 的类才支持。常见支持类包括：Collection、Builder（Eloquent 和 Query Builder）、Request、Response、Str、Arr。不支持的典型例子：任何 Controller、Model（除非手动 use Macroable）、App 门面、Laravel 门面本身。
验证方式很简单：查该类源码是否包含 use IlluminateSupportTraitsMacroable;。
- 错误写法：
App::macro('foo', ...)→ 报Call to undefined method IlluminateFoundationApplication::macro() - 正确写法：
Collection::macro('sumOfSquares', function () { return $this->sum(fn($x) => $x ** 2); }); - 别名类（如
DB）不支持 macro；但它的底层Builder实例支持（需在查询链中调用）
Macro 注册时机和位置很关键
必须在应用启动早期注册（比如 AppServiceProvider::boot()），且不能晚于首次使用目标类的实例。否则宏函数不会生效——因为 Macroable 是静态属性，初始化后才可写入。
- 注册太晚（例如在某个 Controller 里调用
Collection::macro()）→ 宏不可见，调用时报Method does not exist - 推荐位置：
app/Providers/AppServiceProvider.php的boot()方法中集中注册 - 如果宏只在测试中用，可放在
tests/TestCase.php的setUp()里，但注意每次 test 都重注册 - 不建议在配置文件或
config/app.php中注册宏——那里不是运行时上下文
闭包里的 $this 指向什么？
Macro 闭包中的 $this 是调用该宏的实例本身，类型取决于你注册在哪个类上。这是最容易混淆的点。
- 注册在
Collection::macro()上 →$this是IlluminateSupportCollection实例 - 注册在
Builder::macro()上 →$this是IlluminatedatabaseEloquentBuilder或IlluminateDatabaseQueryBuilder实例 - 注册在
Str::macro()上 →$this是IlluminateSupportStr类（静态调用，所以$this实际是Static，但闭包内仍可访问静态方法） - 错误假设：
Collection::macro('foo', fn() => $this->map(...))写成fn() => collect(...)->map(...)就绕开了$this，反而失去链式能力
Macro 和 PHP 8.2+ 的独立函数、PHP 8.4 的只读类共存问题
Macro 本质是往静态属性里塞闭包，它不改变类定义，也不参与 autoloading 或 opcache 预编译。这意味着：
- 开发环境改了 macro，要清 config 缓存（
php artisan config:clear）没用，得清 opcache 或重启 FPM/swoole - 在 Swoole 或 RoadRunner 这类常驻内存环境中，macro 只注册一次，后续请求复用——所以不要在 macro 闭包里引用 request-scoped 对象（如
request()），除非显式传参 - PHP 8.4 的只读类（
readonly class）不影响 macro 使用，因为 macro 不修改类结构，只扩展行为 - Macro 无法被 IDE 自动补全（除非用 phpstan-laravel 或 larastan 插件额外声明）
真正难的是跨服务共享宏逻辑——比如想让多个 package 都用同一个 Collection::macro('groupByCount')，就得把注册逻辑抽成 service provider，再 require 到主项目，而不是靠“复制粘贴”。这点容易被忽略，直到团队协作时宏行为不一致才暴露出来。