云策 WordPress 开发者社区

函数文档

update_blog_option()

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

概述

update_blog_option() 函数用于更新指定博客的选项值，支持多站点环境。它通过调用 update_option() 实现，并处理博客切换逻辑。

关键要点

  • 函数签名：update_blog_option( $id, $option, $value, $deprecated = null )
  • 参数：$id（博客ID，整数）、$option（选项键，字符串）、$value（选项值，混合类型）、$deprecated（已弃用，可选）
  • 返回值：布尔值，表示更新是否成功（基于 update_option() 的返回结果）
  • 内部逻辑：如果当前博客ID与目标ID相同，直接调用 update_option()；否则使用 switch_to_blog() 切换博客后更新
  • 注意事项：$deprecated 参数自 WordPress 3.1.0 起已弃用，传入非 null 值会触发 _deprecated_argument() 警告
  • 返回值说明：返回 false 可能表示值未改变（非错误），需参考 update_option() 行为

代码示例

// 更新博客ID为2的 'my_option' 选项值为 'new_value'
$result = update_blog_option( 2, 'my_option', 'new_value' );
if ( $result ) {
    echo '选项更新成功';
} else {
    echo '选项未改变或更新失败';
}

注意事项

  • 函数适用于多站点环境，单站点中可直接使用 update_option()
  • 返回值 false 不一定表示错误，可能只是选项值未发生变化
  • 相关函数：switch_to_blog()、restore_current_blog()、get_current_blog_id()、update_option()
📄 原文内容

Updates an option for a particular blog.

Parameters

$idintrequired
The blog ID.
$optionstringrequired
The option key.
$valuemixedrequired
The option value.
$deprecatedmixedoptional
Not used.

Default:null

Return

bool True if the value was updated, false otherwise.

Source

function update_blog_option( $id, $option, $value, $deprecated = null ) {
	$id = (int) $id;

	if ( null !== $deprecated ) {
		_deprecated_argument( __FUNCTION__, '3.1.0' );
	}

	if ( get_current_blog_id() === $id ) {
		return update_option( $option, $value );
	}

	switch_to_blog( $id );
	$return = update_option( $option, $value );
	restore_current_blog();

	return $return;
}

View all references View on Trac View on GitHub

Uses Description
switch_to_blog()wp-includes/ms-blogs.php

Switches the current blog.
restore_current_blog()wp-includes/ms-blogs.php

Restores the current blog, after calling switch_to_blog() .
get_current_blog_id()wp-includes/load.php

Retrieves the current site ID.
_deprecated_argument()wp-includes/functions.php

Marks a function argument as deprecated and inform when it has been used.
update_option()wp-includes/option.php

Updates the value of an option that was already added.

Show 3 moreShow less

Used by Description
wp_update_blog_public_option_on_site_update()wp-includes/ms-site.php

Updates the blog_public option for a given site ID.

Changelog

Version Description
MU (3.0.0) Introduced.

User Contributed Notes

  1. Skip to note 2 content


    Xedin Unknown


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

    The return documentation states:

    (bool) True on success, false on failure.

    However, this is not true. This function uses update_option() under the hood, and returns its result verbatim. It’s not in the reference, but the Codex doc of update_option() states:

    (boolean)
    True if option value has changed, false if not or if update failed.

    update_option() will return false if the value has not changed, such as if the new value is the same as the old, and therefore so will update_blog_option(). Thus, just because it returns false does not mean there was an error.

    Also, see this helpful comment.