如何在Psalm项目中添加新的问题类型

如何在Psalm项目中添加新的问题类型

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

理解Psalm问题类型系统

Psalm作为一款静态代码分析工具，其核心功能之一就是检测代码中的各种潜在问题。这些问题在Psalm内部被组织为不同的"问题类型"(Issue Type)，每种类型都有特定的错误级别和短代码标识。

创建新问题类型的完整流程

1. 生成短代码标识

首先需要为新问题类型分配一个唯一的短代码标识(SHORTCODE)。运行项目提供的脚本可以获取当前已使用的最大短代码值：

php bin/max_used_shortcode.php

记下输出的$max_shortcode值，新问题的短代码应该使用这个值加1。

2. 创建问题类

在Psalm\Issue命名空间下创建新的问题类，继承自适当的基类。以下是基本模板：

<?php

namespace Psalm\Issue;

final class MyNewIssue extends CodeIssue 
{
    public const ERROR_LEVEL = 2;
    public const SHORTCODE = 123; // 使用上一步获取的值+1
}

选择合适的基类

Psalm提供了多种基类，根据问题的性质选择合适的基类可以让问题更有针对性：

• CodeIssue：通用问题基类
• ClassIssue：与类/接口/特性/枚举相关的问题
• PropertyIssue：属性相关问题
• FunctionIssue：函数相关问题
• ArgumentIssue：参数相关问题
• MethodIssue：方法相关问题
• ClassConstantIssue：类常量相关问题
• VariableIssue：变量相关问题

选择正确的基类还决定了该问题类型如何在配置文件中被单独抑制。

3. 配置XML架构

所有问题类型都需要在config.xsd文件中注册，这样才能在配置文件中使用。根据选择的基类，添加相应的类型定义。

4. 编写问题文档

每个问题类型都需要有详细的文档说明，包括：

1. 在docs/running_psalm/issues目录下创建Markdown文件
2. 包含能触发该问题的PHP代码示例
3. 代码示例必须使用PHP代码块并包含<?php起始标签
4. 示例代码必须确实能触发所描述的问题

5. 添加文档链接

将新问题的文档链接添加到主文档索引中，确保用户能够找到。

6. 运行文档测试

执行文档测试确保所有步骤都正确完成：

vendor/bin/phpunit tests/DocumentationTest.php

7. 在核心代码中使用新问题类型

最后，在Psalm的核心检测逻辑中适当位置添加新问题的触发代码：

IssueBuffer::maybeAdd(new MyNewIssue(...))

最佳实践建议

1. 错误级别选择：合理设置ERROR_LEVEL，1为最严重，6为最轻微
2. 问题描述清晰：文档中要明确说明问题的表现和可能的修复方案
3. 测试覆盖：除了文档测试，建议为新增的问题类型添加单元测试
4. 基类选择：尽量选择最具体的基类，方便用户针对性抑制

通过以上步骤，开发者可以为Psalm添加新的问题检测类型，扩展其静态分析能力。每个新问题类型的添加都应该经过充分的设计和测试，确保其准确性和实用性。

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