get_site_option( string $option, mixed $default_value = false, bool $deprecated = true ): mixed
- Since
- 2.8.0, 4.4.0, 4.4.0
- Source
wp-includes/option.php:1934
Fetches a value from the network-wide options table (wp_options on a single site) using $option as the key. Falls back to $default_value when no such option has been saved. The third parameter $deprecated exists only for backward compatibility and has no effect on caching or behavior. Use update_site_option() to write the value this function reads.
Compatibility
- WordPress
- since 4.4.0
- PHP
- 7.4–8.6-dev
- 6.7.7
- 6.8.8
- 6.9.7
- 7.0.4
- 7.1.0
Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.
Parameters
$optionstring- Name of the option to retrieve. Expected to not be SQL-escaped.
$default_valuemixedoptional- Value to return if the option doesn't exist. Default false.Default:
false $deprecatedbooloptional- Whether to use cache. Multisite only. Always set to true.Default:
true
Return value
mixed- Value set for the option.
Code examples
Every example is editable and runs in a real WordPress booted in your browser by WordPress Playground. Press Run, then edit the code: clicking away re-runs it. Nothing is sent anywhere until you do.
Get a custom network-wide setting with a fallback
A plugin stores a support email address as a site option so it can be shared across every site in the network.
$support_email = get_site_option( 'acme_support_email', '[email protected]' );
echo esc_html( $support_email );On a non-multisite install this reads from wp_options the same way get_option() does.
Show a default value when a site option was never saved
Check for a feature flag that a plugin has not created yet, to confirm the fallback logic before wiring up an admin screen.
$flag = get_site_option( 'acme_beta_features', 'disabled' );
printf( 'Beta features are currently: %s', esc_html( $flag ) );Common problems and fixes · 3
- Why doesn't the third parameter change whether get_site_option uses the cache?
- Why can't I tell if a site option is really false or just missing?
- Does get_site_option work on a normal single-site install?
Why doesn't the third parameter change whether get_site_option uses the cache?
Why can't I tell if a site option is really false or just missing?
Does get_site_option work on a normal single-site install?
Alternatives and related functions
get_network_option- When you need to target a specific network ID instead of the current one, since get_site_option() always passes null for it.
get_option- When the value is per-site rather than shared across the whole network.
update_site_option- When you need to write or change the value this function reads.
add_site_option- When you want to add a site option only if it does not already exist.
Performance profile
How much work a call to get_site_option() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.
- Cost class
- Moderate
- Scaling
- Constant
- Instructions
- 9
- Plugin surface
- None
- Called by
- 50
Reads stored settings via get_site_option(), cached per request but not free on a cold cache.
No loop in the body: the same number of instructions runs whatever you pass in.
Executed per call on PHP 8.5. The body compiles to 9.
Nothing here hands control to plugin code.
50 places in core call this, so the cost is paid more often than your own code shows.
What it touches
- optionnetwork option
get_site_option()this function does it - hookthird-party callbacks
apply_filters()one call below get_site_option() - cacheobject cache
wp_cache_get()one call below get_site_option() - serializeserialisation
maybe_unserialize()one call below get_site_option()
Further down the call graph this can also reach query and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.
What one call costs · 1 distinct outcome
One number would be a lie: the work depends on which branch runs. These are every distinct cost get_site_option() can have, taken from its control-flow graph on PHP 8.5.
| When | Instructions | Calls it makes |
|---|---|---|
| always | 9 | get_network_option() |
Across PHP versions
Compiles the same on PHP 7.4, 8.1, 8.2, 8.3, 8.4, 8.5 and 8.6-dev: 9 instructions, 9 executed per call, 0 branches. The work does not change between versions.
An instruction is not a fixed amount of time, so a matching count is not necessarily the same speed; what it rules out is a difference in the work itself.
Uses · 1
- get_network_option()Retrieves a network's option value based on the option name.
Used by · 50
- Core_Upgrader::should_update_to_version()Determines if this WordPress Core version should update to an offered version or not.
- WP_Automatic_Updater::after_core_update()Checks whether to send an email and avoid processing future updates after attempting a core update.
- WP_Automatic_Updater::send_core_update_notification_email()Notifies an administrator of a core update.
- WP_Automatic_Updater::send_debug_email()Prepares and sends an email of a full log of background update results, useful for debugging and geekery.
- WP_Automatic_Updater::send_email()Sends an email upon the completion or failure of a background core update.
- WP_Automatic_Updater::send_plugin_theme_email()Sends an email upon the completion or failure of a plugin or theme background update.
- WP_Automatic_Updater::should_update()Tests to see if we can and should update a specific item.
- WP_Debug_Data::get_wp_active_theme()Gets the WordPress active theme section of the debug data.
- WP_Debug_Data::get_wp_parent_theme()Gets the WordPress parent theme section of the debug data.
- WP_Debug_Data::get_wp_plugins_raw_data()Gets the raw plugin data for the WordPress active and inactive sections of the debug data.
- WP_Debug_Data::get_wp_themes_inactive()Gets the WordPress inactive themes section of the debug data.
- WP_MS_Themes_List_Table::column_autoupdates()Handles the auto-updates column output.
Show all 50
- WP_MS_Themes_List_Table::prepare_items()Prepares the themes list for display.
- WP_Plugins_List_Table::prepare_items()Prepares the list of items for displaying.
- WP_Plugins_List_Table::single_row()Generates the markup for a single plugin row.
- WP_REST_Attachments_Controller::check_upload_size()Determine if uploaded file exceeds space quota on multisite.
- WP_Recovery_Mode_Cookie_Service::recovery_mode_hash()Gets a form of `wp_hash()` specific to Recovery Mode.
- WP_Site_Health_Auto_Updates::test_if_failed_update()Checks if automatic updates have tried to run, but failed, previously.
- WP_Theme::get_allowed_on_network()Returns array of stylesheet names of themes allowed on the network.
- WP_Theme::network_disable_theme()Disables a theme for all sites on the current network.
- WP_Theme::network_enable_theme()Enables a theme for all sites on the current network.
- WP_Themes_List_Table::no_items()
- _upgrade_core_deactivate_incompatible_plugins()
- _wp_privacy_send_request_confirmation_notification()Notifies the site administrator via email when a request is confirmed.
- _wp_upload_dir()A non-filtered, non-cached version of wp_upload_dir() that doesn't check the path.
- activate_plugin()Attempts activation of plugin in a "sandbox" and redirects on success.
- check_upload_mimes()Checks an array of MIME types against a list of allowed types.
- check_upload_size()Determines whether uploaded file exceeds space quota.
- core_auto_updates_settings()Display WordPress auto-updates settings.
- deactivate_plugins()Deactivates a single plugin or multiple plugins.
- deactivated_plugins_notice()Renders an admin notice when a plugin was deactivated during an update.
- dismiss_core_update()Dismisses core update.
- get_core_updates()Gets available core updates.
- get_dashboard_blog()Get the "dashboard blog", the blog where users without a blog edit their profile data.
- get_locale()Retrieves the current locale.
- get_site_transient()Retrieves the value of a site transient.
- get_space_allowed()Returns the upload quota for the current blog.
- get_super_admins()Retrieves a list of super admins.
- get_upload_space_available()Determines if there is any upload space left in the current blog's quota.
- grant_super_admin()Grants Super Admin privileges.
- install_blog()Install an empty blog.
- is_email_address_unsafe()Checks an email address against a list of banned domains.
- is_plugin_active_for_network()Determines whether the plugin is active for the entire network.
- is_upload_space_available()Determines if there is any upload space left in the current blog's quota.
- list_plugin_updates()Display the upgrade plugins form.
- list_theme_updates()Display the upgrade themes form.
- maintenance_nag()Displays maintenance nag HTML message.
- map_meta_cap()Maps a capability to the primitive capabilities required of the given user to satisfy the capability being checked.
- ms_site_check()Checks status of current blog.
- ms_upload_constants()Defines Multisite upload constants.
Source code
function get_site_option( $option, $default_value = false, $deprecated = true ) { return get_network_option( null, $option, $default_value );}Changelog
Introduced in 2.8.0. Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
$use_cache parameter was deprecated.from the docblockAbout this page
- Parsed data
- Generated from the wordpress-develop 7.1.0 tag, from
src/wp-includes/option.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it. - Corrections
- Something wrong on this page? Report it and it gets fixed in the next regeneration.