云策 WordPress 开发者社区

函数文档

wp_get_global_settings()

查看官方原文 ↗
💡 云策文档标注

概述

wp_get_global_settings() 函数用于获取合并了核心、主题和用户数据的全局设置。它支持通过路径参数检索特定设置，并利用缓存机制优化性能。

关键要点

  • 函数返回合并后的设置数组或单个设置值，参数 $path 可选，用于指定检索路径。
  • 参数 $context 可选，包含 block_name 和 origin 等元数据，影响数据来源和缓存行为。
  • 内部实现基于 WP_Theme_JSON_Resolver 获取合并数据，并使用非持久化缓存（组为 'theme_json'）以提高效率。
  • 在开发模式为 'theme' 时忽略缓存，以支持主题开发工作流。

代码示例

// 获取所有设置
$settings = wp_get_global_settings();
var_dump($settings);

// 检索主题定义的渐变设置
$gradients = wp_get_global_settings( array( 'color', 'gradients', 'theme' ) );

// 检索间距比例设置
$spacingScale = wp_get_global_settings( array( 'spacing', 'spacingScale' ) );

注意事项

  • 缓存机制设计为非持久化，以确保 theme.json 数据在动态修改（如通过钩子）后保持最新。
  • origin 参数有效值为 'all'（默认，包含核心、主题和用户）或 'base'（仅核心和主题），影响数据合并来源。
  • 函数自 WordPress 5.9.0 版本引入，相关函数包括 wp_theme_has_theme_json() 和 _wp_array_get() 等。
📄 原文内容

Gets the settings resulting of merging core, theme, and user data.

Parameters

$patharrayoptional
Path to the specific setting to retrieve. Optional.
If empty, will return all settings.

Default:array()

$contextarrayoptional
Metadata to know where to retrieve the $path from. Optional.

  • block_name string
    Which block to retrieve the settings from.
    If empty, it’ll return the settings for the global context.
  • origin string
    Which origin to take data from.
    Valid values are 'all' (core, theme, and user) or 'base' (core and theme).
    If empty or unknown, 'all' is used.

Default:array()

Return

mixed The settings array or individual setting value to retrieve.

Source

function wp_get_global_settings( $path = array(), $context = array() ) {
	if ( ! empty( $context['block_name'] ) ) {
		$new_path = array( 'blocks', $context['block_name'] );
		foreach ( $path as $subpath ) {
			$new_path[] = $subpath;
		}
		$path = $new_path;
	}

	/*
	 * This is the default value when no origin is provided or when it is 'all'.
	 *
	 * The $origin is used as part of the cache key. Changes here need to account
	 * for clearing the cache appropriately.
	 */
	$origin = 'custom';
	if (
		! wp_theme_has_theme_json() ||
		( isset( $context['origin'] ) && 'base' === $context['origin'] )
	) {
		$origin = 'theme';
	}

	/*
	 * By using the 'theme_json' group, this data is marked to be non-persistent across requests.
	 * See `wp_cache_add_non_persistent_groups` in src/wp-includes/load.php and other places.
	 *
	 * The rationale for this is to make sure derived data from theme.json
	 * is always fresh from the potential modifications done via hooks
	 * that can use dynamic data (modify the stylesheet depending on some option,
	 * settings depending on user permissions, etc.).
	 * See some of the existing hooks to modify theme.json behavior:
	 * https://make.wordpress.org/core/2022/10/10/filters-for-theme-json-data/
	 *
	 * A different alternative considered was to invalidate the cache upon certain
	 * events such as options add/update/delete, user meta, etc.
	 * It was judged not enough, hence this approach.
	 * See https://github.com/WordPress/gutenberg/pull/45372
	 */
	$cache_group = 'theme_json';
	$cache_key   = 'wp_get_global_settings_' . $origin;

	/*
	 * Ignore cache when the development mode is set to 'theme', so it doesn't interfere with the theme
	 * developer's workflow.
	 */
	$can_use_cached = ! wp_is_development_mode( 'theme' );

	$settings = false;
	if ( $can_use_cached ) {
		$settings = wp_cache_get( $cache_key, $cache_group );
	}

	if ( false === $settings ) {
		$settings = WP_Theme_JSON_Resolver::get_merged_data( $origin )->get_settings();
		if ( $can_use_cached ) {
			wp_cache_set( $cache_key, $settings, $cache_group );
		}
	}

	return _wp_array_get( $settings, $path, $settings );
}

View all references View on Trac View on GitHub

Uses Description
wp_is_development_mode()wp-includes/load.php

Checks whether the site is in the given development mode.
wp_theme_has_theme_json()wp-includes/global-styles-and-settings.php

Checks whether a theme or its parent has a theme.json file.
WP_Theme_JSON_Resolver::get_merged_data()wp-includes/class-wp-theme-json-resolver.php

Returns the data merged from multiple origins.
_wp_array_get()wp-includes/functions.php

Accesses an array in depth based on a path of keys.
wp_cache_set()wp-includes/cache.php

Saves the data to the cache.
wp_cache_get()wp-includes/cache.php

Retrieves the cache contents from the cache by key and group.

Show 1 moreShow less

Used by Description
WP_Font_Face_Resolver::get_fonts_from_theme_json()wp-includes/fonts/class-wp-font-face-resolver.php

Gets fonts defined in theme.json.
WP_Duotone::get_all_global_styles_presets()wp-includes/class-wp-duotone.php

Scrape all possible duotone presets from global and theme styles and store them in self::$global_styles_presets.
get_block_editor_settings()wp-includes/block-editor.php

Returns the contextualized block editor settings for a selected editor context.

Changelog

Version Description
5.9.0 Introduced.

User Contributed Notes

  1. Skip to note 2 content


    jdmweb


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    To know how to use the $path argument with wp_get_global_settings() to retrieve a specific setting, you can try it without first.

    $settings = wp_get_global_settings();
var_dump($settings);

    This gives you a formatted array of every available settings, from this, you can locate the setting you’d like to retrieve.

    For example, gradients are located in $settings['color']['gradients']['theme']

    Take the $settings path, here it’s : ['color']['gradients']['theme'], and transform that in a flat array like this : ['color','gradients','theme'], this is the value you need to pass as the $path argument with wp_get_global_settings($path).

    Example 1, if you’d like to retrieve gradients specified in the theme.json for example, you could use the path argument like so : 

    $gradients = wp_get_global_settings( array( 'color', 'gradients', 'theme' ) );

    Example 2, to retrieve the spacing scale : 

    $spacingScale = wp_get_global_settings( array( 'spacing', 'spacingScale' ) );