云策 WordPress 开发者社区

函数文档

add_site_option()

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

概述

add_site_option() 函数用于为当前网络添加一个新选项，适用于 WordPress 多站点环境。它不会更新已存在的选项，且自 4.4.0 版本起，已封装为 add_network_option() 的包装器。

关键要点

  • 函数功能：添加网络范围的选项，类似于 add_option()，但专为多站点设计。
  • 参数要求：$option（选项名称，字符串，必需，无需 SQL 转义）和 $value（选项值，混合类型，必需，无需 SQL 转义）。
  • 返回值：如果选项添加成功返回 true，否则返回 false。
  • 注意事项：在多站点中，站点范围的选项不会自动加载；在单站点中，选项会自动加载，且此行为不可覆盖。
  • 版本历史：从 4.4.0 版本开始，改为 add_network_option() 的包装器；最初在 2.8.0 版本引入。

代码示例

add_site_option( 'my_option', 'my_value' );

注意事项

  • 如果选项已存在，函数不会更新它，而是返回 false。
  • 在多站点环境中，使用此函数添加的选项不会自动加载，而单站点中会自动加载。
  • 参数 $value 是必需的，文档中可能错误标记为可选。
📄 原文内容

Adds a new option for the current network.

Description

Existing options will not be updated. Note that prior to 3.3 this wasn’t the case.

See also

Parameters

$optionstringrequired
Name of the option to add. Expected to not be SQL-escaped.
$valuemixedrequired
Option value, can be anything. Expected to not be SQL-escaped.

Return

bool True if the option was added, false otherwise.

More Information

This function essentially the same as add_option() but works network wide when using WP Multisite.

The only major difference is that on multisite site-wide options will not autoload and on a single site the option will autoload. Unlike when using add_option() on a single site, the feature cannot be overridden.

Source

function add_site_option( $option, $value ) {
	return add_network_option( null, $option, $value );
}

View all references View on Trac View on GitHub

Uses Description
add_network_option()wp-includes/option.php

Adds a new network option.
Used by Description
set_site_transient()wp-includes/option.php

Sets/updates the value of a site transient.
wpmu_validate_user_signup()wp-includes/ms-functions.php

Sanitizes and validates data required for a user sign-up.
wpmu_validate_blog_signup()wp-includes/ms-functions.php

Processes new site registrations.

Changelog

Version Description
4.4.0 Modified into wrapper for add_network_option()
2.8.0 Introduced.

User Contributed Notes

  1. Skip to note 4 content


    MakeWebBetter


    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

    Install the option defaults

       
 	if ( 1 == $wpmu ) {
         if ( ! get_site_option( 'wporg_lead_options' ) ) {
             add_site_option( 'wporg_lead_options', $wporg_lead_options_defaults, '', 'yes' );
         }
	} else {
         if ( ! get_option( 'wporg_lead_options' ) ) {
             add_option( 'wporg_lead_options', $wporg_lead_options_defaults, '', 'yes' );
         }
	}

  2. Skip to note 5 content


    Codex


    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

    Examples

    Default usage:

    add_site_option( 'my_option', 'my_value' );

    Behavior if the option already exists:

    echo get_site_option( 'i_exist_already' );

// Output: 'some_value'


if ( add_site_option( 'i_exist_already', 'new_value' ) ) {
   echo get_site_option( 'i_exist_already' );
} else {
   echo __( 'Already exists', 'textdomain' );
}