函数文档

_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.