如何在PHPStan中将泛型数组转换为更具体的数组结构？

问题背景 #

我调用了一个返回类型声明如下的方法：

/**
 * @return array<int, array<string,mixed>>
 */
public function fetchAllAssociative(): array;

其中子类型array<string, mixed>是数据库记录的泛型描述。我明确知晓该数据库记录的具体结构，因此想在自定义方法里更精准地声明返回类型：

/**
 * @return array<int, array{id: int, firstName: string, lastName: string}>
 */
public function getAllUsers(): array
{
  return $this->userRepository->fetchAllAssociative();
}

但PHPStan报错类型不匹配：

Method UserRepository::getAllUsers() should return array<int, array{id: int, firstName: string, lastName: string}> but returns array<int, array<string, mixed>>.

我不想用临时方案——引入新变量并添加@var标签（其他静态分析工具也不支持这种写法）：

/**
 * @return array<int, array{id: int, firstName: string, lastName: string}>
 */
public function getAllUsers(): array
{
  /**
   * @var array<int, array{id: int, firstName: string, lastName: string}> $data
   */
  $data = $this->userRepository->fetchAllAssociative();

  return $data;
}

可行解决方案 #

1. 增加类型断言与验证（推荐） #

通过array_map遍历每条记录，添加运行时类型断言，同时让PHPStan识别精确类型：

/**
 * @return array<int, array{id: int, firstName: string, lastName: string}>
 */
public function getAllUsers(): array
{
    return array_map(function(array $user): array {
        // 运行时验证字段存在且类型正确
        assert(isset($user['id']) && is_int($user['id']), '用户ID必须是整数');
        assert(isset($user['firstName']) && is_string($user['firstName']), '用户名字必须是字符串');
        assert(isset($user['lastName']) && is_string($user['lastName']), '用户姓氏必须是字符串');
        
        return $user;
    }, $this->userRepository->fetchAllAssociative());
}

这种方式既解决了PHPStan的类型报错，又增加了运行时的类型安全，避免非法数据流入业务逻辑。

2. 使用DTO转换为强类型对象（更优） #

定义一个UserDTO类将数组转换为强类型对象，彻底解决类型模糊的问题：

// 定义UserDTO类
class UserDTO
{
    public function __construct(
        public int $id,
        public string $firstName,
        public string $lastName
    ) {}
}

// 修改getAllUsers方法
/**
 * @return array<int, UserDTO>
 */
public function getAllUsers(): array
{
    return array_map(function(array $user): UserDTO {
        // 强制转换类型，确保类型正确
        return new UserDTO(
            id: (int)$user['id'],
            firstName: (string)$user['firstName'],
            lastName: (string)$user['lastName']
        );
    }, $this->userRepository->fetchAllAssociative());
}

这种方式不仅让PHPStan完美识别类型，还提升了代码的可读性和维护性，后续使用用户数据时无需再关注数组键名和类型。

3. 直接告知PHPStan类型兼容（不推荐） #

如果确定数据结构绝对符合预期，且不想添加额外代码，可以使用PHPStan专属注解跳过类型检查：

/**
 * @return array<int, array{id: int, firstName: string, lastName: string}>
 */
public function getAllUsers(): array
{
    /** @phpstan-ignore-next-line */
    return $this->userRepository->fetchAllAssociative();
}

注意：这种方式会绕过PHPStan的类型检查，失去了静态分析的意义，仅适用于数据结构完全可控的场景。

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