PHP8.4 使用 Psalm 静态代码检测实现代码质量管控教程-php教程-PHP中文网

psalm 尚未完全支持 php 8.4，但可通过 v5.23+ 版本提前适配显式空值、只读类等特性，配合 allowphpversionmismatch、--php-version=8.4 及 ci 卡点实现渐进式质量管控。

php8.4 使用 psalm 静态代码检测实现代码质量管控教程

PHP 8.4 尚未正式发布（截至 2024 年中仍为开发中版本），因此 Psalm 官方尚未提供对 PHP 8.4 语法的完整支持。但你可以基于当前 Psalm 最新版（如 v5.23+）提前适配 PHP 8.4 的新增特性，并为未来升级做好质量管控准备。

Psalm 的 PHP 支持具有滞后性，新 PHP 版本的语法（如 PHP 8.4 的 explicit_nullability、#[\Override]、只读类增强、enum 构造函数等）需等待 Psalm 主动解析支持。目前（2024 年中）：

Psalm v5.23+ 已初步识别部分 PHP 8.4 语法（如更宽松的联合类型写法），但会跳过未识别结构，不报错也不分析
若遇到 Unexpected token 或解析中断，说明 Psalm 版本过低，需升级到最新稳定版（composer update vimeo/psalm）
可通过 psalm --version 和 php -v 核对环境；建议在 PHP 8.3 环境下完成 Psalm 配置，再迁移至 PHP 8.4 运行时验证

即使 Psalm 尚未完全支持 PHP 8.4，你仍可主动启用实验性检查和兼容模式：

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

在 psalm.xml 中添加 allowPhpVersionMismatch="true"（防止因 PHP 版本声明不匹配而中断）
启用 <featureset></featureset> 中的 explicit-nullability（对应 PHP 8.4 的显式空值标记），需配合 Psalm v5.22+ 和 <typecoercion></typecoercion> 调整
使用 --php-version=8.4 手动指定目标版本（命令行或 psalm.xml 的 <projectfiles></projectfiles> 下设置）
对尚未支持的语法（如 #[\Override]），可临时用 /** @psalm-suppress InvalidDocblock */ 屏蔽警告，待 Psalm 更新后移除

在 GitHub Actions / GitLab CI 中加入 Psalm 检查，确保 PHP 8.4 代码符合质量红线：

安装时指定 PHP 8.4 运行环境（如 GitHub Actions 使用 shivammathur/setup-php@v2 + php-version: '8.4'）
运行命令建议：psalm --no-cache --find-dead-code --report-show-info=false（禁用缓存避免 CI 冲突，开启死代码检测）
设置失败阈值：通过 --error-level 或 <issuehandlers></issuehandlers> 将 InvalidReturnType、UndefinedClass 等设为 error，其他设为 warning
生成 XML 报告供 SonarQube 解析：psalm --output-format=checkstyle --report=psalm-report.xml

针对 PHP 8.4 明确引入的特性，提前规划 Psalm 适配路径：

只读类增强：Psalm v5.23 已支持 readonly class，但需开启 allowReadOnlyPropertyAssignment 并校验构造函数赋值完整性
枚举构造函数：目前 Psalm 将 enum E { case X(value: int); } 视为语法错误；建议暂用 @psalm-ignore-nullable-return 绕过，关注 Psalm v5.24+ 发布日志
显式空值类型（T|null → ?T）：Psalm 默认支持，但需关闭 allowMissingProperties 避免误判 ?string 字段未初始化
定期订阅 Psalm Release Notes，重点关注 “PHP 8.4 support” 相关条目