WordPress WP-CLI 命令注册详解：WP_CLI::add_command() 讲座
各位码农、代码艺术家、以及所有对 WordPress 命令行接口（WP-CLI）感兴趣的朋友们，欢迎来到今天的“WP-CLI 命令注册详解：WP_CLI::add_command()”讲座。我是你们今天的导游，将带领大家深入了解 WP-CLI 的核心机制，学习如何像变魔术一样，创造属于自己的命令行命令。
首先，跟大家打个招呼：各位早安/午安/晚安！希望今天的讲座能给大家带来收获。
为什么我们需要自定义 WP-CLI 命令？
在开始之前，我们先来聊聊，为什么我们需要自定义 WP-CLI 命令？难道 WP-CLI 自带的命令还不够用吗？
想象一下，你是一个大型 WordPress 站点的维护者，每天都要处理大量的重复性工作：
- 批量更新插件。
- 清理垃圾评论。
- 导出指定用户的数据。
- 等等…
如果每次都要手动操作，那简直是噩梦！而 WP-CLI 自带的命令可能无法完全满足你的需求。这时候，自定义命令就派上用场了！它可以帮你把这些重复性工作自动化，提高效率，让你有更多的时间去喝咖啡、撸猫、或者思考人生的意义。
WP_CLI::add_command()：注册命令的核心
WP_CLI::add_command() 是 WP-CLI 中注册自定义命令的核心函数。它就像一个魔法咒语，可以将你编写的代码注册成一个可以被 WP-CLI 识别和执行的命令。
让我们深入了解一下这个函数的用法和参数。
函数原型
WP_CLI::add_command( string $name, mixed $callable, array $args = array() );参数详解
| 参数 | 类型 | 描述 | 示例 |
|---|---|---|---|
$name |
string | 命令的名称。这是你在命令行中输入的命令名称，例如：wp my-custom-command。 |
'my-custom-command'， 'backup-database' |
$callable |
mixed | 命令的回调函数或类。可以是函数名、静态方法、实例方法，甚至是闭包。这是命令执行的具体逻辑。 | 'my_custom_function'，'My_Custom_Class::my_static_method'，array( new My_Custom_Class(), 'my_instance_method' )，function( $args, $assoc_args ) { ... } |
$args |
array | （可选）命令的参数配置。用于定义命令的参数、选项、帮助信息等。这决定了你的命令如何接收和处理用户的输入。 | array( 'shortdesc' => '这是一个自定义命令。', 'synopsis' => array( array( 'type' => 'assoc', 'name' => 'param1', 'description' => '第一个参数。', 'optional' => false, 'default' => 'default_value' ), ) ) |
重要提示：
$name必须是唯一的，不能与其他已注册的命令冲突。$callable必须是可调用的，否则 WP-CLI 会报错。$args是可选的，但通常情况下，为了让你的命令更加灵活和易于使用，建议配置参数。
注册一个简单的命令：Hello World!
让我们先来注册一个最简单的命令，输出 "Hello World!"。
-
创建插件文件: 创建一个插件文件，例如
my-custom-wp-cli-commands.php，并将其放在wp-content/plugins/目录下。 -
编写插件代码: 在插件文件中添加以下代码：
<?php
/**
* Plugin Name: My Custom WP-CLI Commands
* Description: 注册一些自定义的 WP-CLI 命令。
* Version: 1.0.0
*/
if ( defined( 'WP_CLI' ) && WP_CLI ) {
/**
* 输出 "Hello World!"。
*
* ## EXAMPLES
*
* wp hello-world
*
* @when before_wp_load
*/
function my_hello_world_command() {
WP_CLI::line( 'Hello World!' );
}
WP_CLI::add_command( 'hello-world', 'my_hello_world_command' );
}-
激活插件: 在 WordPress 后台激活该插件。
-
运行命令: 在命令行中输入
wp hello-world，你应该会看到 "Hello World!" 的输出。
代码解释：
defined( 'WP_CLI' ) && WP_CLI：这段代码用于判断当前是否在 WP-CLI 环境下运行，避免在 Web 界面下执行。my_hello_world_command()：这是我们自定义的命令的回调函数，它负责输出 "Hello World!"。WP_CLI::line()：这是 WP-CLI 提供的用于输出信息的函数。WP_CLI::add_command( 'hello-world', 'my_hello_world_command' )：这行代码将hello-world命令注册到 WP-CLI，并指定my_hello_world_command函数作为该命令的回调函数。@when before_wp_load: 这个注释告诉 WP-CLI 在 WordPress 加载之前运行这个命令。
注册一个带有参数的命令：计算平方
现在，让我们来注册一个稍微复杂一点的命令，接收一个数字作为参数，并计算它的平方。
- 修改插件代码: 修改
my-custom-wp-cli-commands.php文件，添加以下代码：
<?php
/**
* Plugin Name: My Custom WP-CLI Commands
* Description: 注册一些自定义的 WP-CLI 命令。
* Version: 1.0.0
*/
if ( defined( 'WP_CLI' ) && WP_CLI ) {
/**
* 计算一个数字的平方。
*
* ## OPTIONS
*
* <number>
* : 要计算平方的数字。
*
* ## EXAMPLES
*
* wp square 5
* # 25
*
* @param array $args 命令行参数.
* @param array $assoc_args 关联数组参数.
* @when before_wp_load
*/
function my_square_command( $args, $assoc_args ) {
$number = (int) $args[0]; // 将第一个参数转换为整数
if ( ! is_numeric( $number ) ) {
WP_CLI::error( '请输入一个数字。' );
return;
}
$square = $number * $number;
WP_CLI::success( "{$number} 的平方是 {$square}。" );
}
WP_CLI::add_command( 'square', 'my_square_command' );
}-
激活插件: 如果插件已经激活，则无需再次激活。
-
运行命令: 在命令行中输入
wp square 5，你应该会看到 "5 的平方是 25。" 的输出。
代码解释：
## OPTIONS：这个注释块定义了命令的参数。<number>：表示一个必需的参数，名为 "number"。: 要计算平方的数字。：参数的描述。
$args：这是一个数组，包含了命令的所有参数。在这个例子中，$args[0]就是用户输入的第一个参数，也就是要计算平方的数字。$assoc_args：这是一个关联数组，包含了所有以--开头的选项。我们稍后会介绍选项的用法。WP_CLI::error()：这是 WP-CLI 提供的用于输出错误信息的函数。WP_CLI::success()：这是 WP-CLI 提供的用于输出成功信息的函数。
使用 $args 配置参数
$args 参数允许你更精细地控制命令的参数。它可以定义参数的类型、描述、是否可选、默认值等等。
$args 参数是一个数组，可以包含以下键：
shortdesc：命令的简短描述。longdesc：命令的详细描述。synopsis：一个数组，用于定义命令的参数和选项。
synopsis 数组中的每个元素都代表一个参数或选项，可以包含以下键：
type：参数或选项的类型。可以是positional（位置参数）、assoc（关联数组选项）或flag（布尔选项）。name：参数或选项的名称。description：参数或选项的描述。optional：是否可选。默认为false。default：默认值。multiple：是否允许多个值。默认为false。
让我们通过一个例子来演示如何使用 $args 配置参数。
- 修改插件代码: 修改
my-custom-wp-cli-commands.php文件，添加以下代码：
<?php
/**
* Plugin Name: My Custom WP-CLI Commands
* Description: 注册一些自定义的 WP-CLI 命令。
* Version: 1.0.0
*/
if ( defined( 'WP_CLI' ) && WP_CLI ) {
/**
* 问候用户。
*
* ## OPTIONS
*
* [--name=<name>]
* : 用户的名字。默认为 "World"。
*
* [--greeting=<greeting>]
* : 问候语。默认为 "Hello"。
*
* ## EXAMPLES
*
* wp greet --name=John
* # Hello John!
*
* wp greet --greeting=Hi --name=Jane
* # Hi Jane!
*
* @param array $args 命令行参数.
* @param array $assoc_args 关联数组参数.
* @when before_wp_load
*/
function my_greet_command( $args, $assoc_args ) {
$name = WP_CLIUtilsget_flag_value( $assoc_args, 'name', 'World' );
$greeting = WP_CLIUtilsget_flag_value( $assoc_args, 'greeting', 'Hello' );
WP_CLI::line( "{$greeting} {$name}!" );
}
$args = array(
'shortdesc' => '问候用户。',
'synopsis' => array(
array(
'type' => 'assoc',
'name' => 'name',
'description' => '用户的名字。',
'optional' => true,
'default' => 'World',
),
array(
'type' => 'assoc',
'name' => 'greeting',
'description' => '问候语。',
'optional' => true,
'default' => 'Hello',
),
),
);
WP_CLI::add_command( 'greet', 'my_greet_command', $args );
}-
激活插件: 如果插件已经激活，则无需再次激活。
-
运行命令: 在命令行中输入以下命令，并观察输出：
wp greet：输出 "Hello World!"wp greet --name=John：输出 "Hello John!"wp greet --greeting=Hi --name=Jane：输出 "Hi Jane!"
代码解释：
$args数组定义了两个选项：name和greeting。'type' => 'assoc'：表示这是一个关联数组选项，可以通过--name=value的方式传递参数。'optional' => true：表示这个选项是可选的。'default' => 'World'：表示这个选项的默认值是 "World"。WP_CLIUtilsget_flag_value()：这是一个 WP-CLI 提供的工具函数，用于获取选项的值。它接收三个参数：$assoc_args：关联数组，包含了所有以--开头的选项。'name'：选项的名称。'World'：选项的默认值。
使用类来组织命令
如果你的命令比较复杂，建议使用类来组织代码。这可以提高代码的可读性和可维护性。
- 修改插件代码: 修改
my-custom-wp-cli-commands.php文件，添加以下代码：
<?php
/**
* Plugin Name: My Custom WP-CLI Commands
* Description: 注册一些自定义的 WP-CLI 命令。
* Version: 1.0.0
*/
if ( defined( 'WP_CLI' ) && WP_CLI ) {
/**
* Class My_Custom_Commands
*
* 包含自定义 WP-CLI 命令的类。
*/
class My_Custom_Commands {
/**
* 计算一个数字的平方。
*
* ## OPTIONS
*
* <number>
* : 要计算平方的数字。
*
* ## EXAMPLES
*
* wp calc square 5
* # 25
*
* @param array $args 命令行参数.
* @param array $assoc_args 关联数组参数.
* @when before_wp_load
*/
public function square( $args, $assoc_args ) {
$number = (int) $args[0]; // 将第一个参数转换为整数
if ( ! is_numeric( $number ) ) {
WP_CLI::error( '请输入一个数字。' );
return;
}
$square = $number * $number;
WP_CLI::success( "{$number} 的平方是 {$square}。" );
}
}
WP_CLI::add_command( 'calc', 'My_Custom_Commands' ); // 注册类
}-
激活插件: 如果插件已经激活，则无需再次激活。
-
运行命令: 在命令行中输入
wp calc square 5，你应该会看到 "5 的平方是 25。" 的输出。
代码解释：
- 我们创建了一个名为
My_Custom_Commands的类，并将square函数作为该类的一个方法。 WP_CLI::add_command( 'calc', 'My_Custom_Commands' )：这行代码将calc命令注册到 WP-CLI，并指定My_Custom_Commands类作为该命令的回调对象。当执行wp calc命令时，WP-CLI 会自动创建My_Custom_Commands类的实例，并调用该实例的square方法。- 注意： 当使用类来注册命令时，你需要使用
wp calc square这种形式来调用命令。calc只是一个命名空间，真正的命令是square。
高级技巧：子命令
WP-CLI 还支持子命令，允许你将命令组织成层次结构。
例如，你可以创建一个 wp my-plugin 命令，然后添加 wp my-plugin install 和 wp my-plugin uninstall 子命令。
要创建子命令，你需要使用 WP_CLI::add_command() 函数注册一个父命令，然后使用 WP_CLI::add_command() 函数再次注册子命令，并将子命令的名称设置为 父命令名称 子命令名称。
总结
WP_CLI::add_command() 是 WP-CLI 中注册自定义命令的核心函数。通过合理地使用这个函数，你可以创建强大的自定义命令，自动化你的 WordPress 工作流程，提高效率。
记住，编写清晰、易于理解的代码，并提供详细的帮助信息，可以让你的命令更加易于使用和维护。
希望今天的讲座对大家有所帮助！祝大家编程愉快！
练习题：
- 创建一个 WP-CLI 命令，可以备份 WordPress 数据库。
- 创建一个 WP-CLI 命令，可以批量删除指定用户的所有文章。
- 创建一个 WP-CLI 命令，可以导出指定分类的所有文章到 CSV 文件。
尝试使用今天学到的知识，解决这些问题吧！