Laravel项目中@phpstan-ignore在GitLab CI不生效的解决办法咨询

问题背景 #

Laravel的__()助手函数PHPDoc标注返回string|array|null，但sprintf不接受数组作为参数，触发PHPStan错误：

Parameter #2 ...$values of function sprintf expects bool|float|int|string|null, array|string|null given.
Parameter #3 ...$values of function sprintf expects bool|float|int|string|null, array|string|null given.

本地添加@phpstan-ignore注释后错误消失，但GitLab CI仍触发相同错误，且可确保这些__()调用绝不会返回数组。

解决方案 #

1. 全局覆盖__()函数返回类型（推荐）

在项目的phpstan.neon或phpstan.neon.dist配置文件中，通过functionMap强制指定__()的返回类型为字符串：

parameters:
    functionMap:
        __: 'function(string $key, array $replace = [], ?string $locale = null): string'

此方案全局生效，无需在每个调用处添加注释，彻底解决同类类型报错。若场景中__()可能返回null，可将返回类型改为string|null（sprintf兼容null参数）。

2. 局部类型断言

针对特定调用，用PHPStan类型注释明确指定返回值为字符串：

sprintf("%s %s",
    /** @var string */ __('foo.bar.buzz'),
    /** @var string */ __('foo.bar.baz')
);

也可结合运行时断言，同时保障静态分析和运行时类型安全：

$buzz = __('foo.bar.buzz');
$baz = __('foo.bar.baz');

assert(is_string($buzz), __('foo.bar.buzz') . ' 必须返回字符串');
assert(is_string($baz), __('foo.bar.baz') . ' 必须返回字符串');

sprintf("%s %s", $buzz, $baz);

3. 修正忽略注释格式

若坚持使用忽略指令，需改用单行//注释格式（部分PHPStan配置会忽略多行注释中的忽略规则）：

sprintf("%s %s",
    __('foo.bar.buzz'), // @phpstan-ignore argument.type
    __('foo.bar.baz')   // @phpstan-ignore argument.type
);

内容的提问来源于stack exchange，提问作者Rexy