发布于 由admin

深入理解 WordPress `rest_after_insert_block()` 钩子源码：在区块被插入后执行的自定义操作。

各位观众老爷，早上好！今天咱们来聊聊 WordPress 里一个挺有意思的钩子：rest_after_insert_block()。这玩意儿就像个小精灵，在你往 WordPress 数据库里插完一个区块之后，它就蹦出来，让你有机会做点你想做的事儿。

咱们要深入理解它，就得先知道它是什么，在哪里，以及怎么用。

一、rest_after_insert_block() 钩子是什么？

简单来说，rest_after_insert_block() 是一个 WordPress 的动作钩子（action hook）。这意味着它允许你在特定事件发生后执行自定义代码。这里的“特定事件”指的是：当一个新区块通过 REST API 成功插入到 WordPress 数据库中时。

你可能会问，区块是通过哪种方式插入的？ 答案是：通过WordPress REST API。 比如，古登堡编辑器（Gutenberg Editor）在保存文章或页面时，实际上就是通过 REST API 将区块数据发送到服务器，然后插入到 wp_posts 表的 post_content 字段中。

二、rest_after_insert_block() 钩子在哪里？

这个钩子定义在 wp-includes/rest-api/endpoints/class-wp-rest-blocks-controller.php 文件中的 insert_item() 方法里。你可以自己去 WordPress 的核心代码里找找，感受一下。

// 核心代码片段 (简略版)
class WP_REST_Blocks_Controller extends WP_REST_Posts_Controller {

    public function insert_item( $request ) {
        // ... 一些代码 ...

        $prepared_post = $this->prepare_item_for_database( $request );

        $post_id = wp_insert_post( wp_slash( (array) $prepared_post ), true );

        if ( is_wp_error( $post_id ) ) {
            // ... 错误处理 ...
        }

        $post = get_post( $post_id );

        /**
         * Fires after a single block is completely inserted via the REST API.
         *
         * @since 5.6.0
         *
         * @param WP_Post         $post     Inserted or updated post object.
         * @param WP_REST_Request $request  Request object.
         * @param bool            $creating True when creating a post, false when updating.
         */
        do_action( 'rest_after_insert_block', $post, $request, true ); // 注意这里

        // ... 其他代码 ...
    }
}

从代码中可以看到，do_action('rest_after_insert_block', $post, $request, true); 这行代码触发了这个钩子。它传递了三个参数：

  • $post: 插入或更新后的 WP_Post 对象，代表文章或页面。
  • $request: WP_REST_Request 对象，包含了请求的所有信息，比如传递过来的参数。
  • $creating: 一个布尔值，如果是新建文章/页面，则为 true，如果是更新，则为 false。

三、rest_after_insert_block() 钩子怎么用？

要使用这个钩子，你需要在你的主题或插件中，通过 add_action() 函数来注册一个回调函数。这个回调函数会在区块插入之后被执行。

基本语法如下：

add_action( 'rest_after_insert_block', 'your_custom_function', 10, 3 );
  • 'rest_after_insert_block': 要挂载的钩子的名称。
  • 'your_custom_function': 你自定义的回调函数名。
  • 10: 优先级，数字越小，优先级越高。通常用 10 就行了。
  • 3: 回调函数接收的参数数量，这里是 3 个，对应于 do_action() 传递的三个参数。

四、实战演练：用 rest_after_insert_block() 做点什么好玩的？

好了，理论说了一堆，不如来点实际的。我们来模拟几个场景，看看用这个钩子能干些什么。

场景 1：自动添加自定义字段

假设你希望在每次创建一篇新文章时，自动添加一个自定义字段，比如 block_inserted_time，记录区块插入的时间。

function my_custom_block_insert_action( $post, $request, $creating ) {
    if ( $creating ) { // 只在新建文章时执行
        update_post_meta( $post->ID, 'block_inserted_time', current_time( 'mysql' ) );
    }
}
add_action( 'rest_after_insert_block', 'my_custom_block_insert_action', 10, 3 );

这段代码的意思是：

  1. 定义一个名为 my_custom_block_insert_action 的函数，它接收 $post, $request, $creating 三个参数。
  2. 判断 $creating 是否为 true，如果是，说明是新建文章，才执行后续操作。
  3. 使用 update_post_meta() 函数，将当前时间保存到 block_inserted_time 这个自定义字段中，关联到当前文章的 ID。
  4. 通过 add_action() 函数，将 my_custom_block_insert_action 函数挂载到 rest_after_insert_block 钩子上。

场景 2：发送邮件通知

假设你希望在每次更新文章时，发送一封邮件通知管理员，告知文章内容已更新。

function my_custom_block_update_notification( $post, $request, $creating ) {
    if ( ! $creating ) { // 只在更新文章时执行
        $to      = '[email protected]'; // 管理员邮箱
        $subject = '文章已更新';
        $body    = '文章 "' . $post->post_title . '" 已于 ' . current_time( 'mysql' ) . ' 更新。';
        $headers = array( 'Content-Type: text/html; charset=UTF-8' );

        wp_mail( $to, $subject, $body, $headers );
    }
}
add_action( 'rest_after_insert_block', 'my_custom_block_update_notification', 10, 3 );

这段代码和上面的类似，只不过判断条件是 $creating 是否为 false，并且使用了 wp_mail() 函数发送邮件。

场景 3：记录日志

假设你想记录每次区块插入或更新的详细信息，方便日后排查问题。

function my_custom_block_log( $post, $request, $creating ) {
    $log_message = '文章 ID: ' . $post->ID . "n";
    $log_message .= '文章标题: ' . $post->post_title . "n";
    $log_message .= '是否新建: ' . ($creating ? '是' : '否') . "n";
    $log_message .= '请求参数: ' . print_r( $request->get_params(), true ) . "n";
    $log_message .= '时间: ' . current_time( 'mysql' ) . "n";
    $log_message .= "--------------------n";

    error_log( $log_message, 3, WP_CONTENT_DIR . '/block_insert.log' ); // 写入日志文件
}
add_action( 'rest_after_insert_block', 'my_custom_block_log', 10, 3 );

这段代码将文章 ID、标题、是否新建、请求参数等信息，写入到一个名为 block_insert.log 的日志文件中。 注意 error_log 函数的第二个参数 3 表示将错误信息写入到指定的文件中，第三个参数是文件路径。

五、WP_REST_Request 对象：深入挖掘请求信息

在上面的例子中，我们用到了 $request 对象。这个对象包含了客户端发送过来的所有请求信息，非常有用。 常用的方法如下：

方法 描述 示例
get_params() 获取所有请求参数，返回一个数组。 $request->get_params()
get_param( $key ) 获取指定名称的请求参数。 $request->get_param( 'title' )
get_header( $key ) 获取指定名称的请求头。 $request->get_header( 'Authorization' )
get_body() 获取请求体，通常是 JSON 字符串。 $request->get_body()
get_method() 获取请求方法，例如 ‘GET’, ‘POST’, ‘PUT’, ‘DELETE’。 $request->get_method()

例如，如果你想获取用户在保存文章时填写的标题，可以使用 $request->get_param( 'title' )。

六、注意事项

  • 性能问题： 你的回调函数应该尽可能高效，避免执行耗时的操作，否则会影响文章保存的速度。
  • 错误处理： 在你的回调函数中，要做好错误处理，避免出现未知的错误导致程序崩溃。
  • 安全问题： 如果你从 $request 对象中获取用户输入，一定要进行验证和过滤，防止 XSS 攻击等安全问题。
  • 上下文： rest_after_insert_block 钩子是在 WordPress REST API 的上下文中执行的，因此你可以使用 WordPress 提供的各种 API 函数。

七、总结

rest_after_insert_block() 钩子是一个非常强大的工具，它允许你在区块插入之后执行自定义操作。你可以利用它来实现各种各样的功能，比如自动添加自定义字段、发送邮件通知、记录日志等等。只要你充分发挥想象力，就能用它做出很多有趣的东西。

希望今天的讲解对你有所帮助。 记住，实践是检验真理的唯一标准，赶紧动手试试吧！ 如果有问题，欢迎随时提问。 下次再见！

发表回复

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