深入理解 WordPress `WP_CLI` 类的 `log_level()` 函数的源码：如何控制 WP-CLI 的日志输出。

各位观众老爷们，晚上好！欢迎来到今晚的“扒光 WordPress WP_CLI 的底裤”特别节目！今天咱们要聊的是 WP_CLI 里一个不起眼，但却非常实用的家伙：WP_CLI::log_level()。这玩意儿就像 WP-CLI 的嗓门大小调节器，控制着它在你终端里嘟嘟囔囔的程度。

准备好了吗？咱们开始吧！

一、WP_CLI 的日志系统：一场精彩的戏

首先，我们需要对 WP_CLI 的日志系统有个全局的认识。WP_CLI 为了方便开发者调试和了解命令执行情况，内置了一套日志机制。这套机制允许它在命令执行过程中，输出各种信息，包括：

• Debug 信息: 详细的调试信息，一般用于开发阶段。
• Info 信息: 常规的操作信息，告诉你 WP_CLI 在干什么。
• Warning 信息: 警告信息，提示你可能存在的问题。
• Error 信息: 错误信息，告诉你哪里出错了。
• Success 信息: 成功信息，告诉你一切顺利。

这些信息就像舞台上的演员，各司其职，共同演绎着 WP_CLI 的执行过程。而 WP_CLI::log_level() 就是那个控制音量的调音师，决定你能听到哪些演员的声音。

二、WP_CLI::log_level()：调音师的秘密武器

WP_CLI::log_level() 函数位于 WP-CLI 的核心类 WP_CLI 中。它的作用是设置或获取当前的日志级别。简单来说，就是告诉 WP-CLI，哪些类型的日志信息应该显示出来。

1. 函数定义

让我们先来看看 WP_CLI::log_level() 的函数定义（简化版）：

/**
 * Sets or gets the log level.
 *
 * @param string|null $level Log level to set.
 * @return string|null Current log level.
 */
public static function log_level( $level = null ) {
    static $current_level = 'info'; // 默认的日志级别

    if ( null !== $level ) {
        $level = strtolower( $level ); // 统一转换为小写
        if ( in_array( $level, array( 'debug', 'info', 'warning', 'error', 'success', 'none' ), true ) ) {
            $current_level = $level;
        } else {
            WP_CLI::warning( "Invalid log level: {$level}. Using default 'info'." );
        }
    }

    return $current_level;
}

代码解读：

• static $current_level = 'info';: 这是一个静态变量，用来存储当前的日志级别。默认值是 'info'，也就是说，默认情况下，WP_CLI 会显示 Info 级别及以上的日志信息。
• if ( null !== $level ) { ... }: 这部分代码处理设置日志级别的情况。如果传入了 $level 参数，它会将 $level 转换为小写，并检查 $level 是否是有效的日志级别（'debug', 'info', 'warning', 'error', 'success', 'none'）。如果是有效的，就更新 $current_level 的值；否则，会输出一个警告信息，并保持使用默认的 'info' 级别。
• return $current_level;: 这部分代码处理获取日志级别的情况。如果没有传入 $level 参数，函数会直接返回当前的 $current_level 值。

2. 如何使用 WP_CLI::log_level()

WP_CLI::log_level() 既可以设置日志级别，也可以获取日志级别。

• 设置日志级别:

  WP_CLI::log_level( 'debug' ); // 设置为 Debug 级别
  WP_CLI::log_level( 'warning' ); // 设置为 Warning 级别

• 获取日志级别:

  $current_level = WP_CLI::log_level(); // 获取当前日志级别
  WP_CLI::line( "Current log level: " . $current_level ); // 输出当前日志级别

三、日志级别：从高到低的嗓门

WP_CLI 支持以下几种日志级别，按照从高到低的顺序排列：

日志级别	描述	应用场景
debug	最详细的日志信息，包含所有信息，甚至可以包含变量的值。	开发调试阶段，用于追踪代码执行的每一个细节。
info	常规的操作信息，告诉你 WP_CLI 在干什么。	常规使用场景，用于了解命令执行的基本流程。
success	成功信息，告诉你一切顺利。	命令执行成功时，用于确认操作完成。
warning	警告信息，提示你可能存在的问题，但命令仍然可以继续执行。	当出现一些潜在问题，但不会导致命令执行失败时，用于提醒用户。
error	错误信息，告诉你哪里出错了，命令执行可能会失败。	当命令执行失败时，用于告知用户错误原因。
none	关闭所有日志输出。	当你只想看到命令的最终结果，不想被打扰时使用。

重要提示： 当你设置了某个日志级别后，WP_CLI 会显示该级别及以上的日志信息。例如，如果你设置了 warning 级别，那么 WP_CLI 会显示 warning、error 和 success 级别的日志信息。

四、实战演练：让 WP_CLI 听你的

接下来，我们通过一些实际的例子，来演示如何使用 WP_CLI::log_level() 控制 WP_CLI 的日志输出。

1. 自定义 WP-CLI 命令：一个简单的例子

首先，我们需要创建一个自定义的 WP-CLI 命令，用于演示日志输出。

创建一个名为 my-command.php 的文件，放在 wp-content/plugins/ 目录下 (或者其他 WP 可加载插件的目录). 内容如下：

<?php
/**
 * Plugin Name: My WP-CLI Command
 * Description: A simple WP-CLI command for demonstrating log levels.
 */

if ( defined( 'WP_CLI' ) && WP_CLI ) {

    class My_WP_CLI_Command {

        /**
         * A simple command that demonstrates log levels.
         *
         * ## OPTIONS
         *
         * [--level=<level>]
         * : The log level to use (debug, info, warning, error, success, none).
         *
         * ## EXAMPLES
         *
         *     wp my-command test --level=debug
         *     wp my-command test --level=warning
         *     wp my-command test
         *
         * @when after_wp_load
         */
        public function test( $args, $assoc_args ) {
            $level = WP_CLIUtilsget_flag_value( $assoc_args, 'level', 'info' ); // 默认值为 info

            WP_CLI::log_level( $level );

            WP_CLI::debug( 'This is a debug message.', 'my-command' );
            WP_CLI::info( 'This is an info message.', 'my-command' );
            WP_CLI::success( 'This is a success message.', 'my-command' );
            WP_CLI::warning( 'This is a warning message.', 'my-command' );
            WP_CLI::error( 'This is an error message.', 'my-command' );

            WP_CLI::log_level('info'); // 恢复默认
        }
    }

    WP_CLI::add_command( 'my-command test', 'My_WP_CLI_Command::test' );
}

代码解释：

• @when after_wp_load: 这个注释告诉 WP-CLI，在 WordPress 加载完成后才注册这个命令。
• $level = WP_CLIUtilsget_flag_value( $assoc_args, 'level', 'info' );: 这行代码从命令行参数中获取 level 的值。如果用户没有指定 level，则使用默认值 'info'。
• WP_CLI::log_level( $level );: 这行代码设置当前的日志级别为用户指定的值。
• WP_CLI::debug(...), WP_CLI::info(...), …: 这些代码分别输出不同级别的日志信息。
• WP_CLI::log_level('info'); // 恢复默认: 为了避免影响其他命令的执行，我们在命令执行完毕后，将日志级别恢复为默认的 'info'。

2. 测试不同的日志级别

激活这个插件后，我们就可以在命令行中测试不同的日志级别了。

• wp my-command test --level=debug: 输出所有级别的日志信息。

  Debug: This is a debug message. (my-command)
  Info: This is an info message. (my-command)
  Success: This is a success message.
  Warning: This is a warning message.
  Error: This is an error message.

• wp my-command test --level=warning: 只输出 Warning, Error 和 Success 级别的日志信息。

  Success: This is a success message.
  Warning: This is a warning message.
  Error: This is an error message.

• wp my-command test --level=none: 不输出任何日志信息 (除了命令本身的输出).

  # (什么都没有输出)

• wp my-command test: 使用默认的 info 级别，输出 Info, Success, Warning 和 Error 级别的日志信息。

  Info: This is an info message. (my-command)
  Success: This is a success message.
  Warning: This is a warning message.
  Error: This is an error message.

3. 全局设置日志级别

除了在单个命令中设置日志级别外，我们还可以通过配置文件或环境变量，全局设置 WP_CLI 的日志级别。

• 通过配置文件 wp-cli.yml:

  在 WordPress 根目录下创建一个名为 wp-cli.yml 的文件，内容如下：

  loglevel: debug

  这样，所有 WP_CLI 命令都会使用 Debug 级别的日志输出。

• 通过环境变量 WP_CLI_LOG_LEVEL:

  在终端中设置环境变量：

  export WP_CLI_LOG_LEVEL=warning

  同样，所有 WP_CLI 命令都会使用 Warning 级别的日志输出。

  注意： 命令行参数的优先级高于配置文件，配置文件的优先级高于环境变量。

五、高级用法：自定义日志输出

除了使用 WP_CLI 提供的默认日志输出方式外，我们还可以自定义日志输出，以满足更复杂的需求。

1. 使用 WP_CLI::log() 输出自定义格式的日志信息

WP_CLI::log() 函数可以输出任意格式的日志信息。

WP_CLI::log( WP_CLI::colorize( "%GSuccess:%n This is a custom success message." ) );

代码解释：

• WP_CLI::colorize(): 这个函数可以为日志信息添加颜色。%G 表示绿色，%n 表示恢复默认颜色。

2. 创建自定义的日志处理类

我们可以创建一个自定义的类，实现 WP_CLILoggersLoggerInterface 接口，并将其注册到 WP_CLI 中，从而完全控制日志输出的行为。

这个功能比较高级，这里就不展开讲解了。有兴趣的同学可以参考 WP-CLI 的官方文档。

六、总结：掌控 WP_CLI 的话语权

通过学习 WP_CLI::log_level() 函数的源码，我们了解了 WP_CLI 日志系统的基本原理和使用方法。我们可以根据实际需求，灵活地控制 WP_CLI 的日志输出，从而更好地调试和管理 WordPress。

记住，WP_CLI::log_level() 就像 WP-CLI 的调音师，你可以通过它来掌控 WP_CLI 的话语权，让它在你需要的时候才开口说话，说你想听的话。

好了，今天的“扒光 WordPress WP_CLI 的底裤”特别节目就到这里了。感谢各位观众老爷们的收看！咱们下期再见！