restore_current_blog(): bool
- Since
- MU (3.0.0)
- Source
wp-includes/ms-blogs.php:563
Reverses the site context set by the most recent switch_to_blog() call, popping WordPress back to whichever blog it was on beforehand. It resets the $wpdb table prefix, the current blog ID, and the object cache group for that prior site, and fires the switch_blog action so plugins can react to the change. Pair it one-to-one with switch_to_blog(), since an unbalanced stack leaves table queries and cached values pointed at the wrong site.
Compatibility
- WordPress
- since MU (3.0.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.
Return value
bool- True on success, false if we're already on the current blog.
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.
Undo a switch_to_blog() call after creating a post on another site
On a multisite network, temporarily jump into a second site to publish a post, then hand control back to whichever site the request started on.
$sites = get_sites( array( 'number' => 2 ) );
$target_blog_id = null;
foreach ( $sites as $site ) {
if ( (int) $site->blog_id !== get_current_blog_id() ) {
$target_blog_id = (int) $site->blog_id;
break;
}
}
if ( ! $target_blog_id ) {
echo esc_html( 'No secondary site found to switch into.' );
} else {
switch_to_blog( $target_blog_id );
$new_post_id = wp_insert_post( array(
'post_title' => 'Cross-posted from the main site',
'post_content' => 'This copy lives on the branch office site.',
'post_status' => 'publish',
) );
echo esc_html( sprintf( 'Created post %d on blog %d.', $new_post_id, get_current_blog_id() ) );
$restored = restore_current_blog();
echo esc_html( sprintf( ' restore_current_blog() returned %s, current blog is now %d.', $restored ? 'true' : 'false', get_current_blog_id() ) );
}switch_to_blog() and restore_current_blog() only exist on a multisite install, since they live in code that is loaded solely when is_multisite() is true.
See what restore_current_blog() returns with and without a prior switch
Call the function on its own and then again right after switch_to_blog() to compare the two return values in the same request.
$stack_before = empty( $GLOBALS['_wp_switched_stack'] ) ? 'empty' : 'not empty';
$result_without_switch = restore_current_blog();
switch_to_blog( get_current_blog_id() );
$result_with_switch = restore_current_blog();
echo esc_html( sprintf(
'Switch stack was %s. Restoring with nothing to undo returned %s. Restoring after switching to the same blog returned %s.',
$stack_before,
$result_without_switch ? 'true' : 'false',
$result_with_switch ? 'true' : 'false'
) );Switching to the site you are already on still pushes an entry onto the stack, so the second restore still returns true even though nothing about $wpdb actually changes.
Common problems and fixes · 3
- Why does restore_current_blog() return false?
- Why is $wpdb still querying the site I switched away from?
- Why doesn't the object cache reset when I restore right after switching to the same blog?
Why does restore_current_blog() return false?
Why is $wpdb still querying the site I switched away from?
Why doesn't the object cache reset when I restore right after switching to the same blog?
Alternatives and related functions
switch_to_blog- When you need to move site context to a different blog in the first place, since restore_current_blog() only undoes that call.
ms_is_switched- When you just need to check whether the site context is currently switched without popping the switch stack.
get_current_blog_id- When you only need the ID of whichever site is active right now rather than reverting to a previous one.
Performance profile
How much work a call to restore_current_blog() 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
- Light
- Scaling
- Constant
- Instructions
- 4–36
- Plugin surface
- 1 hook
- Called by
- 37
Only touches the object cache, via wp_cache_switch_to_blog().
No loop in the body: the same number of instructions runs whatever you pass in.
Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 48.
Third-party callbacks on 'switch_blog' run inside this call, and their cost is not bounded by anything here.
37 places in core call this, so the cost is paid more often than your own code shows.
What it touches
- hookthird-party callbacks
do_action()called directly - cacheobject cache
wp_cache_switch_to_blog()called directly
What one call costs · 3 distinct outcomes
One number would be a lie: the work depends on which branch runs. These are every distinct cost restore_current_blog() can have, taken from its control-flow graph on PHP 8.5.
| When | Instructions | Calls it makes |
|---|---|---|
empty($value) | 4 | none |
!empty($value) && $new_blog_id === false | 24 | array_pop(), get_current_blog_id(), do_action() |
!empty($value) && $new_blog_id !== false | 36 | array_pop(), get_current_blog_id(), ->set_blog_id(), ->get_blog_prefix(), wp_cache_switch_to_blog(), do_action() |
Across PHP versions
| PHP | Compiled | Executed | Branches | Notes |
|---|---|---|---|---|
| 8.6-dev | 48 | 4–36 | 2 | |
| 8.5 | 48 | 4–36 | 2 | |
| 8.4 | 48 | 4–36 | 2 | |
| 8.3 | 48 | 4–36 | 2 | |
| 8.2 | 48 | 4–36 | 2 | |
| 8.1 | 48 | 4–36 | 2 | 8 fewer instructions than PHP 7.4 |
| 7.4 | 56 | 5–42 | 2 |
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.
Hooks and filters fired · 2
2 hooks fire while restore_current_blog() runs, in this order:
Uses · 3
- get_current_blog_id()Retrieves the current site ID.
- do_action()Calls the callback functions that have been added to an action hook.
- wp_cache_switch_to_blog()Used when switch_to_blog() and restore_current_blog() are called, but only when a persistent object cache drop-in plugin has omitted the wp_cache_switch_to_blog() function that was introduced in 3.5.0.
Used by · 37
- WP_MS_Sites_List_Table::column_blogname()Handles the site name column output.
- WP_Site::get_details()Retrieves the details for this site.
- WP_Theme::get_allowed_on_site()Returns array of stylesheet names of themes allowed on the site.
- WP_User::get_role_caps()Retrieves all of the capabilities of the user's roles, and merges them with individual user capabilities.
- WP_User_Query::get_cache_last_changed()Retrieves the last changed cache timestamp for users and optionally posts.
- WP_Users_List_Table::get_views()Returns an associative array listing all the views that can be used with this table.
- add_blog_option()Adds a new option for a given blog ID.
- add_user_to_blog()Adds a user to a blog, along with specifying the user's role.
- confirm_another_blog_signup()Shows a message confirming that the new site has been created.
- confirm_delete_users()
- count_users()Counts number of users who have each of the user roles.
- create_empty_blog()Create an empty blog.
Show all 37
- current_user_can_for_site()Returns whether the current user has the specified capability for a given site.
- delete_blog_option()Removes an option by name for a given blog ID. Prevents removal of protected WordPress options.
- get_blog_details()Retrieves the details for a blog from the blogs table and blog options.
- get_blog_option()Retrieves option value for a given blog id based on name of option.
- get_blog_permalink()Gets the permalink for a post on another blog.
- get_blog_post()Gets a blog post from any site on the network.
- get_custom_logo()Returns a custom logo, linked to home unless the theme supports removing the link on the home page.
- get_home_url()Retrieves the URL for a given site where the front end is accessible.
- get_oembed_response_data_for_url()Retrieves the oEmbed response data for a given URL.
- get_site_icon_url()Returns the Site Icon URL.
- get_site_url()Retrieves the URL for a given site where WordPress application files (e.g. wp-blog-header.php or the wp-admin/ folder) are accessible.
- has_custom_logo()Determines whether the site has a custom logo.
- newblog_notify_siteadmin()Notifies the network admin that a new site has been activated.
- remove_user_from_blog()Removes a user from a blog.
- update_blog_option()Updates an option for a particular blog.
- upload_space_setting()Displays the site upload space quota setting form on the Edit Site Settings screen.
- user_can_for_site()Returns whether a particular user has the specified capability for a given site.
- wp_admin_bar_my_sites_menu()Adds the "My Sites/[Site Name]" menu and all submenus.
- wp_get_users_with_no_role()Gets the user IDs of all users with no role on this site.
- wp_initialize_site()Runs the initialization routine for a given site.
- wp_is_site_initialized()Checks whether a site is initialized.
- wp_uninitialize_site()Runs the uninitialization routine for a given site.
- wp_xmlrpc_server::wp_getUsersBlogs()Retrieves the blogs of the user.
- wpmu_delete_blog()Deletes a site.
- wpmu_delete_user()Deletes a user and all of their posts from the network.
Source code
function restore_current_blog() { global $wpdb; if ( empty( $GLOBALS['_wp_switched_stack'] ) ) { return false; } $new_blog_id = array_pop( $GLOBALS['_wp_switched_stack'] ); $prev_blog_id = get_current_blog_id(); if ( $new_blog_id === $prev_blog_id ) { /** This filter is documented in wp-includes/ms-blogs.php */ do_action( 'switch_blog', $new_blog_id, $prev_blog_id, 'restore' ); // If we still have items in the switched stack, consider ourselves still 'switched'. $GLOBALS['switched'] = ! empty( $GLOBALS['_wp_switched_stack'] ); return true; } $wpdb->set_blog_id( $new_blog_id ); $GLOBALS['blog_id'] = $new_blog_id; $GLOBALS['table_prefix'] = $wpdb->get_blog_prefix(); wp_cache_switch_to_blog( $new_blog_id ); /** This filter is documented in wp-includes/ms-blogs.php */ do_action( 'switch_blog', $new_blog_id, $prev_blog_id, 'restore' ); // If we still have items in the switched stack, consider ourselves still 'switched'. $GLOBALS['switched'] = ! empty( $GLOBALS['_wp_switched_stack'] ); return true;}Changelog
Introduced in MU (3.0.0). Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
About this page
- Parsed data
- Generated from the wordpress-develop 7.1.0 tag, from
src/wp-includes/ms-blogs.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.