switch_to_blog() – Function | Developer.WordPress.org

Switches the current blog.

Description

This function is useful if you need to pull posts, or other information, from other blogs. You can switch back afterwards using restore_current_blog() .

PHP code loaded with the originally requested site, such as code from a plugin or theme, does not switch. See #14941.

Parameters

$new_blog_idintrequired: The ID of the blog to switch to. Default: current blog.
$deprecatedbooloptional: Not used.
Default:null

Return

true Always returns true.

Source

function switch_to_blog( $new_blog_id, $deprecated = null ) {	global $wpdb;	$prev_blog_id = get_current_blog_id();	if ( empty( $new_blog_id ) ) {	$new_blog_id = $prev_blog_id;	}	$GLOBALS['_wp_switched_stack'][] = $prev_blog_id;	/* * If we're switching to the same blog id that we're on, * set the right vars, do the associated actions, but skip * the extra unnecessary work */	if ( $new_blog_id === $prev_blog_id ) {	/** * Fires when the blog is switched. * * @since MU (3.0.0) * @since 5.4.0 The `$context` parameter was added. * * @param int $new_blog_id New blog ID. * @param int $prev_blog_id Previous blog ID. * @param string $context Additional context. Accepts 'switch' when called from switch_to_blog() * or 'restore' when called from restore_current_blog(). */	do_action( 'switch_blog', $new_blog_id, $prev_blog_id, 'switch' );	$GLOBALS['switched'] = true;	return true;	}	$wpdb->set_blog_id( $new_blog_id );	$GLOBALS['table_prefix'] = $wpdb->get_blog_prefix();	$GLOBALS['blog_id'] = $new_blog_id;	if ( function_exists( 'wp_cache_switch_to_blog' ) ) {	wp_cache_switch_to_blog( $new_blog_id );	} else {	global $wp_object_cache;	if ( is_object( $wp_object_cache ) && isset( $wp_object_cache->global_groups ) ) {	$global_groups = $wp_object_cache->global_groups;	} else {	$global_groups = false;	}	wp_cache_init();	if ( function_exists( 'wp_cache_add_global_groups' ) ) {	if ( is_array( $global_groups ) ) {	wp_cache_add_global_groups( $global_groups );	} else {	wp_cache_add_global_groups(	array(	'blog-details',	'blog-id-cache',	'blog-lookup',	'blog_meta',	'global-posts',	'image_editor',	'networks',	'network-queries',	'sites',	'site-details',	'site-options',	'site-queries',	'site-transient',	'theme_files',	'rss',	'users',	'user-queries',	'user_meta',	'useremail',	'userlogins',	'userslugs',	)	);	}	wp_cache_add_non_persistent_groups( array( 'counts', 'plugins', 'theme_json' ) );	}	}	/** This filter is documented in wp-includes/ms-blogs.php */	do_action( 'switch_blog', $new_blog_id, $prev_blog_id, 'switch' );	$GLOBALS['switched'] = true;	return true; }

View all references View on Trac View on GitHub

Hooks

do_action( ‘switch_blog’, int $new_blog_id, int $prev_blog_id, string $context ): Fires when the blog is switched.

Uses	Description
wp_cache_switch_to_blog()`wp-includes/cache.php`	Switches the internal blog ID.
wp_cache_init()`wp-includes/cache.php`	Sets up Object Cache Global and assigns it.
wp_cache_add_global_groups()`wp-includes/cache.php`	Adds a group or set of groups to the list of global groups.
wp_cache_add_non_persistent_groups()`wp-includes/cache.php`	Adds a group or set of groups to the list of non-persistent groups.
wpdb::set_blog_id()`wp-includes/class-wpdb.php`	Sets blog ID.
wpdb::get_blog_prefix()`wp-includes/class-wpdb.php`	Gets blog prefix.
get_current_blog_id()`wp-includes/load.php`	Retrieves the current site ID.
do_action()`wp-includes/plugin.php`	Calls the callback functions that have been added to an action hook.

Show 3 more Show less

Used by	Description
user_can_for_site()`wp-includes/capabilities.php`	Returns whether a particular user has the specified capability for a given site.
current_user_can_for_site()`wp-includes/capabilities.php`	Returns whether the current user has the specified capability for a given site.
WP_User_Query::generate_cache_key()`wp-includes/class-wp-user-query.php`	Generate cache key.
wp_initialize_site()`wp-includes/ms-site.php`	Runs the initialization routine for a given site.
wp_uninitialize_site()`wp-includes/ms-site.php`	Runs the uninitialization routine for a given site.
wp_is_site_initialized()`wp-includes/ms-site.php`	Checks whether a site is initialized.
get_oembed_response_data_for_url()`wp-includes/embed.php`	Retrieves the oEmbed response data for a given URL.
WP_Site::get_details()`wp-includes/class-wp-site.php`	Retrieves the details for this site.
has_custom_logo()`wp-includes/general-template.php`	Determines whether the site has a custom logo.
get_custom_logo()`wp-includes/general-template.php`	Returns a custom logo, linked to home unless the theme supports removing the link on the home page.
wp_get_users_with_no_role()`wp-includes/user.php`	Gets the user IDs of all users with no role on this site.
get_site_icon_url()`wp-includes/general-template.php`	Returns the Site Icon URL.
WP_MS_Sites_List_Table::column_blogname()`wp-admin/includes/class-wp-ms-sites-list-table.php`	Handles the site name column output.
confirm_another_blog_signup()`wp-signup.php`	Shows a message confirming that the new site has been created.
wpmu_delete_user()`wp-admin/includes/ms.php`	Deletes a user and all of their posts from the network.
upload_space_setting()`wp-admin/includes/ms.php`	Displays the site upload space quota setting form on the Edit Site Settings screen.
wpmu_delete_blog()`wp-admin/includes/ms.php`	Deletes a site.
WP_Users_List_Table::get_views()`wp-admin/includes/class-wp-users-list-table.php`	Returns an associative array listing all the views that can be used with this table.
WP_Importer::set_blog()`wp-admin/includes/class-wp-importer.php`
WP_User::get_role_caps()`wp-includes/class-wp-user.php`	Retrieves all of the capabilities of the user’s roles, and merges them with individual user capabilities.
WP_Theme::get_allowed_on_site()`wp-includes/class-wp-theme.php`	Returns array of stylesheet names of themes allowed on the site.
get_home_url()`wp-includes/link-template.php`	Retrieves the URL for a given site where the front end is accessible.
get_site_url()`wp-includes/link-template.php`	Retrieves the URL for a given site where WordPress application files (e.g. wp-blog-header.php or the wp-admin/ folder) are accessible.
wp_admin_bar_my_sites_menu()`wp-includes/admin-bar.php`	Adds the “My Sites/[Site Name]” menu and all submenus.
count_users()`wp-includes/user.php`	Counts number of users who have each of the user roles.
newblog_notify_siteadmin()`wp-includes/ms-functions.php`	Notifies the network admin that a new site has been activated.
get_blog_post()`wp-includes/ms-functions.php`	Gets a blog post from any site on the network.
add_user_to_blog()`wp-includes/ms-functions.php`	Adds a user to a blog, along with specifying the user’s role.
remove_user_from_blog()`wp-includes/ms-functions.php`	Removes a user from a blog.
get_blog_permalink()`wp-includes/ms-functions.php`	Gets the permalink for a post on another blog.
create_empty_blog()`wp-includes/ms-deprecated.php`	Create an empty blog.
get_blog_option()`wp-includes/ms-blogs.php`	Retrieves option value for a given blog id based on name of option.
add_blog_option()`wp-includes/ms-blogs.php`	Adds a new option for a given blog ID.
delete_blog_option()`wp-includes/ms-blogs.php`	Removes an option by name for a given blog ID. Prevents removal of protected WordPress options.
update_blog_option()`wp-includes/ms-blogs.php`	Updates an option for a particular blog.
get_blog_details()`wp-includes/ms-blogs.php`	Retrieves the details for a blog from the blogs table and blog options.
wp_xmlrpc_server::wp_getUsersBlogs()`wp-includes/class-wp-xmlrpc-server.php`	Retrieves the blogs of the user.

Show 32 more Show less

Changelog

Version	Description
MU (3.0.0)	Introduced.

User Contributed Notes

Skip to note 7 content

Codex 10 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note
Multiple switches
```
foreach( $blog_ids as $blog_id ){ switch_to_blog( $blog_id ); //Do stuff restore_current_blog(); }
```
If you do not call restore_current_blog() after every switch_to_blog() , WordPress can get into a state that can potentially build the wrong urls for the site. See restore_current_blog() vs switch_to_blog() .
Log in to add feedback
Skip to note 8 content

Brent Leavitt 7 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
I was a little confused with the switch_to_blog() functionality when I first started using it. This function only affects the database which is being accessed on the network. I cannot access blocks of code, classes, functions, or variables that exist within a specific blog on the network. By extension, this also means that I cannot access themes or plugins that only exist on one site on the network. I was hoping for a little more power with this function before I realized that this was limited to site data being stored in the database.

The following example does not work:

Site 1 --> Site1_only_plugin --> Site1_only_plugin_function()

That is, Site 1 has a unique plugin that has a bit of functionality that I want to access on Site 2 (or anywhere else on the network) without loading the full plugin to Site 2. I might be tempted to do something like this from Site 2:
```
switch_to_blog( $site1 ); $var = site1_only_plugin_function(); restore_current_blog();
```
This does not work. I can only use the switch_to_blog() functionality to access database values from other sites on the network. Here’s an example that does work:

Site 1 --> Site1_only_plugin --> Site1_only_plugin_function()--> add_option( 'Site1_only_plugin_option', $var )

The plugin on Site 1 has first set a value in the Site 1 database. I can then access that value in the options table from anywhere on the network as follows:
```
switch_to_blog( $site1 ); $var = get_option( 'Site1_only_plugin_option' ); restore_current_blog();
```
Log in to add feedback
Skip to note 9 content

Codex 10 years ago

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
One switch
```
switch_to_blog( $blog_id ); // Do something restore_current_blog();
```
Log in to add feedback
Skip to note 10 content

Lance Cleveland 9 years ago

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

Description

Restores previous blog after a switch_to_blog call.

Contrary to the function’s name, this does NOT restore the original blog but the previous blog. Calling `switch_to_blog() ` twice in a row and then calling this function will result in being on the blog set by the first `switch_to_blog() ` call.
- Looks like this comment was meant for the `restore_current_blog() ` function, not on this page.
  
  jakeparis 3 years ago
Log in to add feedback
Skip to note 11 content

dekket 4 years ago

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
When using switch_to_blog() outside of WordPress, you need to have the global $switched defined. The variable for defining which blog ID to target, may also not be $blog_id, because it is used by WP Core.

The below example will not create a post within the correct blog_id, unless $switched is defined.
```
<?php require_once '../wp-load.php'; global $switched; $blog_id_target = 2; switch_to_blog( $blog_id_target ); // Create a post programmatically, for blog 2. $id = wp_insert_post(	array(	'post_author' => 1,	'post_status' => 'publish',	'post_type' => 'custom_post_type',	'post_content' => 'Post body here',	'post_title' => 'Post title here'	) ); ?>
```
Log in to add feedback
Skip to note 12 content

jakeparis 3 years ago

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

It’s important to note that switch_to_blog() does not check whether a blog actually exists for the supplied ID. You could potentially switch to a non-existant blog and run queries against non-existant tables.

Log in to add feedback

switch_to_blog( int $new_blog_id, bool $deprecated = null ): true

In this article