PHPStan 类型收窄指南：精确控制变量类型范围

什么是类型收窄

在 PHP 静态分析工具 PHPStan 中，类型收窄（Type Narrowing）是指将变量的类型范围从宽泛的类型缩小到更具体的类型。这是编写类型安全代码的重要技术，特别是在处理联合类型（如 bool|int）或需要针对特定子类型（如 InvalidArgumentException）执行操作时。

为什么需要类型收窄

1. 提高代码安全性：确保变量在使用时具有预期的具体类型
2. 增强静态分析效果：帮助 PHPStan 更准确地理解代码意图
3. 减少运行时错误：提前发现潜在的类型相关问题

类型收窄的基本方法

1. 精确的类型声明

最佳实践是从源头避免类型过宽的问题：

// 精确的参数类型
function processArticle(Article $article): void {
    // 这里$article保证是Article类型
}

// 精确的返回类型
function getFeaturedArticle(): Article {
    // 返回具体的Article对象
    return $article;
}

2. 严格比较运算符

使用 === 和 !== 可以收窄标量类型：

if ($mixedValue === 42) {
    // 这里$mixedValue被收窄为整数42
}

assert($possibleString !== '');
// 断言后$possibleString排除了空字符串

3. 类型检查函数

PHP 内置的类型检查函数能有效收窄类型：

if (is_int($value)) {
    // $value被收窄为int
}

assert(is_object($data));
// 断言后$data被收窄为object

4. instanceof 运算符

处理对象类型时最常用的收窄方式：

if ($exception instanceof InvalidArgumentException) {
    // $exception被收窄为InvalidArgumentException
}

高级类型收窄技术

自定义类型检查函数

对于自定义的类型检查逻辑，可以使用 PHPDoc 标注：

/**
 * @phpstan-assert Admin $user
 */
function validateAdmin(User $user): void {
    if (!$user->isAdmin()) {
        throw new InvalidArgumentException();
    }
}

// 使用后
validateAdmin($user);
// $user被收窄为Admin类型

条件性类型断言

使用 @phpstan-assert-if-true 和 @phpstan-assert-if-false：

/**
 * @phpstan-assert-if-true \DateTimeInterface $value
 */
function isDateTime($value): bool {
    return $value instanceof \DateTimeInterface;
}

if (isDateTime($data)) {
    // $data被收窄为DateTimeInterface
}

泛型支持

类型收窄与泛型完美配合：

/**
 * @template T of object
 * @param class-string<T> $className
 * @phpstan-assert-if-true T $object
 */
function isInstanceOf(string $className, object $object): bool {
    return $object instanceof $className;
}

特殊场景处理

否定类型断言

可以断言某个类型不存在：

/**
 * @phpstan-assert !string $value
 */
function ensureNotString($value): void {
    if (is_string($value)) {
        throw new Exception();
    }
}

属性关系断言

表达属性之间的条件关系：

/** @phpstan-assert-if-true !null $this->getName() */
public function hasName(): bool {
    return $this->name !== null;
}

精确控制断言行为

使用 = 运算符避免自动的反向断言：

/**
 * @phpstan-assert-if-true =Admin $this->admin
 */
public function isAdmin(): bool {
    return $this->admin !== null;
}

最佳实践建议

1. 优先使用精确类型声明：从源头减少类型收窄的需求
2. 合理使用断言：在确实需要收窄的地方使用适当的断言
3. 保持一致性：团队统一类型收窄的方式
4. 利用静态分析：通过 PHPStan 验证类型收窄的正确性

通过掌握这些类型收窄技术，您可以显著提高代码的类型安全性，减少运行时错误，并使 PHPStan 能够提供更准确的静态分析结果。