PHPStan返回类型报错：方法应返回指定类型却返回mixed的解决问询

问题原因 #

PHPStan无法准确推断self::$requirementsArrayImage[$key] ?? null的类型，核心原因有两点：

• 静态属性$requirementsArrayImage初始化为空数组，后续赋值在构造函数中，PHPStan无法追踪到类实例化后对静态属性的类型修改；
• 即便有PHPDoc注释，数组索引访问的类型推断在这种场景下仍存在局限。

简洁解决方案 #

方案1：将静态数组初始化移至属性声明处 #

把构造函数里的数组赋值直接放到静态属性的定义中，让PHPStan直接解析数组的结构和元素类型：

/**
 * Provides basic requirements
 * @var array<string, array<string, string|int>|string|int|float>
 */
private static array $requirementsArrayImage = [
    'allowed_ratio' => ['1', '4/3', '16/9'],
    'allowed_file_types_array' => ['jpeg', 'png'],
    'min_pixels' => 2000,
    'min_width_px' => 400,
    'min_height_px' => 200,
    // ... 其他元素
];

// 移除构造函数中的赋值代码
public function __construct()
{
    // 原赋值代码已移至属性声明
}

这样PHPStan能直接识别数组元素的类型，自然就能推断出返回值的正确类型，无需额外代码。

方案2：添加显式PHPDoc类型注释（无需修改初始化逻辑） #

如果必须在构造函数中初始化静态数组，可在返回前给变量添加PHPDoc注释，明确标注类型：

public static function getRequirementsArrayImageByKey(string|int $key): string|int|float|array|null
{
    /** @var array<string, mixed>|string|int|float|null $result */
    $result = self::$requirementsArrayImage[$key] ?? null;
    return $result;
}

这个方案仅添加一行注释，不会增加代码逻辑复杂度，PHPStan会根据注释识别返回值类型。

额外说明 #

确保方法的返回类型提示与PHPDoc注释一致：当前方法的类型提示是string|int|float|array|null，PHPDoc是array<string, mixed>|string|int|float|null，两者兼容，但如果需要更精确的类型提示（PHP 8.4暂不支持泛型类型提示），保持PHPDoc的精确性即可，PHPStan会优先参考PHPDoc进行类型检查。

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