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;

	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, '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.
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 2 more Show less

Used by	Description
WP_User_Query::get_cache_last_changed()`wp-includes/class-wp-user-query.php`	Retrieves the last changed cache timestamp for users and optionally posts.
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_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.
create_empty_blog()`wp-includes/ms-deprecated.php`	Create an empty blog.
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.
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 8 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 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

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 4 years ago
Log in to add feedback
Skip to note 11 content

dekket 5 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 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

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