wp_initialize_site() │ WP 5.1.0

Prepares a new site in WordPress Multisite: creates database tables, fills in standard options, roles, metadata, and the site’s initial content.

The function is used to initialize a site that has already been added to the network but has not yet been prepared for operation. Usually it is not called directly, but via the site creation process from wp_insert_site().

During execution, the function switches to the required site through switch_to_blog(), creates tables, sets the basic options home, siteurl, blogname, blog_public, adds standard roles, creates initial posts/pages, and assigns the specified user as the site administrator.

The function is intended for Multisite. If the site has already been initialized, a repeated run will return an WP_Error to avoid overwriting the already created site structure.

Initialization arguments can be modified via the wp_initialize_site_args filter. It is convenient when you need to set your own options or metadata for all new sites in the network.

Uses: get_site(), wp_is_site_initialized(), get_network(), make_db_current_silent(), populate_options(), populate_site_meta(), wp_install_defaults()
Hooks from the function

Returns

true|WP_Error.

  • true — the site was successfully initialized.
  • WP_Error — an error occurred: the site ID was not provided, the site was not found, or the site has already been initialized.

Usage

wp_initialize_site( $site_id, $args );
$site_id(int|WP_Site) (required)
The site ID or an WP_Site{} object that needs to be initialized.
$args(array)
Initialization arguments that change the behavior.
Default: []
user_id (int)
The ID of the user who will become the administrator of the new site.
title (string)
The name of the site. If not specified, a string of the form Site %d is used, where %d is the site ID.
options (array)
An array of additional site options in the format key => value. Passed to populate_options() and can override the default options.
meta (array)
An array of site metadata in the format key => value. Passed to populate_site_meta().

Examples

0

#1 Initializing a New Site

The example receives the ID of an already created site and runs the standard initialization for it.

$result = wp_initialize_site( 123, [
	'user_id' => 1,
	'title'   => 'New site',
] );

if ( is_wp_error( $result ) ) {
	wp_die( $result->get_error_message() );
}
0

#2 Passing your options during initialization

The example sets the site name, the administrator email, and closes the site from indexing via the blog_public option.

$result = wp_initialize_site( 123, [
	'user_id' => 1,
	'title'   => 'Private site',
	'options' => [
		'admin_email' => '[email protected]',
		'blog_public' => 0,
	],
] );

if ( is_wp_error( $result ) ) {
	error_log( $result->get_error_message() );
}
0

#3 Adding Your Site Metadata

The example adds metadata that will be saved for the new site during initialization.

$result = wp_initialize_site( 123, [
	'user_id' => 1,
	'title'   => 'Client Site',
	'meta'    => [
		'client_id'   => 456,
		'client_type' => 'premium',
	],
] );

if ( true === $result ) {
	// The site has been successfully initialized.
}
0

#4 Changing arguments via a filter

The example automatically adds its own options for each new site before it is initialized.

add_filter( 'wp_initialize_site_args', 'my_change_site_initialization_args', 10, 3 );

function my_change_site_initialization_args( $args, $site, $network ) {
	$args['options']['blog_public'] = 0;
	$args['options']['timezone_string'] = 'Europe/Moscow';

	$args['meta']['created_by_custom_flow'] = 1;

	return $args;
}

Notes

  • Global. wpdb. $wpdb WordPress database abstraction object.
  • Global. WP_Roles. $wp_roles WordPress role management object.

Changelog

Since 5.1.0 Introduced.

wp_initialize_site() code WP 7.0

wp-includes/ms-site.php 
function wp_initialize_site( $site_id, array $args = array() ) {
	global $wpdb, $wp_roles;

	if ( empty( $site_id ) ) {
		return new WP_Error( 'site_empty_id', __( 'Site ID must not be empty.' ) );
	}

	$site = get_site( $site_id );
	if ( ! $site ) {
		return new WP_Error( 'site_invalid_id', __( 'Site with the ID does not exist.' ) );
	}

	if ( wp_is_site_initialized( $site ) ) {
		return new WP_Error( 'site_already_initialized', __( 'The site appears to be already initialized.' ) );
	}

	$network = get_network( $site->network_id );
	if ( ! $network ) {
		$network = get_network();
	}

	$args = wp_parse_args(
		$args,
		array(
			'user_id' => 0,
			/* translators: %d: Site ID. */
			'title'   => sprintf( __( 'Site %d' ), $site->id ),
			'options' => array(),
			'meta'    => array(),
		)
	);

	/**
	 * Filters the arguments for initializing a site.
	 *
	 * @since 5.1.0
	 *
	 * @param array      $args    Arguments to modify the initialization behavior.
	 * @param WP_Site    $site    Site that is being initialized.
	 * @param WP_Network $network Network that the site belongs to.
	 */
	$args = apply_filters( 'wp_initialize_site_args', $args, $site, $network );

	$orig_installing = wp_installing();
	if ( ! $orig_installing ) {
		wp_installing( true );
	}

	$switch = false;
	if ( get_current_blog_id() !== $site->id ) {
		$switch = true;
		switch_to_blog( $site->id );
	}

	require_once ABSPATH . 'wp-admin/includes/upgrade.php';

	// Set up the database tables.
	make_db_current_silent( 'blog' );

	$home_scheme    = 'http';
	$siteurl_scheme = 'http';
	if ( ! is_subdomain_install() ) {
		if ( 'https' === parse_url( get_home_url( $network->site_id ), PHP_URL_SCHEME ) ) {
			$home_scheme = 'https';
		}
		if ( 'https' === parse_url( get_network_option( $network->id, 'siteurl' ), PHP_URL_SCHEME ) ) {
			$siteurl_scheme = 'https';
		}
	}

	// Populate the site's options.
	populate_options(
		array_merge(
			array(
				'home'        => untrailingslashit( $home_scheme . '://' . $site->domain . $site->path ),
				'siteurl'     => untrailingslashit( $siteurl_scheme . '://' . $site->domain . $site->path ),
				'blogname'    => wp_unslash( $args['title'] ),
				'admin_email' => '',
				'upload_path' => get_network_option( $network->id, 'ms_files_rewriting' ) ? UPLOADBLOGSDIR . "/{$site->id}/files" : get_blog_option( $network->site_id, 'upload_path' ),
				'blog_public' => (int) $site->public,
				'WPLANG'      => get_network_option( $network->id, 'WPLANG' ),
			),
			$args['options']
		)
	);

	// Clean blog cache after populating options.
	clean_blog_cache( $site );

	// Populate the site's roles.
	populate_roles();
	$wp_roles = new WP_Roles();

	// Populate metadata for the site.
	populate_site_meta( $site->id, $args['meta'] );

	// Remove all permissions that may exist for the site.
	$table_prefix = $wpdb->get_blog_prefix();
	delete_metadata( 'user', 0, $table_prefix . 'user_level', null, true );   // Delete all.
	delete_metadata( 'user', 0, $table_prefix . 'capabilities', null, true ); // Delete all.

	// Install default site content.
	wp_install_defaults( $args['user_id'] );

	// Set the site administrator.
	add_user_to_blog( $site->id, $args['user_id'], 'administrator' );
	if ( ! user_can( $args['user_id'], 'manage_network' ) && ! get_user_meta( $args['user_id'], 'primary_blog', true ) ) {
		update_user_meta( $args['user_id'], 'primary_blog', $site->id );
	}

	if ( $switch ) {
		restore_current_blog();
	}

	wp_installing( $orig_installing );

	return true;
}

Multisite