深入理解 WordPress `rest_after_insert_block` 钩子源码：在区块插入后执行自定义逻辑。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位观众老爷，早上好！今天咱们来聊聊 WordPress 里的一个“幕后英雄”—— rest_after_insert_block 钩子。这哥们儿虽然不像 the_content 那么抛头露面，但关键时刻也能帮咱们干不少事儿。

准备好了吗？咱们这就开车，深入了解一下它。

一、钩子是个啥？为啥我们需要它？

首先，咱得明白钩子是个啥玩意儿。你可以把它想象成 WordPress 这辆大卡车上的预留挂钩。 WordPress 在执行某些特定操作的时候，会检查这些挂钩上有没有挂着东西。如果有，就顺便执行一下挂在上面的代码。

rest_after_insert_block 钩子，顾名思思义，就是在通过 REST API 插入一个区块之后执行的。为啥我们需要它？因为有些时候，区块插入之后，我们可能需要做一些额外的事情，比如：

更新区块的属性： 插入后，我们可能需要根据某些条件，动态地修改区块的某些属性。
触发其他动作： 比如发送通知、更新缓存等等。
进行数据同步： 如果你的区块和外部数据源有联动，可能需要在插入后同步数据。
自定义验证: 确保插入的区块符合某种特定的规则。

总之，这个钩子给了我们一个在区块插入后“动手脚”的机会。

二、 rest_after_insert_block 钩子的参数和返回值

rest_after_insert_block 钩子接收三个参数：

$block (WP_Block): 插入的区块对象。包含了区块的所有信息，比如区块类型、属性等等。
$request (WP_REST_Request): 原始的 REST 请求对象。通过它可以获取请求的参数、头部信息等等。
$response (WP_REST_Response): REST API 的响应对象。我们可以修改这个对象，来改变 API 的返回值。

返回值：

默认情况下，这个钩子不需要返回值。但是，如果你想修改 API 的响应，可以修改 $response 对象，然后返回它。

咱用一个表格来总结一下：

参数	类型	描述
`$block`	`WP_Block`	插入的区块对象，包含了区块的类型、属性等信息。
`$request`	`WP_REST_Request`	原始的 REST 请求对象，通过它可以获取请求的参数、头部信息等。
`$response`	`WP_REST_Response`	REST API 的响应对象，我们可以修改这个对象，来改变 API 的返回值。
返回值	(mixed)	默认情况下，不需要返回值。如果需要修改 API 的响应，返回 `$response` 对象。

三、 rest_after_insert_block 钩子的源码分析

要理解这个钩子，咱得扒一扒 WordPress 的源码。这个钩子的触发点位于 wp-includes/rest-api/endpoints/class-wp-rest-blocks-controller.php 文件中的 insert_item() 方法里。

咱们简化一下代码，看看关键的部分：

// ... (省略前面的代码)

$block = new WP_Block( $parsed_block );

/**
 * Fires after a block has been inserted via the REST API.
 *
 * @since 5.0.0
 *
 * @param WP_Block        $block    Inserted block object.
 * @param WP_REST_Request $request  The request sent to the API.
 * @param WP_REST_Response $response The response from the API.
 */
do_action( 'rest_after_insert_block', $block, $request, $response );

// ... (省略后面的代码)

看到了吧？ WordPress 使用 do_action() 函数触发了这个钩子。 do_action() 函数的作用就是执行所有挂在这个钩子上的函数。

四、实战演练：利用 rest_after_insert_block 钩子修改区块属性

光说不练假把式，咱们来写一段代码，演示一下如何利用 rest_after_insert_block 钩子修改区块的属性。

假设我们有一个自定义的区块，叫做 my-custom/block，它有一个属性叫做 backgroundColor。我们希望在区块插入后，如果 backgroundColor 属性为空，就给它设置一个默认值 #f0f0f0。

<?php
/**
 * 钩子函数，在区块插入后执行。
 *
 * @param WP_Block        $block    插入的区块对象。
 * @param WP_REST_Request $request  REST 请求对象。
 * @param WP_REST_Response $response REST 响应对象。
 */
function my_custom_block_set_default_background_color( $block, $request, $response ) {
    // 检查是否是我们的自定义区块。
    if ( 'my-custom/block' === $block->name ) {
        // 检查 backgroundColor 属性是否为空。
        if ( empty( $block->attributes['backgroundColor'] ) ) {
            // 设置默认的 backgroundColor 属性。
            $block->attributes['backgroundColor'] = '#f0f0f0';

            // 更新响应对象，确保前端能拿到更新后的属性。
            $response_data = $response->get_data();
            $response_data['block'] = $block;
            $response->set_data( $response_data );
        }
    }

    // 返回响应对象。
    return $response;
}

// 将我们的函数挂载到 rest_after_insert_block 钩子上。
add_action( 'rest_after_insert_block', 'my_custom_block_set_default_background_color', 10, 3 );

这段代码做了以下几件事：

定义了一个钩子函数 my_custom_block_set_default_background_color()： 这个函数接收三个参数，分别是 $block、$request 和 $response。
检查是否是我们的自定义区块： 通过 $block->name 属性判断。
检查 backgroundColor 属性是否为空： 使用 empty() 函数判断。
设置默认的 backgroundColor 属性： 直接修改 $block->attributes['backgroundColor'] 的值。
更新响应对象： 这一步非常重要！我们需要将更新后的 $block 对象放回 $response 对象中，这样前端才能拿到最新的属性值。
返回响应对象： 将修改后的 $response 对象返回。
将函数挂载到 rest_after_insert_block 钩子上： 使用 add_action() 函数。 10 是优先级，3 是参数个数。

重点： 更新响应对象是关键！否则，前端拿到的还是旧的属性值。

五、高级用法：利用 WP_REST_Request 对象获取请求参数

有时候，我们需要根据 REST 请求的参数来修改区块的属性。这时候，就需要用到 $request 对象了。

比如，我们希望根据请求中传递的 theme 参数，来设置区块的背景颜色。

<?php
/**
 * 钩子函数，在区块插入后执行。
 *
 * @param WP_Block        $block    插入的区块对象。
 * @param WP_REST_Request $request  REST 请求对象。
 * @param WP_REST_Response $response REST 响应对象。
 */
function my_custom_block_set_background_color_by_theme( $block, $request, $response ) {
    // 检查是否是我们的自定义区块。
    if ( 'my-custom/block' === $block->name ) {
        // 获取 theme 参数。
        $theme = $request->get_param( 'theme' );

        // 根据 theme 参数设置背景颜色。
        switch ( $theme ) {
            case 'dark':
                $background_color = '#333';
                break;
            case 'light':
                $background_color = '#fff';
                break;
            default:
                $background_color = '#f0f0f0';
        }

        // 设置背景颜色属性。
        $block->attributes['backgroundColor'] = $background_color;

        // 更新响应对象。
        $response_data = $response->get_data();
        $response_data['block'] = $block;
        $response->set_data( $response_data );
    }

    // 返回响应对象。
    return $response;
}

// 将我们的函数挂载到 rest_after_insert_block 钩子上。
add_action( 'rest_after_insert_block', 'my_custom_block_set_background_color_by_theme', 10, 3 );

这段代码的关键在于使用 $request->get_param( 'theme' ) 获取了请求中的 theme 参数。然后，根据 theme 参数的值，设置了不同的背景颜色。

六、错误处理和调试

在使用 rest_after_insert_block 钩子的时候，难免会遇到一些错误。以下是一些常见的错误和调试技巧：

钩子函数没有执行： 检查 add_action() 函数是否正确调用，优先级是否设置正确，以及钩子函数是否定义在正确的文件中。
属性没有更新： 检查是否正确更新了 $response 对象。
代码报错： 使用 error_log() 函数将错误信息写入日志文件，方便调试。

七、注意事项

性能问题： rest_after_insert_block 钩子会在每次区块插入后执行，因此要避免在钩子函数中执行耗时的操作，以免影响性能。
安全性： 对 REST 请求的参数进行验证和过滤，防止恶意攻击。

八、总结

rest_after_insert_block 钩子是一个非常强大的工具，可以让我们在区块插入后执行自定义逻辑，实现各种各样的功能。希望通过今天的讲解，大家能够对它有一个更深入的理解，并在实际开发中灵活运用。

记住，要善用 WP_Block 和 WP_REST_Request 对象，并时刻注意性能和安全问题。

好了，今天的讲座就到这里。感谢大家的收听！如果有什么问题，欢迎在评论区留言。

祝大家编程愉快！

发表回复 取消回复

发表回复取消回复