_wp_customize_include()
云策文档标注
概述
_wp_customize_include() 函数用于在特定条件下包含并实例化 WP_Customize_Manager 类,以初始化 WordPress 自定义器。它通常在访问 customize.php 管理页面或请求中包含特定参数时触发。
关键要点
- 函数在 plugins_loaded 阶段加载,当访问 customize.php 页面、请求包含 wp_customize=on 参数或 customize_changeset_uuid 参数时触发。
- 通过检查 $_REQUEST 和 $_GET/$_POST 变量来确定是否应包含自定义器,并处理相关参数如 changeset_uuid、theme 等。
- 实例化 WP_Customize_Manager 时传递配置参数,包括 changeset_uuid、theme、messenger_channel、settings_previewed、autosaved 和 branching。
- 函数内部使用 sanitize_key() 和 wp_array_slice_assoc() 等辅助函数进行数据清理和提取。
代码示例
function _wp_customize_include() {
$is_customize_admin_page = ( is_admin() && 'customize.php' === basename( $_SERVER['PHP_SELF'] ) );
$should_include = (
$is_customize_admin_page
||
( isset( $_REQUEST['wp_customize'] ) && 'on' === $_REQUEST['wp_customize'] )
||
( ! empty( $_GET['customize_changeset_uuid'] ) || ! empty( $_POST['customize_changeset_uuid'] ) )
);
if ( ! $should_include ) {
return;
}
// 参数处理逻辑...
require_once ABSPATH . WPINC . '/class-wp-customize-manager.php';
$GLOBALS['wp_customize'] = new WP_Customize_Manager(
compact(
'changeset_uuid',
'theme',
'messenger_channel',
'settings_previewed',
'autosaved',
'branching'
)
);
}注意事项
- 函数在 wp_magic_quotes() 调用前执行,因此未使用 wp_unslash() 处理输入变量,但参数值通常不包含需要反斜杠的字符。
- settings_previewed 参数默认设置为 true 以支持向后兼容,但在 customize_save Ajax 操作中会设置为 false 以防止误保存。
- changeset_uuid 可能为 false,表示在 after_setup_theme 后确定,以重用现有更改集或生成新 UUID。
原文内容
Includes and instantiates the WP_Customize_Manager class.
Description
Loads the Customizer at plugins_loaded when accessing the customize.php admin page or when any request includes a wp_customize=on param or a customize_changeset param (a UUID). This param is a signal for whether to bootstrap the Customizer when WordPress is loading, especially in the Customizer preview or when making Customizer Ajax requests for widgets or menus.
Source
function _wp_customize_include() {
$is_customize_admin_page = ( is_admin() && 'customize.php' === basename( $_SERVER['PHP_SELF'] ) );
$should_include = (
$is_customize_admin_page
||
( isset( $_REQUEST['wp_customize'] ) && 'on' === $_REQUEST['wp_customize'] )
||
( ! empty( $_GET['customize_changeset_uuid'] ) || ! empty( $_POST['customize_changeset_uuid'] ) )
);
if ( ! $should_include ) {
return;
}
/*
* Note that wp_unslash() is not being used on the input vars because it is
* called before wp_magic_quotes() gets called. Besides this fact, none of
* the values should contain any characters needing slashes anyway.
*/
$keys = array(
'changeset_uuid',
'customize_changeset_uuid',
'customize_theme',
'theme',
'customize_messenger_channel',
'customize_autosaved',
);
$input_vars = array_merge(
wp_array_slice_assoc( $_GET, $keys ),
wp_array_slice_assoc( $_POST, $keys )
);
$theme = null;
$autosaved = null;
$messenger_channel = null;
/*
* Value false indicates UUID should be determined after_setup_theme
* to either re-use existing saved changeset or else generate a new UUID if none exists.
*/
$changeset_uuid = false;
/*
* Set initially to false since defaults to true for back-compat;
* can be overridden via the customize_changeset_branching filter.
*/
$branching = false;
if ( $is_customize_admin_page && isset( $input_vars['changeset_uuid'] ) ) {
$changeset_uuid = sanitize_key( $input_vars['changeset_uuid'] );
} elseif ( ! empty( $input_vars['customize_changeset_uuid'] ) ) {
$changeset_uuid = sanitize_key( $input_vars['customize_changeset_uuid'] );
}
// Note that theme will be sanitized via WP_Theme.
if ( $is_customize_admin_page && isset( $input_vars['theme'] ) ) {
$theme = $input_vars['theme'];
} elseif ( isset( $input_vars['customize_theme'] ) ) {
$theme = $input_vars['customize_theme'];
}
if ( ! empty( $input_vars['customize_autosaved'] ) ) {
$autosaved = true;
}
if ( isset( $input_vars['customize_messenger_channel'] ) ) {
$messenger_channel = sanitize_key( $input_vars['customize_messenger_channel'] );
}
/*
* Note that settings must be previewed even outside the customizer preview
* and also in the customizer pane itself. This is to enable loading an existing
* changeset into the customizer. Previewing the settings only has to be prevented
* here in the case of a customize_save action because this will cause WP to think
* there is nothing changed that needs to be saved.
*/
$is_customize_save_action = (
wp_doing_ajax()
&&
isset( $_REQUEST['action'] )
&&
'customize_save' === wp_unslash( $_REQUEST['action'] )
);
$settings_previewed = ! $is_customize_save_action;
require_once ABSPATH . WPINC . '/class-wp-customize-manager.php';
$GLOBALS['wp_customize'] = new WP_Customize_Manager(
compact(
'changeset_uuid',
'theme',
'messenger_channel',
'settings_previewed',
'autosaved',
'branching'
)
);
}
Changelog
| Version | Description |
|---|---|
| 3.4.0 | Introduced. |