解析 WordPress `register_setting()` 函数源码：如何将设置选项与数据库中的 `wp_options` 表绑定。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位观众老爷们，晚上好！我是你们的老朋友，代码界的段子手，今天咱们来聊聊WordPress里一个看似简单，实则暗藏玄机的函数——register_setting()。别看它名字朴实无华，它的作用可是连接WordPress设置页面和数据库的桥梁，让你的选项安安稳稳地躺在wp_options表里。

准备好了吗？咱们这就开始一场源码解剖之旅！

一、初识register_setting()：这货是干啥的？

简单来说，register_setting()函数的作用就是注册一个设置，告诉WordPress：“嘿，哥们，我这有个设置，以后你得帮我管着，记得帮我存到数据库里，用户改了你也得记着！”。

它的基本语法如下：

register_setting( string $option_group, string $option_name, array $args = array() );

$option_group：选项组名，相当于给你的设置们分个组，方便管理。这个名字会在设置页面的URL中出现，所以最好起个有意义的名字。
$option_name：选项名，这是你真正要存到数据库里的选项的名字，也就是wp_options表里option_name字段的值。
$args：可选参数，可以设置一些额外的属性，比如数据清洗的回调函数。

举个栗子：

register_setting(
    'my_plugin_options', // 选项组名
    'my_plugin_setting', // 选项名
    array(
        'sanitize_callback' => 'my_plugin_sanitize_setting' // 数据清洗回调函数
    )
);

这段代码告诉WordPress：

有一个选项组叫做my_plugin_options。
在这个组里有一个选项叫做my_plugin_setting。
在保存这个选项之前，先用my_plugin_sanitize_setting函数清洗一下数据，确保数据安全。

二、深入源码：register_setting()的内心世界

光说不练假把式，咱们直接扒开register_setting()的源码，看看它到底做了些什么。

源码位于wp-includes/option.php文件中。为了方便阅读，我把关键部分摘出来：

function register_setting( $option_group, $option_name, $args = array() ) {
    global $new_whitelist_options;

    $new_whitelist_options[ $option_group ][ $option_name ] = true;

    add_action( 'admin_init', function() use ( $option_group, $option_name, $args ) {
        $sanitize_callback = isset( $args['sanitize_callback'] ) ? $args['sanitize_callback'] : '';

        if ( ! is_callable( $sanitize_callback ) && ! empty( $sanitize_callback ) ) {
            _doing_it_wrong(
                __FUNCTION__,
                sprintf(
                    /* translators: 1: sanitize_callback, 2: register_setting */
                    __( 'The %1$s argument must be a valid callback for the %2$s function.' ),
                    '<code>sanitize_callback</code>',
                    '<code>register_setting()</code>'
                ),
                '4.7.0'
            );
            $sanitize_callback = '';
        }

        register_setting_callback( $option_group, $option_name, $sanitize_callback );

        /**
         * Fires after a setting has been registered.
         *
         * @since 4.2.0
         *
         * @param string $option_group Option group.
         * @param string $option_name  Option name.
         * @param array  $args         Arguments passed to register_setting().
         */
        do_action( 'register_setting', $option_group, $option_name, $args );
    } );
}

这段代码主要做了三件事：

global $new_whitelist_options;：声明一个全局变量$new_whitelist_options，这个变量用于存储所有注册的选项组和选项名。你可以把它理解成一个“白名单”，只有在这个白名单里的选项才能被保存到数据库。
$new_whitelist_options[ $option_group ][ $option_name ] = true;：将当前注册的选项组和选项名添加到$new_whitelist_options白名单中。
add_action( 'admin_init', ... );：注册一个admin_init钩子，这意味着当WordPress后台初始化时，会执行这个匿名函数。这个匿名函数又做了两件事：
- 检查sanitize_callback是否是一个有效的回调函数。如果不是，会抛出一个_doing_it_wrong警告，并清空sanitize_callback。
- 调用register_setting_callback()函数，真正注册设置。
- 触发 register_setting 钩子。

看到这里，你可能会问：“register_setting_callback()又是啥玩意？” 别急，咱们继续往下看。

三、register_setting_callback()：幕后英雄

register_setting_callback()函数才是真正将设置和数据库绑定的关键。它的源码如下：

function register_setting_callback( $option_group, $option_name, $sanitize_callback = '' ) {
    global $wp_settings_fields, $wp_settings_sections;

    // Add the option to the settings fields array.
    add_settings_field(
        $option_name,
        '',
        '__return_empty_string',
        $option_group,
        'default'
    );

    // Register the option with the settings API.
    add_action( 'admin_init', function() use ( $option_name, $option_group, $sanitize_callback ) {
        register_meta( 'option', $option_name, array(
            'type'              => 'string', // Default to string
            'description'       => 'Option value',
            'single'            => true,
            'sanitize_callback' => $sanitize_callback,
            'show_in_rest'      => false,
        ) );

        add_filter( "pre_update_option_{$option_name}", function( $value ) use ( $option_name, $sanitize_callback ) {
            if ( ! empty( $sanitize_callback ) && is_callable( $sanitize_callback ) ) {
                $value = call_user_func( $sanitize_callback, $value );
            }
            return $value;
        });
    } );

}

这个函数做了三件事：

add_settings_field(...)：将选项添加到设置字段数组中。这个函数主要用于在设置页面上显示选项，这里只是简单地添加了一个空的设置字段，因为我们更关心的是如何保存选项到数据库。
register_meta(...)：使用 register_meta 注册元数据。这个步骤至关重要，它告诉WordPress这是一个选项，并且需要进行元数据处理。它定义了选项的类型（默认为字符串），描述，以及最关键的 sanitize_callback。
add_filter( "pre_update_option_{$option_name}", ... )：注册一个pre_update_option_{$option_name}过滤器。这个过滤器会在更新选项之前被调用，用于对选项值进行处理。在这里，我们判断sanitize_callback是否存在，如果存在，就调用它来清洗数据，确保数据的安全性和有效性。

四、wp_options表：选项的家

经过上面的注册过程，当你在设置页面修改了选项并保存时，WordPress就会将选项值保存到wp_options表中。

wp_options表是WordPress的核心表之一，用于存储各种各样的配置信息，包括主题设置、插件设置、站点信息等等。

wp_options表的主要字段包括：

字段名	数据类型	描述
`option_id`	bigint(20)	选项ID，自增主键。
`option_name`	varchar(191)	选项名，用于唯一标识一个选项。这就是我们在`register_setting()`函数中定义的`$option_name`。
`option_value`	longtext	选项值，存储选项的具体内容。WordPress会自动对这个值进行序列化和反序列化，所以你可以存储各种类型的数据，比如字符串、数组、对象等等。
`autoload`	varchar(20)	是否自动加载。如果设置为`yes`，则WordPress会在每次页面加载时自动加载这个选项，这可以提高性能，但也会增加内存消耗。如果设置为`no`，则只有在需要时才会加载这个选项。

当你调用update_option( $option_name, $option_value )函数时，WordPress会：

首先检查wp_options表中是否存在option_name为$option_name的记录。
如果存在，则更新option_value字段的值为$option_value。
如果不存在，则插入一条新的记录，option_name为$option_name，option_value为$option_value。

五、数据清洗：sanitize_callback的重要性

在保存选项之前，对数据进行清洗是非常重要的，可以防止恶意代码注入，确保数据的安全性和有效性。

sanitize_callback参数就是用于指定数据清洗的回调函数。这个回调函数接收一个参数，即要保存的选项值，然后对这个值进行处理，最后返回处理后的值。

WordPress提供了一些内置的数据清洗函数，比如：

sanitize_text_field()：过滤文本字段，移除HTML标签和编码特殊字符。
sanitize_email()：过滤Email地址，确保Email地址的格式正确。
absint()：将值转换为正整数。
wp_kses_post(): 允许有限的 HTML 标记和属性。

你也可以自定义数据清洗函数，比如：

function my_plugin_sanitize_setting( $input ) {
    // 确保输入的是一个有效的颜色值
    if ( preg_match( '/^#[a-f0-9]{6}$/i', $input ) ) {
        return $input;
    } else {
        return '#FFFFFF'; // 默认白色
    }
}

这个函数检查输入是否是一个有效的十六进制颜色值，如果是，则返回输入值，否则返回默认的白色值。

六、总结：register_setting()的完整流程

现在，让我们把上面的内容串起来，总结一下register_setting()的完整流程：

调用register_setting( $option_group, $option_name, $args )函数。
register_setting()函数将选项组和选项名添加到$new_whitelist_options白名单中。
register_setting()函数注册一个admin_init钩子。
当WordPress后台初始化时，admin_init钩子被触发。
admin_init钩子中的匿名函数被执行。
匿名函数调用register_setting_callback( $option_group, $option_name, $sanitize_callback )函数。
register_setting_callback()函数使用add_settings_field()添加一个空的设置字段。
register_setting_callback()函数使用 register_meta() 注册元数据。
register_setting_callback()函数注册一个pre_update_option_{$option_name}过滤器。
当你在设置页面修改了选项并保存时，pre_update_option_{$option_name}过滤器被触发。
过滤器中的匿名函数被执行。
匿名函数调用sanitize_callback函数对选项值进行清洗。
WordPress将清洗后的选项值保存到wp_options表中。

七、高级用法：选项组的妙用

$option_group参数不仅仅是用来分组的，它还有其他的妙用。

你可以使用$option_group参数来：

批量更新选项：通过update_option()函数更新选项时，只需要指定$option_name即可，WordPress会自动找到对应的选项组。
批量删除选项：通过delete_option()函数删除选项时，只需要指定$option_name即可，WordPress会自动找到对应的选项组。
创建自定义设置页面：你可以使用settings_fields( $option_group )函数来输出选项组中的所有选项，从而创建一个自定义的设置页面。

八、注意事项：踩坑指南

在使用register_setting()函数时，有一些需要注意的地方，避免掉坑里：

$option_name必须是唯一的：同一个$option_name只能注册一次，否则会导致冲突。
sanitize_callback必须是一个有效的回调函数：如果sanitize_callback不是一个有效的回调函数，WordPress会抛出一个_doing_it_wrong警告，并忽略sanitize_callback。
不要在admin_init钩子之前调用register_setting()函数：register_setting()函数需要在admin_init钩子之后调用，否则会导致注册失败。
记住要验证和转义数据：始终验证和转义通过设置 API 提交的数据，以防止安全漏洞。

九、实战演练：做一个简单的插件设置

现在，让我们来做一个简单的插件设置，巩固一下所学的知识。

假设我们要创建一个插件，允许用户自定义插件的标题和背景颜色。

首先，创建一个插件文件my-plugin.php，并添加以下代码：

<?php
/**
 * Plugin Name: My Plugin
 * Description: A simple plugin for demonstration purposes.
 * Version: 1.0.0
 */

// 注册设置
add_action( 'admin_init', 'my_plugin_register_settings' );
function my_plugin_register_settings() {
    register_setting(
        'my_plugin_options', // 选项组名
        'my_plugin_title',   // 选项名
        array( 'sanitize_callback' => 'sanitize_text_field' ) // 数据清洗回调函数
    );
    register_setting(
        'my_plugin_options', // 选项组名
        'my_plugin_background_color', // 选项名
        array( 'sanitize_callback' => 'my_plugin_sanitize_color' ) // 数据清洗回调函数
    );
}

// 自定义颜色清洗函数
function my_plugin_sanitize_color( $input ) {
    if ( preg_match( '/^#[a-f0-9]{6}$/i', $input ) ) {
        return $input;
    } else {
        return '#FFFFFF'; // 默认白色
    }
}

// 添加菜单项
add_action( 'admin_menu', 'my_plugin_add_menu' );
function my_plugin_add_menu() {
    add_options_page(
        'My Plugin Settings', // 页面标题
        'My Plugin',         // 菜单标题
        'manage_options',      // 权限
        'my-plugin-settings',  // 菜单slug
        'my_plugin_settings_page' // 回调函数
    );
}

// 设置页面回调函数
function my_plugin_settings_page() {
    ?>
    <div class="wrap">
        <h1>My Plugin Settings</h1>
        <form method="post" action="options.php">
            <?php
            settings_fields( 'my_plugin_options' ); // 输出选项组的隐藏字段
            do_settings_sections( 'my-plugin-settings' ); // 输出设置区域
            submit_button(); // 输出提交按钮
            ?>
            <table class="form-table">
                <tr valign="top">
                    <th scope="row">Plugin Title</th>
                    <td>
                        <input type="text" name="my_plugin_title" value="<?php echo esc_attr( get_option( 'my_plugin_title' ) ); ?>" />
                    </td>
                </tr>
                <tr valign="top">
                    <th scope="row">Background Color</th>
                    <td>
                        <input type="text" name="my_plugin_background_color" value="<?php echo esc_attr( get_option( 'my_plugin_background_color' ) ); ?>" />
                    </td>
                </tr>
            </table>
        </form>
    </div>
    <?php
}

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

注册了两个设置：my_plugin_title和my_plugin_background_color，分别用于存储插件的标题和背景颜色。
定义了一个自定义的颜色清洗函数my_plugin_sanitize_color()，用于验证颜色值的有效性。
添加了一个菜单项，用于显示插件的设置页面。
创建了一个设置页面，用于显示插件的设置表单。

将这个插件上传到WordPress，激活插件，然后在后台的“设置”菜单下找到“My Plugin”菜单，点击进入设置页面，你就可以修改插件的标题和背景颜色了。

十、总结

register_setting()函数是WordPress连接设置页面和数据库的关键，掌握它可以让你更好地管理插件和主题的设置，为用户提供更灵活的自定义选项。

今天的讲座就到这里，希望大家有所收获。记住，代码的世界是充满乐趣的，只要你敢于探索，就能发现更多的惊喜！下次再见！

发表回复 取消回复

发表回复取消回复