PHP 数组与静态分析工具的配合

静态分析工具需通过数组形状注解、关联数组优先、类型声明与断言、精准配置规则来准确校验php数组。例如用@phpstan-var Array{status: String, code: int}明确结构，避免array或mixed[]模糊类型，启用checkarrayaccess等规则捕获未定义键。

PHP 数组灵活但容易出错，静态分析工具（如 PHPStan、Psalm、PHP_CodeSniffer）能提前发现类型不匹配、键不存在、空值解引用等问题。关键在于让工具“理解”数组结构，而不是把数组当黑盒处理。

用数组形状（Array Shapes）明确结构

PHPStan 和 Psalm 支持 数组形状注解，显式声明键名、类型和是否可选，大幅提升分析精度：

• PHPStan：用 @phpstan-var array{status: string, code: int, data?: array} 注释变量
• Psalm：支持类似语法，还可配合 @psalm-var 或类型别名（type ApiResponse = array{status: string, code: int};）
• 避免用模糊的 array 或 mixed[]，否则工具无法校验 $res['message'] 是否存在

优先使用键值明确的数组，而非数字索引

静态分析对关联数组（string keys）的支持远好于纯数字索引数组。例如：

• ✅ 推荐：$user = ['id' => 123, 'name' => 'Alice']; —— 工具可校验 $user['email'] 是否缺失
• ❌ 谨慎：$row = [123, 'Alice', 'alice@example.com']; —— 工具无法知道索引 2 对应邮箱，易引发运行时错误
• 若必须用数字索引，可用 @var array{0: int, 1: string, 2: string} 显式标注

配合类型声明与断言增强可信度

PHP 7.4+ 的属性类型、8.0+ 的联合类型、以及 assert() / is_array() 检查，能帮静态分析器缩小推理范围：

立即学习“PHP免费学习笔记（深入）”；

• 在方法签名中使用 array{...} 作为参数或返回类型（PHPStan 支持，需开启 strict-rules）
• 用 assert(isset($arr['required_key'])); 向 Psalm/PHPStan 提供运行时保证，避免误报“可能未定义键”
• 搭配 array_filter($arr, 'is_string') 后，可加 @var array<string></string> 帮助推导

配置规则，聚焦数组常见陷阱

在 phpstan.neon 或 psalm.xml 中启用针对性规则：

• PHPStan：开启 checkArrayAccess（检查未定义键）、checkArrayItemAccess（检查键类型）
• Psalm：启用 InvalidArrayOffset、PossiblyUndefinedArrayOffset 等检查项
• 禁用宽松模式（如 PHPStan 的 level: 5 起），才能捕获 $arr['missing'] ?? NULL 这类隐式容错写法的问题