Adding network options in WordPress using add_site_option
The add_site_option function in WordPress is designed to add a new option to the options database table for the current network. It is a part of the WordPress Multisite (MS) functions, and its main purpose is to provide a way to manage options across an entire network of sites.
When a new option is added using add_site_option, it is only added if the option does not already exist. If the option does exist, the function will not update or change the existing option. This makes it different from the update_site_option function, which will update an existing option or add a new one if it does not already exist.
One of the main advantages of using add_site_option is that it allows developers to set default options that apply to all sites in a network. This can be useful when setting up a new network or when adding new sites to an existing network.
The add_site_option function is also designed to work with WordPress’s built-in caching mechanisms. This means that once an option is added, it can be retrieved quickly and efficiently, without the need for additional database queries.
Parameters for the add_site_option Function in WordPress
The add_site_option function in WordPress accepts two parameters, both of which are required:
$option(string): This parameter represents the name of the option you want to add. It should not be SQL-escaped.$value(mixed): This parameter is the value of the option. It can be any data type and, like the$optionparameter, it should not be SQL-escaped.
Return Value of the add_site_option Function
The add_site_option function in WordPress returns a boolean value. It will return true if the option was successfully added. If the addition of the option was unsuccessful, the function will return false.
Examples
How to Add a New Site Option in WordPress
The add_site_option function is commonly used to add a new site-wide option in a WordPress multisite network. Here is a basic usage:
add_action('init', 'add_my_site_option');
function add_my_site_option() {
if (!get_site_option('my_site_option')) {
add_site_option('my_site_option', 'My Site Option Value');
}
}
This code snippet adds a new site option named ‘my_site_option’ with the value ‘My Site Option Value’. The function is hooked to the ‘init’ action, so it runs on every page load. It first checks if the option already exists with get_site_option, and if it doesn’t, it adds the option.
How to Add a Boolean Site Option in WordPress
The add_site_option function can also be used to add boolean options. Here is an example:
add_action('init', 'add_my_boolean_site_option');
function add_my_boolean_site_option() {
if (!get_site_option('my_boolean_option')) {
add_site_option('my_boolean_option', true);
}
}
This code snippet adds a new site option named ‘my_boolean_option’ with the value true. Just like the previous example, it first checks if the option already exists, and if it doesn’t, it adds the option.
How to Add an Array Site Option in WordPress
The add_site_option function can also handle array values. Here is an example:
add_action('init', 'add_my_array_site_option');
function add_my_array_site_option() {
if (!get_site_option('my_array_option')) {
add_site_option('my_array_option', array('key1' => 'value1', 'key2' => 'value2'));
}
}
This code snippet adds a new site option named ‘my_array_option’ with an array as its value. The array has two elements, ‘key1’ with the value ‘value1’ and ‘key2’ with the value ‘value2’. As always, it first checks if the option already exists, and if it doesn’t, it adds the option.
Conclusion
The add_site_option function in WordPress is a valuable utility that allows developers to add a new option to the options database table. This function is specifically designed to work in a multisite environment, where it will add an option for the entire network of sites, rather than for a single site. It can be used for storing network-wide settings, such as default themes, network policies, or global customizations. It’s important to note that the add_site_option function will not update an option that already exists, ensuring that existing settings are not unintentionally overridden.