自从我开始使用人工智能(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,以及如何添加显示其使用情况的徽章。
参考资料
- PHPStan,官方网站。
- Rule Levels,级别文档。
- 我正在使用的两个项目:Design Laboratori Italia,KK Content Exporter。
*** 注意:本文是通过使用 n8n 和 OpenAI 自动翻译生成的。原文版本为意大利语。

