发布于 由admin

分析 WordPress `activate_plugin()` 函数的源码：它是如何通过 `do_action()` 激活插件的。

各位未来的WordPress大神们，欢迎来到今天的“源码八卦时间”。今天咱们要聊的是WordPress插件激活时，那个神秘的activate_plugin()函数，以及它如何通过do_action()这个“广播喇叭”来激活插件的。

开场白：插件激活，一场精心策划的“表演”

想象一下，你安装了一个新的WordPress插件，点击“激活”按钮的那一刻，背后发生的事情远比你看到的要复杂得多。 这可不是简单地把一个文件从“休眠”状态唤醒，而是一场精心策划的“表演”，其中activate_plugin()函数就是这场表演的导演，而do_action()则是负责通知各个“演员”该出场了。

activate_plugin()：导演的剧本

首先，我们来扒一扒activate_plugin()函数的底裤，看看它到底做了些什么。 这个函数位于wp-admin/includes/plugin.php文件中，它的主要任务包括：

  1. 权限检查： 确保当前用户有激活插件的权限。毕竟，不能让随便什么阿猫阿狗都能激活插件，否则你的网站就成了黑客的游乐场了。
  2. 插件文件路径验证： 检查你提供的插件文件路径是否合法，确保它指向一个真正的插件文件。
  3. 激活钩子触发： 这是最关键的一步，也是我们今天的主角do_action()登场的地方。它会触发一个名为activate_{$plugin}的动作钩子，其中{$plugin}是插件的文件路径。
  4. 记录激活状态： 更新WordPress的选项，记录这个插件已经被激活。
  5. 可能的回调函数调用： 如果插件定义了激活时需要执行的回调函数，activate_plugin()会负责调用它们。

源码解剖（精简版）

为了不让大家睡着，我这里只提供一个简化版的activate_plugin()函数，重点关注do_action()的部分：

function activate_plugin( $plugin, $redirect = '', $network_wide = false ) {
    // ... (权限检查、文件路径验证等代码省略) ...

    /**
     * Fires before a plugin is activated.
     *
     * @since 2.5.0
     *
     * @param string $plugin Plugin path to main plugin file with plugin name.
     *
     * @param bool $network_wide Whether to enable the plugin for all sites in the network
     *                            or just the current site. Multisite only. Default is false.
     */
    do_action( 'activate_' . $plugin, $network_wide );

    // ... (记录激活状态、回调函数调用等代码省略) ...
}

do_action()：广播喇叭的威力

现在，让我们聚焦到do_action( 'activate_' . $plugin, $network_wide ); 这行代码。这行代码是整个激活过程的灵魂所在。 do_action() 函数的作用就像一个广播喇叭，它会发出一个信号，告诉所有“监听”这个信号的函数（也就是那些挂载到activate_{$plugin}钩子上的函数）：“嘿，{$plugin}这个插件要激活了，你们该干活了！”

do_action()的语法很简单：

do_action( $tag, $arg1, $arg2, ... );
  • $tag：钩子的名称，也就是我们广播的“频道”。
  • $arg1, $arg2, ...：传递给监听函数的参数。

在这个例子中：

  • $tag 是 'activate_' . $plugin，例如，如果你的插件文件是 my-awesome-plugin/my-awesome-plugin.php，那么 $tag 就是 'activate_my-awesome-plugin/my-awesome-plugin.php'。
  • $arg1 是 $network_wide，表示是否在整个网络中激活插件（仅在多站点环境下有效）。

插件如何“监听”这个信号？

插件通过add_action()函数来“监听”特定的钩子。 add_action() 的语法如下：

add_action( $tag, $function_to_add, $priority = 10, $accepted_args = 1 );
  • $tag：要监听的钩子的名称。
  • $function_to_add：要执行的函数。
  • $priority：执行的优先级，数字越小优先级越高。
  • $accepted_args：函数接受的参数个数。

例如，你的插件想要在激活时创建一些数据库表，你可以在插件的主文件中添加如下代码：

function my_awesome_plugin_activate() {
    global $wpdb;

    $table_name = $wpdb->prefix . 'my_awesome_table';

    $charset_collate = $wpdb->get_charset_collate();

    $sql = "CREATE TABLE $table_name (
        id mediumint(9) NOT NULL AUTO_INCREMENT,
        time datetime DEFAULT '0000-00-00 00:00:00' NOT NULL,
        name varchar(255) NOT NULL,
        PRIMARY KEY  (id)
    ) $charset_collate;";

    require_once( ABSPATH . 'wp-admin/includes/upgrade.php' );
    dbDelta( $sql );
}
register_activation_hook( __FILE__, 'my_awesome_plugin_activate' );

或者，更为推荐的方式：

function my_awesome_plugin_activate() {
    // 创建数据库表的代码
    error_log('Awesome plugin activated!'); // 记录激活事件
}

add_action( 'activate_my-awesome-plugin/my-awesome-plugin.php', 'my_awesome_plugin_activate' );

这段代码的意思是：“当activate_my-awesome-plugin/my-awesome-plugin.php 这个钩子被触发时，执行my_awesome_plugin_activate() 函数。”

register_activation_hook()：WordPress的“糖衣炮弹”

你可能注意到上面第一段代码示例中使用了register_activation_hook()函数。 这是一个WordPress提供的“糖衣炮弹”，它实际上是对add_action() 函数的封装。 它的作用和add_action() 是一样的，只不过它简化了代码，让你的代码更易读。

register_activation_hook() 的语法如下：

register_activation_hook( $file, $function );
  • $file：插件的主文件路径（通常是__FILE__）。
  • $function：要执行的函数。

register_activation_hook( __FILE__, 'my_awesome_plugin_activate' ); 相当于：

add_action( 'activate_' . plugin_basename( __FILE__ ), 'my_awesome_plugin_activate' );

plugin_basename(__FILE__) 的作用是获取插件的主文件名（例如 my-awesome-plugin/my-awesome-plugin.php）。

do_action() 和 apply_filters() 的区别

很多同学容易把do_action() 和 apply_filters() 搞混。 它们都是WordPress的核心钩子机制，但作用不同：

  • do_action()： 用于执行动作（side effects）。 它就像一个广播喇叭，发出一个信号，让其他函数执行一些操作。 它不返回值。
  • apply_filters()： 用于修改数据。 它就像一个过滤器，允许其他函数修改某个变量的值。 它必须返回修改后的值。

可以这样理解：do_action() 用于“做事”，apply_filters() 用于“改东西”。

一个更完整的例子

为了更清晰地展示整个过程，我们来创建一个简单的插件，并演示如何使用do_action() 在插件激活时执行一些操作。

  1. 创建插件文件：my-example-plugin/my-example-plugin.php
<?php
/**
 * Plugin Name: My Example Plugin
 * Description: A simple plugin to demonstrate plugin activation hooks.
 * Version: 1.0.0
 * Author: Your Name
 */

// 激活时执行的函数
function my_example_plugin_activate() {
    // 在wp_options表中添加一个选项
    add_option( 'my_example_plugin_option', 'Hello, world!' );

    // 记录激活事件
    error_log( 'My Example Plugin activated!' );
}

// 注册激活钩子
register_activation_hook( __FILE__, 'my_example_plugin_activate' );

// 停用时执行的函数
function my_example_plugin_deactivate() {
    // 删除wp_options表中的选项
    delete_option( 'my_example_plugin_option' );

    // 记录停用事件
    error_log( 'My Example Plugin deactivated!' );
}

// 注册停用钩子
register_deactivation_hook( __FILE__, 'my_example_plugin_deactivate' );

// 添加一个管理菜单
function my_example_plugin_menu() {
    add_menu_page(
        'My Example Plugin',
        'My Example',
        'manage_options',
        'my-example-plugin',
        'my_example_plugin_page'
    );
}
add_action( 'admin_menu', 'my_example_plugin_menu' );

// 管理页面内容
function my_example_plugin_page() {
    echo '<div class="wrap">';
    echo '<h1>My Example Plugin</h1>';
    echo '<p>This is a simple example plugin.</p>';
    echo '<p>Option value: ' . get_option( 'my_example_plugin_option' ) . '</p>';
    echo '</div>';
}

  1. 激活插件

    在WordPress后台，找到你的插件，点击“激活”。

  2. 验证结果

    • 查看wp_options 表，应该有一个名为 my_example_plugin_option 的选项，其值为 Hello, world!。
    • 查看你的PHP错误日志（通常在 wp-content/debug.log），应该有一行记录 My Example Plugin activated!。
    • 在WordPress后台，你应该能看到一个新的管理菜单项“My Example”，点击后可以看到插件的管理页面。

这个例子演示了如何在插件激活时执行一些操作，包括添加选项、记录日志和添加管理菜单。

多站点环境下的插件激活

在多站点环境下，插件可以在整个网络中激活，也可以只在单个站点中激活。 activate_plugin() 函数会根据 $network_wide 参数的值来触发不同的钩子：

  • 在整个网络中激活： 触发 activate_{$plugin} 钩子，并且 $network_wide 参数为 true。
  • 只在单个站点中激活： 触发 activate_{$plugin} 钩子，并且 $network_wide 参数为 false。

你可以在插件中使用 is_network_admin() 函数来判断当前是否在网络管理界面，从而根据不同的情况执行不同的操作。

表格总结

函数/钩子 作用 参数
activate_plugin() 激活插件，触发 activate_{$plugin} 钩子 $plugin (插件文件路径), $redirect (激活后重定向的URL), $network_wide (是否在整个网络中激活)
do_action() 触发一个动作钩子，执行所有挂载到该钩子上的函数 $tag (钩子名称), $arg1, $arg2, ... (传递给监听函数的参数)
add_action() 监听一个动作钩子，当该钩子被触发时执行指定的函数 $tag (钩子名称), $function_to_add (要执行的函数), $priority (执行优先级), $accepted_args (函数接受的参数个数)
register_activation_hook() 注册插件激活时要执行的函数，实际上是对 add_action() 的封装 $file (插件主文件路径), $function (要执行的函数)
apply_filters() 应用一个过滤器，允许其他函数修改某个变量的值 $tag (过滤器名称), $value (要过滤的值), $arg1, $arg2, ... (传递给监听函数的参数)

进阶思考

  • 插件激活的最佳实践： 插件激活时应该执行哪些操作？ 数据库表的创建、选项的添加、默认值的设置等等。
  • 如何处理激活失败的情况？ 如果激活过程中发生错误，如何优雅地处理？ 显示错误信息、回滚操作等等。
  • 插件停用时的清理工作： 插件停用时应该清理哪些数据？ 删除数据库表、删除选项等等。

结语：掌握do_action()，走向WordPress巅峰

do_action() 是WordPress的核心机制之一，掌握它，你就掌握了WordPress的“任督二脉”。 通过 do_action()，你可以轻松地扩展WordPress的功能，定制你自己的插件。希望今天的讲解能让你对插件激活的原理有更深入的了解。 记住，源码才是王道！ 多看源码，多实践，你也能成为WordPress大神！ 感谢大家的收听，下次再见！

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注