深入理解Psalm中的断言注解机制-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00145/article/details/148490692

深入理解Psalm中的断言注解机制

psalm A static analysis tool for finding errors in PHP applications 项目地址: https://gitcode.com/gh_mirrors/ps/psalm

前言

在PHP静态分析工具Psalm中，断言注解是一种强大的类型系统增强工具，它允许开发者明确表达函数或方法对变量和属性的验证逻辑。本文将全面解析Psalm中的五种断言注解，帮助开发者编写更安全、更可靠的代码。

五种核心断言注解

Psalm提供了五种关键的docblock注解来增强类型断言能力：

@psalm-assert - 用于抛出异常时验证类型
@psalm-assert-if-true - 当函数返回true时验证类型
@psalm-assert-if-false - 当函数返回false时验证类型
@psalm-if-this-is - 方法调用时对对象模板参数进行断言
@psalm-this-out - 方法调用后改变对象的模板参数

基础断言示例

数组类型验证

考虑一个验证字符串数组的函数，我们可以使用@psalm-assert来明确其行为：

/** @psalm-assert string[] $arr */
function validateStringArray(array $arr): void {
    foreach ($arr as $s) {
        if (!is_string($s)) {
            throw new UnexpectedValueException('Invalid value ' . gettype($s));
        }
    }
}

使用这个函数后，Psalm会记住验证结果：

function takesArray(array $arr): void {
    takesInt($arr[0]);  // 这里没问题
    
    validateStringArray($arr);
    
    takesInt($arr[0]);  // 这里会报错，因为Psalm知道$arr现在是字符串数组
    
    foreach ($arr as $a) {
        takesString($a);  // 这里没问题
    }
}

条件断言

@psalm-assert-if-true和@psalm-assert-if-false特别适合验证函数：

/**
 * @psalm-assert-if-true B $a
 */
function isValidB(A $a): bool {
    return $a instanceof B && $a->isValid();
}

/**
 * @psalm-assert-if-false B $a
 */
function isInvalidB(A $a): bool {
    return !$a instanceof B || !$a->isValid();
}

使用这些函数时，Psalm会根据返回值智能推断类型：

function takesA(A $a): void {
    if (isValidB($a)) {
        $a->bar();  // Psalm知道$a现在是B类型
    }
    
    if (isInvalidB($a)) {
        // 处理无效情况
    } else {
        $a->bar();  // 这里$a也是B类型
    }
    
    $a->bar();  // 这里会报错，因为不能确定$a是B类型
}

高级用法

空值断言

断言注解同样适用于空值检查：

/** @psalm-assert !null $value */
function assertNotNull($value): void {
    if ($value === null) {
        throw new InvalidArgumentException('Value cannot be null');
    }
}

/** @psalm-assert-if-true null $value */
function isNull($value): bool {
    return $value === null;
}

方法返回值断言

在类方法中，断言注解可以同时验证多个属性或方法返回值：

class Result {
    private ?Exception $exception;
    
    /**
     * @psalm-assert-if-true Exception $this->exception
     * @psalm-assert-if-true Exception $this->getException()
     */
    public function hasException(): bool {
        return $this->exception !== null;
    }
    
    // 其他方法...
}

注意：要使这类断言正常工作，需要启用方法调用记忆化功能或将类标记为不可变。

模板参数断言

对于泛型类，可以使用@psalm-if-this-is和@psalm-this-out来操作模板参数：

/** @template T */
class A {
    /** @psalm-this-out self<T|NewT> */
    public function addData($data) { /*...*/ }
    
    /** @psalm-if-this-is a<int> */
    public function test(): void { /*...*/ }
}

这种机制使得Psalm能够跟踪泛型类型的变化，提供更精确的类型检查。