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

各位观众老爷，大家好！今天咱们来聊聊 WordPress 里一个挺有意思的钩子：rest_after_insert_block()。这玩意儿就像个小精灵，在你往 WordPress 编辑器里插入一个区块之后，它就跳出来，让你有机会施展一些魔法，做点你想做的事情。

Part 1: 钩子是个啥？为什么要用它？

首先，得明白钩子（Hook）是啥。你可以把它想象成 WordPress 代码里的一个个“挂钩”，WordPress 在执行某些关键步骤的时候，会看看这些“挂钩”上有没有挂着你的代码。如果有，它就会执行你的代码。

用钩子的好处在于，你不用修改 WordPress 核心代码就能改变它的行为。这就像搭积木，你想让积木房子加个烟囱，不用把整个房子拆了重盖，直接在顶部搭个烟囱就行了。

WordPress 里有两种主要的钩子：

• 动作钩子（Action Hook）： 就像咱们今天的主角 rest_after_insert_block()，它让你在某个事件发生后执行一些操作，比如发送邮件、更新数据库等等。
• 过滤器钩子（Filter Hook）： 允许你修改 WordPress 的数据，比如修改文章标题、过滤评论内容等等。

Part 2: rest_after_insert_block() 钩子：区块插入后的魔法时刻

rest_after_insert_block() 钩子，顾名思义，是在通过 REST API 插入一个区块之后触发的。 这意味着，无论是通过古腾堡编辑器、自定义 REST API 端点，还是其他任何方式，只要是通过 REST API 插入区块，这个钩子就会被调用。

这个钩子能干啥？

想象一下，你可以用它来：

• 记录区块的使用情况，统计哪些区块最受欢迎。
• 根据插入的区块类型，自动添加一些额外的属性或内容。
• 触发一些自定义事件，比如发送通知给管理员。
• 与其他系统集成，比如将区块数据同步到 CRM 系统。

总之，只要你想在区块插入后做点啥，rest_after_insert_block() 就能帮你实现。

Part 3: 源码剖析：看看钩子是怎么工作的

想真正理解 rest_after_insert_block()，还得扒开源码看看它的真面目。

这个钩子是在 wp-includes/rest-api/endpoints/class-wp-rest-blocks-controller.php 文件的 insert_item() 方法中触发的。简单来说，就是当通过 REST API 成功插入一个区块后，WordPress 会调用 do_action() 函数来触发这个钩子。

// 位于 wp-includes/rest-api/endpoints/class-wp-rest-blocks-controller.php 的 insert_item() 方法中

if ( ! is_wp_error( $block ) ) {
    /**
     * Fires after a block is inserted via the REST API.
     *
     * @since 5.5.0
     *
     * @param WP_Block $block The inserted block.
     * @param WP_REST_Request $request The request sent to the API.
     * @param bool $creating True when creating a new block, false when updating an existing one.
     */
    do_action( 'rest_after_insert_block', $block, $request, true ); // 注意这里的 'rest_after_insert_block'
    return rest_ensure_response( $this->prepare_item_for_response( $block, $request ) );
}

从代码中可以看到，do_action() 函数接收了三个参数：

• 'rest_after_insert_block'：钩子的名称，也就是我们要在 add_action() 中使用的字符串。
• $block：插入的区块对象，包含了区块的所有信息，比如区块类型、属性等等。
• $request：REST API 请求对象，包含了请求的所有信息，比如请求参数、请求头等等。
• true：表示这是一个新的区块创建，而不是更新已有的区块。

Part 4: 实战演练：编写自定义钩子函数

理论讲了一堆，不如动手写点代码。咱们来写一个简单的例子，当插入一个段落区块时，自动在段落内容后面添加一句“这是一段自动添加的文字”。

<?php
/**
 * Plugin Name: Block Insertion Handler
 * Description: A simple plugin to demonstrate the rest_after_insert_block hook.
 * Version: 1.0.0
 */

add_action( 'rest_after_insert_block', 'my_custom_block_insertion_handler', 10, 3 );

/**
 * Custom function to handle block insertion.
 *
 * @param WP_Block $block   The inserted block.
 * @param WP_REST_Request $request The request sent to the API.
 * @param bool $creating True when creating a new block, false when updating an existing one.
 */
function my_custom_block_insertion_handler( $block, $request, $creating ) {
    // 检查是否是新创建的区块
    if ( $creating ) {
        // 检查是否是段落区块
        if ( 'core/paragraph' === $block->blockName ) {
            // 获取段落内容
            $content = $block->innerContent[0][0]; // 注意 innerContent 的结构

            // 添加自定义文字
            $new_content = $content . ' 这是一段自动添加的文字。';

            // 更新区块内容 (这里需要更复杂的操作，因为区块对象是只读的，需要通过其他方式更新)
            // 这是一个简化的示例，实际情况下需要更新文章内容，而不是直接修改 $block 对象
            // 可以使用 update_post() 函数来更新文章内容，需要先获取文章 ID
            // 示例代码：
            // $post_id = $request['post']; // 假设请求中包含了 post ID
            // if ( $post_id ) {
            //     $post = get_post( $post_id );
            //     if ( $post ) {
            //         $blocks = parse_blocks( $post->post_content );
            //         foreach ( $blocks as &$b ) {
            //             if ( $b['attrs']['id'] === $block->attrs['id'] ) { // 假设区块有唯一的 ID
            //                 $b['innerHTML'] = $new_content;
            //                 $b['innerContent'] = array( array( $new_content ) );
            //                 break;
            //             }
            //         }
            //         $updated_content = serialize_blocks( $blocks );
            //         wp_update_post( array( 'ID' => $post_id, 'post_content' => $updated_content ) );
            //     }
            // }

            error_log('段落区块插入了，添加了自定义文字'); // 输出到错误日志，方便调试
        }
    }
}

代码解释：

1. add_action( 'rest_after_insert_block', 'my_custom_block_insertion_handler', 10, 3 );：这行代码将我们的自定义函数 my_custom_block_insertion_handler 挂载到 rest_after_insert_block 钩子上。

   • 10：优先级，数字越小优先级越高，表示我们的函数会在其他函数之前执行。
   • 3：参数数量，表示我们的函数接收三个参数（$block, $request, $creating）。

2. my_custom_block_insertion_handler( $block, $request, $creating )：这是我们的自定义函数，它接收三个参数：

   • $block：插入的区块对象。
   • $request：REST API 请求对象。
   • $creating：一个布尔值，表示是否是新创建的区块。

3. if ( $creating )：我们只在新创建区块时才执行我们的逻辑。

4. if ( 'core/paragraph' === $block->blockName )：我们只在插入段落区块时才执行我们的逻辑。

5. $content = $block->innerContent[0][0];：获取段落内容。注意，$block->innerContent 的结构可能比较复杂，需要根据实际情况调整。

6. $new_content = $content . ' 这是一段自动添加的文字。';：添加自定义文字。

7. 更新区块内容 (重要)：

   请注意，上面的代码中更新区块内容的部分只是一个简化的示例。 实际上，由于 $block 对象是只读的，你不能直接修改它。你需要通过其他方式来更新文章内容，比如使用 update_post() 函数。

   正确的方法是：

   1. 获取文章 ID： 从 $request 对象中获取文章 ID。
   2. 获取文章内容： 使用 get_post() 函数获取文章内容。
   3. 解析文章内容： 使用 parse_blocks() 函数将文章内容解析成区块数组。
   4. 找到目标区块： 遍历区块数组，找到与当前插入的区块匹配的区块（可以通过区块的 ID 或其他属性来匹配）。
   5. 修改区块内容： 修改目标区块的 innerHTML 和 innerContent 属性。
   6. 序列化区块数组： 使用 serialize_blocks() 函数将区块数组序列化成文章内容。
   7. 更新文章内容： 使用 wp_update_post() 函数更新文章内容。

   上面代码中的注释部分提供了更详细的示例代码，你可以参考它来实现正确的区块内容更新。

8. error_log('段落区块插入了，添加了自定义文字');：将日志信息输出到错误日志，方便调试。

Part 5: 调试技巧：让你的代码跑起来

调试 WordPress 钩子可能会有点棘手，但掌握一些技巧可以事半功倍：

• 使用 error_log() 函数： 在你的钩子函数中添加 error_log() 函数，将一些关键信息输出到错误日志，方便你查看代码的执行情况。
• 使用调试工具： 可以使用一些 WordPress 调试插件，比如 Query Monitor、Debug Bar 等，它们可以帮助你查看钩子的执行情况、数据库查询等等。
• 使用断点调试： 如果你使用的是 IDE，可以使用断点调试功能，一步一步地执行你的代码，查看变量的值，找出问题所在。

Part 6: 钩子的参数：玩转 $block 和 $request

咱们再深入了解一下钩子的参数 $block 和 $request，它们包含了大量的信息，可以让你做更多的事情。

$block 对象：

$block 对象是 WP_Block 类的实例，它包含了插入的区块的所有信息。常用的属性包括：

属性	描述
blockName	区块的名称，比如 'core/paragraph'、'core/image' 等等。
attrs	区块的属性，是一个数组，包含了区块的所有属性，比如段落的文本对齐方式、图片的 URL 等等。
innerHTML	区块的 HTML 内容，包含了区块的所有 HTML 标签和内容。
innerContent	一个多维数组，包含了区块的内部内容。对于简单的区块，它可能只包含一个元素，但对于复杂的区块，比如 Columns 区块，它可能包含多个元素，每个元素又是一个区块对象。这个属性的结构比较复杂，需要根据实际情况进行分析。通常，你可以使用 print_r() 或 var_dump() 函数来查看它的结构。
innerBlocks	一个区块对象的数组，代表该区块内部包含的子区块。例如，一个 Columns 区块会包含两个 Column 区块作为其 innerBlocks。这个属性对于处理嵌套区块非常有用。

$request 对象：

$request 对象是 WP_REST_Request 类的实例，它包含了 REST API 请求的所有信息。常用的方法包括：

方法	描述
get_params()	获取所有请求参数，返回一个数组。
get_param( $param )	获取指定名称的请求参数，如果参数不存在，则返回 null。
get_headers()	获取所有请求头，返回一个数组。
get_header( $header )	获取指定名称的请求头，如果请求头不存在，则返回 null。
get_method()	获取请求方法，比如 'GET'、'POST'、'PUT'、'DELETE' 等等。

通过 $block 和 $request 对象，你可以获取到足够的信息，来做你想做的任何事情。

Part 7: 注意事项：避免踩坑

在使用 rest_after_insert_block() 钩子时，有一些需要注意的地方，可以避免你踩坑：

• 性能问题： 钩子函数会在每次插入区块时都执行，如果你的函数逻辑比较复杂，可能会影响编辑器的性能。所以，尽量让你的函数执行效率高一些，避免不必要的计算。
• 安全性问题： 钩子函数可以访问 WordPress 的所有数据，包括敏感数据。所以，要确保你的函数是安全的，避免被恶意利用。
• 版本兼容性： rest_after_insert_block() 钩子是在 WordPress 5.5 版本引入的，如果你的插件需要兼容更早的版本，需要做一些兼容性处理。
• 区块更新： 前面已经提到，直接修改 $block 对象是无效的。你需要通过 update_post() 函数来更新文章内容。

总结：

rest_after_insert_block() 钩子是一个强大的工具，可以让你在区块插入后执行自定义逻辑。通过理解钩子的原理、掌握调试技巧、注意一些坑点，你就可以充分利用这个钩子，为 WordPress 编辑器添加更多功能。

好了，今天的讲座就到这里。希望大家有所收获！下次再见！