Larastan 中宏定义的正确使用方式：避免 Invokable 类陷阱

问题背景

在使用 Laravel 框架的字符串宏功能时，开发者可能会遇到一个常见的陷阱：尝试通过 invokable 类来定义宏。虽然这在运行时可能不会立即报错，但当配合 Larastan 静态分析工具使用时，就会暴露出类型不匹配的问题。

错误示例分析

让我们先看一个典型的错误实现方式：

class ReplaceVariables
{
    public function __invoke(
        string $string,
        array $variablesToReplace,
        $variablePrefix = '{{',
        $variableSuffix = '}}'
    ): Stringable {
        // 实现逻辑...
    }
}

Str::macro('replaceVariables', app(ReplaceVariables::class));

这种实现方式会导致 Larastan 抛出类型错误，因为 Larastan 期望宏定义必须返回一个闭包(Closure)类型，而不是直接使用 invokable 类的实例。

正确的宏定义方式

方法一：使用闭包直接定义

最简单直接的方式是使用闭包来定义宏：

Str::macro('replaceVariables', function (
    string $string,
    array $variablesToReplace,
    $variablePrefix = '{{',
    $variableSuffix = '}}'
): Stringable {
    // 实现逻辑...
});

这种方式简洁明了，适合简单的宏逻辑。

方法二：使用返回闭包的 Invokable 类

如果需要更复杂的逻辑组织，可以使用 invokable 类，但必须确保它返回一个闭包：

class ReplaceVariables
{
    public function __invoke(): Closure {
        return function (
            string $string,
            array $variablesToReplace,
            $variablePrefix = '{{',
            $variableSuffix = '}}'
        ): Stringable {
            // 实现逻辑...
        };
    }
}

Str::macro('replaceVariables', app(ReplaceVariables::class));

方法三：使用 Mixin 模式

对于更复杂的扩展需求，可以使用 Mixin 模式：

class StringMixin
{
    public function replaceVariables()
    {
        return function (
            string $string,
            array $variablesToReplace,
            $variablePrefix = '{{',
            $variableSuffix = '}}'
        ): Stringable {
            // 实现逻辑...
        };
    }
}

Str::mixin(new StringMixin());

技术原理

Laravel 的宏系统底层实现依赖于 PHP 的魔术方法 __call 和 __callStatic。当调用一个宏方法时，Laravel 会检查注册的宏是否可调用。虽然 invokable 类实例本身是可调用的，但 Larastan 的静态分析需要更严格的类型约束。

Larastan 在分析宏调用时，会尝试将宏转换为闭包类型进行类型推断。当遇到 invokable 类实例而不是闭包时，就会抛出类型错误。这是静态分析工具比运行时检查更严格的一个典型例子。

最佳实践建议

1. 简单逻辑优先使用闭包：对于简单的字符串处理，直接使用闭包定义宏是最清晰的方式。

2. 复杂逻辑考虑 Mixin：当需要为一组相关功能扩展字符串类时，Mixin 模式提供了更好的组织方式。

3. 避免直接使用 invokable 类：虽然技术上可行，但会带来静态分析问题，不是推荐的做法。

4. 保持类型一致性：确保宏定义返回的类型与文档标注一致，这有助于 IDE 和静态分析工具提供更好的支持。

通过遵循这些实践，开发者可以避免 Larastan 的类型错误，同时写出更健壮、更易维护的代码。