分析 WordPress `WP_CLI` 类的 `log()`、`success()`、`error()` 方法源码：如何处理命令行的输出。

WP-CLI 输出控制台：log()、success()、error() 的幕后故事

各位好！今天咱们聊聊 WordPress 命令行工具 WP-CLI 里面的几个小能手：log()、success()、error()。它们负责把命令运行的结果，像说书人一样，清清楚楚地展示给咱们。别看它们名字简单，背后的逻辑可一点都不含糊。

咱们先来热个身，看看这几个方法长啥样：

<?php

namespace WP_CLI;

class WP_CLI {

    /**
     * Output a string to STDOUT, respecting --quiet.
     *
     * @param string $str String to output.
     */
    public static function log( $str ) {
        if ( ! Utilsget_flag_value( self::$config, 'quiet', false ) ) {
            fwrite( STDOUT, $str . PHP_EOL );
        }
    }

    /**
     * Output a green string to STDOUT, respecting --quiet.
     *
     * @param string $str String to output.
     */
    public static function success( $str ) {
        if ( ! Utilsget_flag_value( self::$config, 'quiet', false ) ) {
            fwrite( STDOUT, self::colorize( "%GSuccess: {$str}%n" ) . PHP_EOL );
        }
    }

    /**
     * Output a red string to STDERR, respecting --quiet.
     *
     * @param string $str String to output.
     */
    public static function error( $str ) {
        fwrite( STDERR, self::colorize( "%RError: {$str}%n" ) . PHP_EOL );
    }

    /**
     * Colorize a string for output.
     *
     * @param string $string String to colorize.
     * @return string Colorized string.
     */
    public static function colorize( $string ) {
        $colors = array(
            '%y' => "33[33m", // Yellow
            '%g' => "33[32m", // Green
            '%b' => "33[34m", // Blue
            '%r' => "33[31m", // Red
            '%p' => "33[35m", // Purple
            '%m' => "33[36m", // Cyan
            '%n' => "33[0m",  // Reset
            '%Y' => "33[1;33m", // Yellow Bold
            '%G' => "33[1;32m", // Green Bold
            '%B' => "33[1;34m", // Blue Bold
            '%R' => "33[1;31m", // Red Bold
            '%P' => "33[1;35m", // Purple Bold
            '%M' => "33[1;36m", // Cyan Bold
            '%N' => "33[0m",   // Reset
        );

        return str_replace( array_keys( $colors ), array_values( $colors ), $string );
    }

    public static $config = array();

}

怎么样，是不是感觉还挺亲切的？接下来，咱们逐个剖析，看看它们到底是怎么工作的。

1. WP_CLI::log()：普普通通的“记录员”

log() 方法就像一个兢兢业业的记录员，负责把你想说的话，原原本本地输出到控制台上。它的主要任务就是：

• 判断是否安静模式： 通过 Utilsget_flag_value( self::$config, 'quiet', false ) 检查是否开启了 --quiet 参数。如果开启了，它就闭嘴不说话，保持安静。
• 输出字符串： 如果不是安静模式，它就用 fwrite( STDOUT, $str . PHP_EOL ) 把字符串输出到标准输出 (STDOUT)。PHP_EOL 是换行符，保证每条信息都独占一行。

代码示例：

WP_CLI::log( '开始执行数据库备份...' );
// 如果没加 --quiet 参数，控制台会显示：开始执行数据库备份...

总结： log() 方法简单直接，主要负责输出普通的信息，比如命令执行的进度、状态等等。

2. WP_CLI::success()：报喜不报忧的“喜报员”

success() 方法稍微高级一点，它不仅能输出信息，还能给信息加上绿色的“成功”标签，让咱们一眼就能看出命令执行成功了。它的主要任务是：

• 判断是否安静模式： 和 log() 一样，先检查是否开启了 --quiet 参数。
• 格式化字符串： 使用 self::colorize( "%GSuccess: {$str}%n" ) 将字符串格式化成绿色。%G 和 %n 是颜色代码，分别表示“绿色开始”和“颜色重置”。
• 输出字符串： 使用 fwrite( STDOUT, ... ) 将格式化后的字符串输出到标准输出 (STDOUT)。

代码示例：

WP_CLI::success( '数据库备份完成！' );
// 如果没加 --quiet 参数，控制台会显示：Success: 数据库备份完成！（绿色字体）

总结： success() 方法用于输出执行成功的消息，并用绿色字体突出显示，增加视觉上的辨识度。

3. WP_CLI::error()：拉响警报的“报警员”

error() 方法是这三个方法里最严肃的一个，它负责输出错误信息，并用红色的“错误”标签警示咱们。它的主要任务是：

• 格式化字符串： 使用 self::colorize( "%RError: {$str}%n" ) 将字符串格式化成红色。%R 和 %n 是颜色代码，分别表示“红色开始”和“颜色重置”。
• 输出字符串： 使用 fwrite( STDERR, ... ) 将格式化后的字符串输出到标准错误 (STDERR)。注意，这里用的是 STDERR，而不是 STDOUT。

代码示例：

WP_CLI::error( '数据库备份失败！' );
// 控制台会显示：Error: 数据库备份失败！（红色字体）

总结： error() 方法用于输出执行失败的消息，并用红色字体突出显示，同时输出到标准错误流，方便咱们区分错误信息和普通信息。

4. WP_CLI::colorize()：色彩魔法师

这三个方法都用到了 self::colorize() 方法，这个方法是给字符串上色的关键。它通过替换字符串中的特殊代码，来实现不同颜色的输出。

• 颜色代码： colorize() 方法定义了一个颜色代码数组 $colors，包含了各种颜色对应的 ANSI 转义序列。
• 字符串替换： colorize() 方法使用 str_replace() 函数，将字符串中的颜色代码替换成对应的 ANSI 转义序列。

代码示例：

$colored_string = WP_CLI::colorize( "%RThis is red text.%n" );
echo $colored_string; // 控制台会显示红色的 "This is red text."

重要提示： ANSI 转义序列并不是所有终端都支持。如果你的终端不支持 ANSI 转义序列，颜色代码会直接显示在字符串中，影响可读性。

颜色代码表：

代码	颜色	说明
%y	Yellow	黄色
%g	Green	绿色
%b	Blue	蓝色
%r	Red	红色
%p	Purple	紫色
%m	Cyan	青色
%n	Reset	重置颜色
%Y	Yellow Bold	黄色（粗体）
%G	Green Bold	绿色（粗体）
%B	Blue Bold	蓝色（粗体）
%R	Red Bold	红色（粗体）
%P	Purple Bold	紫色（粗体）
%M	Cyan Bold	青色（粗体）
%N	Reset	重置颜色（粗体）

5. STDOUT 和 STDERR：两条不同的输出通道

• STDOUT (Standard Output)： 标准输出，用于输出正常的信息，比如命令执行的进度、结果等等。
• STDERR (Standard Error)： 标准错误，用于输出错误信息，比如命令执行失败的原因等等。

使用 STDOUT 和 STDERR 的好处是，可以将正常信息和错误信息分开处理。例如，可以将错误信息重定向到日志文件，方便排查问题。

6. --quiet 参数：让世界安静

--quiet 参数的作用是禁止 WP-CLI 输出任何信息。这在某些自动化脚本中非常有用，可以避免输出干扰脚本的执行。

log()、success()、error() 方法都会检查是否开启了 --quiet 参数。如果开启了，它们就不会输出任何信息。

代码示例：

wp plugin install akismet --quiet
# 不会输出任何信息

7. WP_CLI::$config：配置信息的大本营

WP_CLI::$config 是一个静态属性，用于存储 WP-CLI 的配置信息，例如 --quiet 参数的值。

Utilsget_flag_value() 函数用于从 WP_CLI::$config 中获取指定参数的值。

8. 如何在自定义命令中使用这些方法

在自定义 WP-CLI 命令中，你可以直接使用 WP_CLI::log()、WP_CLI::success()、WP_CLI::error() 方法来输出信息。

代码示例：

<?php

class My_Command {

    /**
     * 执行一些操作
     *
     * ## EXAMPLES
     *
     *     wp my-command do-something
     *
     * @when after_wp_load
     */
    public function do_something() {
        try {
            // 执行一些操作
            WP_CLI::log( '开始执行操作...' );
            // ...
            WP_CLI::success( '操作执行成功！' );
        } catch ( Exception $e ) {
            WP_CLI::error( '操作执行失败：' . $e->getMessage() );
        }
    }
}

WP_CLI::add_command( 'my-command', 'My_Command' );

9. 总结一下

方法	功能	输出位置	颜色	是否受 --quiet 影响
log()	输出普通信息	STDOUT	无	是
success()	输出成功信息	STDOUT	绿色	是
error()	输出错误信息	STDERR	红色	否 (始终输出)
colorize()	给字符串添加颜色代码	–	–	–

这三个方法是 WP-CLI 输出控制台信息的核心，它们分工明确，各司其职，让咱们能够清晰地了解命令的执行状态。 掌握了它们，你就可以在自定义命令中，像一位优秀的播报员一样，把信息传递给用户。

最后，别忘了，好的输出信息能够极大地提升用户体验。让你的 WP-CLI 命令不仅功能强大，而且友好易用！ 今天的分享就到这里，感谢各位的聆听！