switch_to_blog()WP 3.0.0

Switch the current blog.

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().

Things that aren't switched:

  • plugins. See #14941
1 time — 0.00094 sec (slow) | 50000 times — 5.201680 sec (fast) | PHP 7.4.8, WP 5.7.2
Hooks from the function

Return

true. Always returns true.

Usage

switch_to_blog( $new_blog_id, $deprecated );
$new_blog_id(int) (required)
The ID of the blog to switch to.
Default: current blog
$deprecated(true|false)
Not used.
Default: null

Examples

0

#1 Single Switching

Let's switch to blog 5 to display its posts and go back to the current blog.

// switch to blog 5
switch_to_blog( 5 );

// Output the data of the blog we switched to
// Getting posts from blog 5
$myposts = get_posts();
foreach( $myposts as $post ){
	echo esc_html( $post->post_title ) .'<br>';
}
wp_reset_postdata();

// back to the current blog
restore_current_blog();
0

#2 Multiple Switching

Before you can switch to another blog, you must first go back to the current blog...

foreach( $blog_ids as $blog_id ){

	switch_to_blog( $blog_id );

	// process the data of the blog to which we have switched.

	restore_current_blog();
}

Note: 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.

0

#3 global $switched 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'
	)
);
?>

Notes

  • See: restore_current_blog()
  • Global. wpdb. $wpdb WordPress database abstraction object.
  • Global. Int. $blog_id
  • Global. Array. $_wp_switched_stack
  • Global. true|false. $switched
  • Global. String. $table_prefix
  • Global. WP_Object_Cache. $wp_object_cache

Changelog

Since 3.0.0 Introduced.

switch_to_blog() code WP 6.4.3

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',
						'networks',
						'network-queries',
						'sites',
						'site-details',
						'site-options',
						'site-queries',
						'site-transient',
						'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;
}