为 WP-CLI Doctor 编写自定义检查-未完纪

wp doctor 的检查建立在统一的抽象类之上，因此编写自定义检查的步骤比较直接：创建一个继承 runcommand\Doctor\Checks\Check 的类，并实现 run() 方法。这个方法根据检查逻辑设置状态和提示信息。

下面的带注释示例检查 Akismet 是否已经启用，并且配置了用于验证的 API 密钥。

<?php

/**
 * Ensures Akismet is activated with the appropriate credentials.
 */
class Akismet_Activated extends runcommand\Doctor\Checks\Check {

    public function __construct( $options = array() ) {
        parent::__construct( $options );
        // Every check is to run on 'after_wp_load' by default.
        // You could instead use 'before_wp_load' or 'after_wp_config_load'
        $this->set_when( 'after_wp_load' );
    }

    public function run() {
        // If the Akismet isn't activated, bail early.
        if ( ! class_exists( 'Akismet' ) ) {
            $this->set_status( 'error' );
            $this->set_message( "Akismet doesn't appear to be activated." );
            return;
        }
        // Verify that the API exists.
        $api_key = Akismet::get_api_key();
        if ( empty( $api_key ) ) {
            $this->set_status( 'error' );
            $this->set_message( 'API key is missing.' );
            return;
        }
        // Verify that the API key is valid.
        $verification = Akismet::verify_key( $api_key );
        if ( 'failed' === $verification ) {
            $this->set_status( 'error' );
            $this->set_message( 'API key verification failed.' );
            return;
        }
        // Everything looks good, so report a success.
        $this->set_status( 'success' );
        $this->set_message( 'Akismet is activated with a verified API key.' );
    }

}

如果把这个类保存为 akismet-activated.php，可以在 doctor.yml 中这样注册它：

plugin-akismet-activated:
  class: Akismet_Activated
  require: akismet-activated.php

然后使用该配置运行检查：

$ wp doctor check plugin-akismet-activated --config=doctor.yml
+--------------------------+--------+---------------------+
| name                     | status | message             |
+--------------------------+--------+---------------------+
| plugin-akismet-activated | error  | API key is missing. |
+--------------------------+--------+---------------------+

阅读和使用这个示例时

检查名 plugin-akismet-activated 同时出现在 YAML 配置与命令参数中；class 指向类名，require 指向包含这个类的文件。把示例的两个文件放在明确的工作目录，并核对实际使用的配置文件与加载路径。

构造函数先调用父类，再设置执行阶段。示例使用 after_wp_load，此时 WordPress 已完成加载；代码注释还列出了 before_wp_load 与 after_wp_config_load。需要访问插件类的检查，应选择能够加载该插件的阶段。

代码依次检查插件类是否存在、是否取得密钥、验证结果是否为 failed，遇到前两种缺失情况或该失败值时返回错误状态。最后两行设置成功状态与说明。状态和提示由检查对象保存，而不是靠输出一段终端文本来报告。

wp doctor 来自 Doctor 命令包。运行前先确认目标环境已经安装了与 WP-CLI 兼容的该命令包，以及它使用的检查基类。本页不声称所有 WP-CLI 安装都默认包含此命令。

终端块保留了原文的 $ 提示符和示例输出。真正执行时输入 $ 后面的命令；表格中的“API key is missing.” 是原文展示的结果，不是本文在目标站点运行后的结果。

原示例的验证边界

上面的三个代码块保留官方页面的代码、配置和输出，未把示例悄悄改成另一个实现。原代码只把 failed 视为验证失败。Akismet 官方密钥验证接口说明还列出了 valid 与 invalid 结果，因此不能仅从“不是 failed”推断“密钥有效”。这是根据接口文档作出的审查提示；仍需核对实际安装的 Akismet 版本中 Akismet::verify_key() 的包装逻辑。

将此示例用于真实检查前，应覆盖无效密钥、网络失败和有效密钥三种情况，确认只有明确有效的结果才进入成功分支。如果目标版本的方法直接返回 valid 或 invalid，就应以 valid 作为成功条件，而不是把所有其他结果都当作成功。本文没有运行 PHP、加载 WordPress 或调用 Akismet 来验证这些分支。

密钥验证可能向 Akismet 发送请求。不要为了演示填写真实密钥，也不要把密钥放进代码、终端截图或日志；先阅读目标插件的实现并安排适当的测试环境。

来源与许可

原文：Write a custom check to perform an arbitrary assertion，WP-CLI Development Group。本文完整汉化原文正文，并另加上述阅读说明与验证边界；代码块保留网页版本。

文档源文件：wp-cli/handbook。该文件所在仓库以 MIT 许可发布。补充核对来源：Doctor 命令包、Akismet 密钥验证接口。

The MIT License (MIT)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

文章版权归作者所有，未经允许请勿转载。

THE END