使用 PHPStan 进行代码静态分析

自从我开始使用人工智能(AI)开发WordPress插件以来,我总是担心当前的代理会引入错误或编写过于复杂且不清晰的代码。并不是说我在使用AI之前的代码就无懈可击,恰恰相反。不过,既然有工具可以自动分析和验证代码,为什么不使用它们呢?

其中之一是PHPStan,即PHP静态分析工具,它进行静态分析:不执行代码,而是读取代码并发现那些只有在运行时(甚至生产环境中)才会暴露的错误。例如:不存在的函数或方法、错误的类型、未定义的变量、可能为null的值、永远不会执行的代码。

其优点是检查是自动且可重复的;可以通过命令手动运行,或在每次提交时自动运行,工具会执行一系列检查,根据所选的“清洁级别”目标,产生多或少的警告。

这些警告不会自动修正:需要手动逐一处理。

级别

PHPStan不会一次性应用所有检查,而是将它们组织成从0到10的级别,从最宽松到最严格,且每个级别都包含之前级别的检查。因此,对于已有项目,可以从低级别开始,随着代码的改进逐步提高级别。

简要说明:

  • 级别0–2:检查代码中使用的类、函数、方法和变量是否真实存在。
  • 级别3–5:检查传递给函数的值、返回值和赋值给属性的值是否符合声明的类型。
  • 级别6:要求函数的参数、返回值和类的属性必须始终声明类型。
  • 级别7–10:要求代码处理所有可能的值,包括联合类型、null和mixed类型的值。

级别可以通过命令行选择,例如 vendor/bin/phpstan analyse src --level 5,或者在配置文件 phpstan.neon 中设置。

级别说明

理解达到某个级别实际意味着什么并不直观。基本上,代码中可能的异常根据检查的严格程度被分级,以便逐步解决。

下面列出一些示例,帮助理解每个级别的检查内容,从而确定自己应用程序应达到的最低级别。

每个级别包括:它回答的问题、检查内容以及一个错误示例(❌)和修正示例(✅)。

级别0 – 代码存在吗?

调用的类、函数和方法必须存在,且必须传入所有必需参数。额外的参数只有在级别1才会被报告,因为PHP默认接受它们。

// ❌ 不存在的函数和缺少必需参数
$title = get_the_titel();
$color = get_option();

// ✅
$title = get_the_title();
$color = get_option('my_plugin_color');

级别1 – 变量总是存在吗?

报告可能未定义的变量,例如只在if语句内赋值的变量。

// ❌ 如果 $is_admin 为 false,$msg 不存在
if ($is_admin) {
    $msg = 'Ciao admin';
}
echo $msg;

// ✅
$msg = '';
if ($is_admin) {
    $msg = 'Ciao admin';
}
echo $msg;

级别2 – 方法在任何对象上都存在吗?

级别0只检查调用于$this的方法,这里检查任何对象上的方法,并验证PHPDoc的有效性。

// ❌ WP_Post 没有 getTitle() 方法
function show(WP_Post $post) {
    echo $post->getTitle();
}

// ✅
function show(WP_Post $post) {
    echo $post->post_title;
}

级别3 – 返回承诺的类型吗?

返回值和赋值给属性的值必须符合声明的类型。

// ❌ 声明返回 int,但返回了字符串
function count_items(): int {
    return '5';
}

// ✅
function count_items(): int {
    return 5;
}

级别4 – 有无无用代码?

发现死代码:始终为真或始终为假的条件,以及永远不会执行的代码。

// ❌ $post 已经是 WP_Post:条件总为真
function render(WP_Post $post) {
    if ($post instanceof WP_Post) {
        return $post->post_title;
    }
    return ''; // 不可达
}

// ✅
function render(WP_Post $post) {
    return $post->post_title;
}

级别5 – 传递正确类型的参数吗?

检查传递给函数和方法的参数类型。这是发现最多实际错误的级别。

// ❌ get_post() 需要 int 或 WP_Post,不能是字符串
$post = get_post('abc');

// ✅
$post = get_post(absint($_GET['id'] ?? 0));

级别6 – 声明类型了吗?

报告未声明类型的参数、返回值和属性,包括未描述内容的数组。

// ❌ 未声明类型
function get_ids($posts) {
    return array_map(fn($p) => $p->ID, $posts);
}

// ✅
/**
 * @param WP_Post[] $posts
 * @return int[]
 */
function get_ids(array $posts): array {
    return array_map(fn(WP_Post $p) => $p->ID, $posts);
}

级别7 – 处理所有可能的类型吗?

如果值可能有多种类型(联合类型),代码必须对所有类型都能正常工作,而不仅仅是部分类型。

// ❌ wp_insert_post() 可能返回 int 或 WP_Error
$id = wp_insert_post($data, true);
echo $id + 1;

// ✅
$id = wp_insert_post($data, true);
if (is_wp_error($id)) {
    return;
}
echo $id + 1;

级别8 – 考虑了 null 吗?

禁止对可能为null的值调用方法或访问属性。

// ❌ get_post() 可能返回 null
$post = get_post(42);
echo $post->post_title;

// ✅
$post = get_post(42);
if ($post === null) {
    return;
}
echo $post->post_title;

级别9 – 使用 mixed 时未检查类型?

声明为mixed的值不能直接使用,必须先验证类型。唯一允许的操作是将其传递给另一个mixed。

// ❌ get_option() 返回 mixed,不一定是数组
$opts = get_option('my_plugin_settings');
echo $opts['color'];

// ✅
$opts  = get_option('my_plugin_settings');
$color = is_array($opts) && is_string($opts['color'] ?? null)
    ? $opts['color']
    : 'blue';
echo $color;

级别10 – 隐式 mixed 也检查?

对mixed 隐式类型(即未声明类型的值)也应用级别9的规则。

// ❌ $title 未声明类型,是隐式 mixed
add_filter('the_title', function ($title) {
    return strtoupper($title);
});

// ✅
add_filter('the_title', function ($title) {
    return is_string($title) ? strtoupper($title) : $title;
});

WordPress 中的级别9和10

在WordPress中,这两个级别较难达到,因为许多核心函数返回mixed,原因是WordPress诞生于PHP类型声明出现之前,因此它保存各种形式的数据:许多核心函数返回或接受的参数类型多样。例如:

  • 选项和元数据:get_option()、get_post_meta()、get_transient()可能返回字符串、数组、false等;
  • 过滤器:apply_filters()返回最后一个挂钩回调的返回值,可能是其他插件的回调;
  • 用户输入:$_GET和$_POST的每个字段都必须验证;
  • 钩子回调:通常参数无类型,即级别10的隐式mixed。

因此,从WordPress读取的每个值都必须在使用前进行检查,如级别9和10的示例所示,代码会变得相当冗长。但这些检查并非无用:损坏的选项或返回null的过滤器都是实际的错误,为了可维护性,建议在单一位置验证数据(使用少量类型化的getter或配置类),并始终声明回调的类型。

总结

对于WordPress插件,通常级别5或6是一个不错的折中,而新插件可以目标定为8,强制处理像get_post()这类函数可能返回的null。

对于已有项目,建议从较低级别开始并生成基线(--generate-baseline),以“冻结”已有错误:这样PHPStan只报告新错误,可以逐步提高级别。无论如何,需要安装phpstan-wordpress扩展,否则PHPStan无法识别核心函数。

不用说,这些检查非常适合自动化的持续集成流程,且借助AI代理进行大规模修正,使升级到更高级别变得更容易。

或许我以后会写一篇文章,介绍如何在WordPress插件中配置PHPStan,如何在GitHub上配置CI,以及如何添加显示其使用情况的徽章。

 

参考资料

  1. PHPStan,官方网站。
  2. Rule Levels,级别文档。
  3. 我正在使用的两个项目:Design Laboratori Italia,KK Content Exporter。

*** 注意:本文是通过使用 n8n 和 OpenAI 自动翻译生成的。原文版本为意大利语。

5 days ago

Leave a Reply

Your email address will not be published. Required fields are marked *

评论审核已启用。您的评论可能需要一段时间后才能被显示。