WordPress插件开发：设置API和选项API

WordPress

类型：CMS系统

简介：一款开源的内容管理系统（CMS），用于构建和管理网站。

百科词条 访问网站

WordPress提供了两个核心API——设置API和选项API，前者主要用于简化表单创建和数据管理，后者侧重于为我们提供一种简单的键/值系统来管理数据。接下来将主要介绍在WordPress插件开发过程中设置API和选项API的使用方法。

一、WordPress设置API介绍

设置API是WordPress 2.7后增加的功能，可以实现半自动管理含有设置表单的后台页面，包括自定义页面、页面的分节和表单字段。还可以同时添加新设置页面和与其中的表单字段，也可以添加设置分节和表单字段到现有页面。

虽然开发者仍需要手动注册和验证表单字段，但是设置API为我们避免了管理底层选项的大量复杂调试。

使用设置API时，接收表单提交的wp-admin/options.php页面会进行相当严格的权限检查。用户具有manage_options能力才能保存数据。

使用设置API的优势如下：

可以让自定义设置页面和WordPress默认管理界面视觉上呈现更加一致性，使用设置API后自定义页面的风格会随着WordPress默认风格一起更新，而不会停留在很久之前的老旧页面。

由于设置API是WordPress核心的一部分，任何更新都将自动更新我们的设置页面，如果我们创建了自己的设置页面，WordPress的内核更新可能会破坏我们的自定义设置。会有越来越多的开发者测试和维护这些设置API代码，所以会更加稳定。

WordPress设置API的主要功能：

• 处理表单提交：让WordPress处理并存储$_POST提交；
• 包括安全措施：可以让我们获得额外的安全措施，如随机数验证；
• 清理数据：可以和WordPress其他部分一样，自动为我们清理数据，以确保提交的字符串可以安全的使用。

设置API函数参考：

设置注册/注销注册：

• register_setting()
• unregister_setting()

添加字段/分节：

• add_settings_section()
• add_settings_field()

选项表单渲染：

• settings_fields()
• do_settings_sections()
• do_settings_fields()

错误信息：

• add_settings_error()
• get_settings_errors()
• settings_errors()

二、WordPress设置API的使用方法

1、添加设置

使用register_setting()函数可以定义一个新的设置，例如会在 {$wpdb->prefix}_options数据表中插入记录，使用 add_settings_section()可以在现有设置页面上添加新分节；使用add_settings_field()可以将新字段添加到现有的分节上面。

register_setting(
string $option_group, 
string $option_name, 
callable $sanitize_callback = ''
);

2、添加分节

分节是在WordPress设置上看到的附有共享标题的设置组，可以在插件中向现有的设置页面添加新分节，而不是创建一个新页面。这可以让我们的插件更容易维护，并降低用户的学习和使用成本。

add_settings_section(
string $id, 
string $title, 
callable $callback, 
string $page
);

完整实例：

<?php
function zzbaike_settings_init(){
// 为 阅读 页面注册新设置
register_setting('reading', 'zzbaike_setting_name');

// 在阅读页面上注册新分节
add_settings_section(
'zzbaike_settings_section',
'zzbaike Settings Section',
'zzbaike_settings_section_cb',
'reading'
);

// 阅读页面中，在 the zzbaike_settings_section 分节上注册新设置
add_settings_field(
'zzbaike_settings_field',
'zzbaike Setting',
'zzbaike_settings_field_cb',
'reading',
'zzbaike_settings_section'
);
}

/**
* 注册 zzbaike_settings_init 到 admin_init Action 钩子
*/
add_action('admin_init', 'zzbaike_settings_init');


/**
* 回调函数
*/
// 分节内容回调
function zzbaike_settings_section_cb() {
echo '<p>zzbaike Section Introduction.</p>';
}

// 字段内容回调
function zzbaike_settings_field_cb() {
// 获取我们使用 register_setting() 注册的字段的值
$setting = get_option('zzbaike_setting_name');
// 输出字段
?>
<input type=text name=zzbaike_setting_name value=<?php echo isset( $setting ) ? esc_attr( $setting ) : ''; ?>>
<?php
}

3、获取设置

get_option()函数可以获取设置数据：

get_option(
string $option,
mixed $default = false
);

实例：

// 获取我们上面使用 register_setting() 注册的选项值
$setting = get_option('zzbaike_setting_name');

三、WordPress选项API简介

选项API比设置API要古老些，它是WordPress 1.0就引入的功能，可以让我们添加、获取、更新和删除WordPress选项，结合设置API，我们可以控制设置页面中的自定义选项。

选项保存位置在{$wpdb->prefix}_options的数据表中，其中$wpdb->prefix由wp-config.php配置文件中的$table_prefix变量定义。具体保存方式可以以单个值或者数组的形式存储在WordPress数据库中。

选项API分为单个值和数组的形式，其中保存为单个值的时候，选项值为单个字符串、整数等；保存为数组时，选项值为一个数组。

单个值：

<?php
// add a new option
add_option('zzbaike_custom_option', 'hello world!');
// get an option
$option = get_option('zzbaike_custom_option');

数组：

<?php
// array of options
$data_r = ['title' => 'hello world!', 1, false];
// add a new option
add_option('zzbaike_custom_option', $data_r);
// get an option
$options_r = get_option('zzbaike_custom_option');
// output the title
echo esc_html($options_r['title']);

如果我们需要保存大量选项，把这些选项保存为数组，对性能提升可能会有帮助。

选项API函数参考：

添加选项：

• add_option()
• add_site_option()

获取选项：

• get_option()
• get_site_option()

更新选项：

• update_option()
• update_site_option()

删除选项：

• delete_option()
• delete_site_option()

四、WordPress选项API的使用方法

WordPress插件开发中，如果需要用到选项API，可以参考以下创建自定义设置页面的一个完整示例。

<?php
/**
* @internal never define functions inside callbacks.
* these functions could be run multiple times; this would result in a fatal error.
*/

/**
* custom option and settings
*/
function zzbaike_settings_init() {
// register a new setting for zzbaike page
register_setting( 'zzbaike', 'zzbaike_options' );

// register a new section in the zzbaike page
add_settings_section(
'zzbaike_section_developers',
__( 'The Matrix has you.', 'zzbaike' ),
'zzbaike_section_developers_cb',
'zzbaike'
);

// register a new field in the zzbaike_section_developers section, inside the zzbaike page
add_settings_field(
'zzbaike_field_pill', // as of WP 4.6 this value is used only internally
// use $args' label_for to populate the id inside the callback
__( 'Pill', 'zzbaike' ),
'zzbaike_field_pill_cb',
'zzbaike',
'zzbaike_section_developers',
[
'label_for' => 'zzbaike_field_pill',
'class' => 'zzbaike_row',
'zzbaike_custom_data' => 'custom',
]
);
}

/**
* register our zzbaike_settings_init to the admin_init action hook
*/
add_action( 'admin_init', 'zzbaike_settings_init' );

/**
* custom option and settings:
* callback functions
*/

// developers section cb

// section callbacks can accept an $args parameter, which is an array.
// $args have the following keys defined: title, id, callback.
// the values are defined at the add_settings_section() function.
function zzbaike_section_developers_cb( $args ) {
?>
<p id=<?php echo esc_attr( $args[ 'id' ] ); ?>><?php esc_html_e( 'Follow the white rabbit.', 'zzbaike' ); ?></p>
<?php
}

// pill field cb

// field callbacks can accept an $args parameter, which is an array.
// $args is defined at the add_settings_field() function.
// wordpress has magic interaction with the following keys: label_for, class.
// the label_for key value is used for the for attribute of the <label>.
// the class key value is used for the class attribute of the <tr> containing the field.
// you can add custom key value pairs to be used inside your callbacks.
function zzbaike_field_pill_cb( $args ) {
// get the value of the setting we've registered with register_setting()
$options = get_option( 'zzbaike_options' );
// output the field
?>
<select id=<?php echo esc_attr( $args[ 'label_for' ] ); ?>
data-custom=<?php echo esc_attr( $args[ 'zzbaike_custom_data' ] ); ?>
name=zzbaike_options[<?php echo esc_attr( $args[ 'label_for' ] ); ?>]
>
<option value=red <?php echo isset( $options[ $args[ 'label_for' ] ] ) ? ( selected( $options[ $args[ 'label_for' ] ], 'red', false ) ) : ( '' ); ?>>
<?php esc_html_e( 'red pill', 'zzbaike' ); ?>
</option>
<option value=blue <?php echo isset( $options[ $args[ 'label_for' ] ] ) ? ( selected( $options[ $args[ 'label_for' ] ], 'blue', false ) ) : ( '' ); ?>>
<?php esc_html_e( 'blue pill', 'zzbaike' ); ?>
</option>
</select>
<p class=description>
<?php esc_html_e( 'You take the blue pill and the story ends. You wake in your bed and you believe whatever you want to believe.', 'zzbaike' ); ?>
</p>
<p class=description>
<?php esc_html_e( 'You take the red pill and you stay in Wonderland and I show you how deep the rabbit-hole goes.', 'zzbaike' ); ?>
</p>
<?php
}

/**
* top level menu
*/
function zzbaike_options_page() {
// add top level menu page
add_menu_page(
'zzbaike',
'zzbaike Options',
'manage_options',
'zzbaike',
'zzbaike_options_page_html'
);
}

/**
* register our zzbaike_options_page to the admin_menu action hook
*/
add_action( 'admin_menu', 'zzbaike_options_page' );

/**
* top level menu:
* callback functions
*/
function zzbaike_options_page_html() {
// check user capabilities
if ( ! current_user_can( 'manage_options' ) ) {
return;
}

// add error/update messages

// check if the user have submitted the settings
// wordpress will add the settings-updated $_GET parameter to the url
if ( isset( $_GET[ 'settings-updated' ] ) ) {
// add settings saved message with the class of updated
add_settings_error( 'zzbaike_messages', 'zzbaike_message', __( 'Settings Saved', 'zzbaike' ), 'updated' );
}

// show error/update messages
settings_errors( 'zzbaike_messages' );
?>
<div class=wrap>
<h1><?php echo esc_html( get_admin_page_title() ); ?></h1>
<form action=options.php method=post>
<?php
// output security fields for the registered setting zzbaike
settings_fields( 'zzbaike' );
// output setting sections and their fields
// (sections are registered for zzbaike, each field is registered to a specific section)
do_settings_sections( 'zzbaike' );
// output save settings button
submit_button( 'Save Settings' );
?>
</form>
</div>
<?php
}

以上代码中添加了一个名为zzbaike的顶级菜单，注册了一个名为 zzbaike_options的选项，并使用设置API和选项API执行了一个CRUD增查改删操作。