PHPStan能检测出哪些类型错误？——全面指南与实战问答
目录导读
- PHPStan检测类型错误的核心理念
- 基础类型错误检测
- 复杂类型与泛型错误检测
- 函数与方法声明错误
- 继承与接口契约违规
- 动态调用与魔术方法陷阱
- 实战问答：常见类型错误场景解析
- 如何配置PHPStan提升检测精度
PHPStan检测类型错误的核心理念
PHPStan是一款静态分析工具，它不实际运行代码，而是通过解析抽象语法树（AST）和类型推断引擎，在编译阶段发现潜在的运行时错误，与PHP内置的type hint不同，PHPStan能检测出隐式类型转换错误、未定义属性访问、泛型约束违规等深层次问题，根据官方文档，PHPStan支持从Level 0到Level 9共9个检测强度等级，等级越高,检测越严格。
核心检测类型包括：
- 基础类型不匹配
- 方法签名冲突
- 联合类型/交叉类型错误
- 模板类型（泛型）违规
- 死代码与不可达分支
基础类型错误检测
PHPStan能够检测以下基础类型错误：
1 类型赋值错误
function getAge(): int {
return "twenty"; // PHPStan报告：返回值类型应为int，但返回string
}
检测点： 函数返回值类型与声明不符；变量赋值时类型冲突（如$name = 123; 但后续作为字符串使用）。
2 Null安全与可空类型
function getName(?string $name): string {
return $name; // PHPStan报告：可能返回null，但声明返回string
}
检测点： 未正确处理null值；调用可空对象上的方法（如$obj?->method()误写为$obj->method()）。
3 数组键值类型错误
/** @param array<string, int> $items */
function process(array $items): void {
echo $items[0]; // PHPStan报告：键名类型应为string，但使用int访问
}
复杂类型与泛型错误检测
1 联合类型误用
function handle(int|string $value): void {
if (is_int($value)) {
echo $value->length; // PHPStan报告：int没有length属性
}
}
检测点： 类型缩窄不完整；联合类型成员的方法调用不当。
2 泛型（模板类型）约束违规
/**
* @template T
* @param array<T> $items
* @return T
*/
function first(array $items) {
return $items[0];
}
$result = first([1, 2, 3]);
echo $result->name; // PHPStan报告：int没有name属性
检测点： 泛型参数未正确实例化；类型参数边界被违反（如@template T of SomeInterface但传入其他类型）。
函数与方法声明错误
1 参数数量与类型不匹配
function add(int $a, int $b): int {
return $a + $b;
}
add("5", 3); // PHPStan报告：参数1应为int，收到string
add(1); // PHPStan报告：缺少参数2
2 可变参数与callable错误
function sum(int ...$numbers): int {
return array_sum($numbers);
}
sum(1, 2, "3"); // PHPStan报告：参数应为int，但收到string
继承与接口契约违规
1 方法协变/逆变错误
class ParentClass {
public function getValue(): int {}
}
class ChildClass extends ParentClass {
public function getValue(): string {} // PHPStan报告：返回值类型协变冲突
}
检测点： 子类方法返回值类型范围必须更小（协变），参数类型范围必须更大（逆变）；违反该原则则报错。
2 未实现接口方法
interface Logger {
public function log(string $message): void;
}
class FileLogger implements Logger {
// PHPStan报告：缺少log方法实现
}
动态调用与魔术方法陷阱
1 未定义属性访问
class User {
private string $name;
}
$user = new User();
echo $user->name; // PHPStan报告：属性User::$name不可访问
2 魔术方法签名错误
class Data {
public function __get(string $name): mixed {
return $this->data[$name] ?? null;
}
}
$obj = new Data();
echo $obj->foo; // PHPStan默认不报错，但如果配置了checkMagicMethods: true则会检查__get返回值类型
实战问答：常见类型错误场景解析
Q1：为什么PHPStan报告“Cannot call method on mixed”？
A： 当变量类型为mixed（混合类型）时，PHPStan无法推断其具体方法，解决方案：使用instanceof进行类型缩窄，或添加@param/@var注解明确类型。
Q2：如何检测“使用未初始化变量”？
A： 开启Level 0以上即可。
function test(): void {
echo $x; // PHPStan：Undefined variable: x
}
注意：未初始化的变量在读取前会触发警告。
Q3：PHPStan能检测出死代码吗？
A： 可以，如return后的语句、永远不成立的if分支：
function test(): void {
return;
echo "dead"; // PHPStan：Unreachable statement
}
Q4：泛型如何协变？
A： PHPStan支持@template-covariant标记。
/**
* @template-covariant T
*/
class Collection {
// 仅允许T出现在返回位置，禁止出现在参数位置
}
如何配置PHPStan提升检测精度
要充分发挥PHPStan的类型错误检测能力,建议：
- 安装社区扩展包：如
phpstan/phpstan-phpunit（检测测试辅助）、phpstan/phpstan-symfony（框架集成） - 使用严格的基准配置：
phpstan.neon中写：parameters: level: max # 最高检测等级 checkMissingIterableValueType: true checkGenericClassInNonGenericObjectType: true checkUninitializedProperties: true checkTooWideReturnType: true
- 结合PHPDoc注解：为动态数据添加强类型标注，如
@param array{name: string, age: int}。
PHPStan能检测的基础与高级类型错误超过30种，从简单的类型不匹配到复杂的泛型约束违规均可覆盖，通过合理配置Level等级和扩展，可有效避免80%以上的运行时类型错误，建议在CI流程中集成PHPStan扫描,每日维护类型安全。
提示：实际错误列表会随phpstan版本变化，可通过运行
vendor/bin/phpstan analyse --list-known-custom-error-identifiers查看当前版本支持的所有错误标识符。
