wp_insert_site()
云策文档标注
概述
wp_insert_site() 函数用于向 WordPress 数据库插入一个新站点,适用于多站点网络。它接受一个数组参数来配置站点属性,并返回新站点的 ID 或 WP_Error 对象。
关键要点
- 参数 $data 为必需数组,包含域、路径、网络 ID 等字段,支持默认值如 domain 默认为空字符串,path 默认为 '/'。
- 函数执行时会触发 wp_insert_site、wp_initialize_site 和已弃用的 wpmu_new_blog 钩子,用于站点初始化和自定义操作。
- 返回值在成功时为整数站点 ID,失败时返回 WP_Error 对象,便于错误处理。
- 内部使用 wp_prepare_site_data() 准备数据,并依赖 wpdb::insert() 进行数据库操作,确保数据一致性。
代码示例
$site_id = wp_insert_site(array(
'domain' => 'example.com',
'path' => '/mysite',
'title' => 'My New Site',
'user_id' => 1
));
if (is_wp_error($site_id)) {
// 错误处理
}注意事项
- 确保在支持多站点的 WordPress 环境中使用此函数,否则可能引发错误。
- 参数如 user_id、title、options 和 meta 会传递给 wp_initialize_site 钩子,可用于扩展站点初始化逻辑。
- 注意 wpmu_new_blog 钩子已弃用,建议使用 wp_initialize_site 替代,以保持代码兼容性。
原文内容
Inserts a new site into the database.
Parameters
$dataarrayrequired-
Data for the new site that should be inserted.
domainstringSite domain. Default empty string.pathstringSite path. Default'/'.network_idintThe site’s network ID. Default is the current network ID.registeredstringWhen the site was registered, in SQL datetime format. Default is the current time.last_updatedstringWhen the site was last updated, in SQL datetime format. Default is the value of $registered.publicintWhether the site is public. Default 1.archivedintWhether the site is archived. Default 0.matureintWhether the site is mature. Default 0.spamintWhether the site is spam. Default 0.deletedintWhether the site is deleted. Default 0.lang_idintThe site’s language ID. Currently unused. Default 0.user_idintUser ID for the site administrator. Passed to thewp_initialize_sitehook.titlestringSite title. Default is ‘Site %d’ where %d is the site ID. Passed to thewp_initialize_sitehook.optionsarrayCustom option $key => $value pairs to use. Default empty array. Passed to thewp_initialize_sitehook.metaarrayCustom site metadata $key => $value pairs to use. Default empty array.
Passed to thewp_initialize_sitehook.
Source
function wp_insert_site( array $data ) {
global $wpdb;
$now = current_time( 'mysql', true );
$defaults = array(
'domain' => '',
'path' => '/',
'network_id' => get_current_network_id(),
'registered' => $now,
'last_updated' => $now,
'public' => 1,
'archived' => 0,
'mature' => 0,
'spam' => 0,
'deleted' => 0,
'lang_id' => 0,
);
$prepared_data = wp_prepare_site_data( $data, $defaults );
if ( is_wp_error( $prepared_data ) ) {
return $prepared_data;
}
if ( false === $wpdb->insert( $wpdb->blogs, $prepared_data ) ) {
return new WP_Error( 'db_insert_error', __( 'Could not insert site into the database.' ), $wpdb->last_error );
}
$site_id = (int) $wpdb->insert_id;
clean_blog_cache( $site_id );
$new_site = get_site( $site_id );
if ( ! $new_site ) {
return new WP_Error( 'get_site_error', __( 'Could not retrieve site data.' ) );
}
/**
* Fires once a site has been inserted into the database.
*
* @since 5.1.0
*
* @param WP_Site $new_site New site object.
*/
do_action( 'wp_insert_site', $new_site );
// Extract the passed arguments that may be relevant for site initialization.
$args = array_diff_key( $data, $defaults );
if ( isset( $args['site_id'] ) ) {
unset( $args['site_id'] );
}
/**
* Fires when a site's initialization routine should be executed.
*
* @since 5.1.0
*
* @param WP_Site $new_site New site object.
* @param array $args Arguments for the initialization.
*/
do_action( 'wp_initialize_site', $new_site, $args );
// Only compute extra hook parameters if the deprecated hook is actually in use.
if ( has_action( 'wpmu_new_blog' ) ) {
$user_id = ! empty( $args['user_id'] ) ? $args['user_id'] : 0;
$meta = ! empty( $args['options'] ) ? $args['options'] : array();
// WPLANG was passed with `$meta` to the `wpmu_new_blog` hook prior to 5.1.0.
if ( ! array_key_exists( 'WPLANG', $meta ) ) {
$meta['WPLANG'] = get_network_option( $new_site->network_id, 'WPLANG' );
}
/*
* Rebuild the data expected by the `wpmu_new_blog` hook prior to 5.1.0 using allowed keys.
* The `$allowed_data_fields` matches the one used in `wpmu_create_blog()`.
*/
$allowed_data_fields = array( 'public', 'archived', 'mature', 'spam', 'deleted', 'lang_id' );
$meta = array_merge( array_intersect_key( $data, array_flip( $allowed_data_fields ) ), $meta );
/**
* Fires immediately after a new site is created.
*
* @since MU (3.0.0)
* @deprecated 5.1.0 Use 'wp_initialize_site' instead.
*
* @param int $site_id Site ID.
* @param int $user_id User ID.
* @param string $domain Site domain.
* @param string $path Site path.
* @param int $network_id Network ID. Only relevant on multi-network installations.
* @param array $meta Meta data. Used to set initial site options.
*/
do_action_deprecated(
'wpmu_new_blog',
array( $new_site->id, $user_id, $new_site->domain, $new_site->path, $new_site->network_id, $meta ),
'5.1.0',
'wp_initialize_site'
);
}
return (int) $new_site->id;
}
Hooks
- do_action_deprecated( ‘wpmu_new_blog’, int $site_id, int $user_id, string $domain, string $path, int $network_id, array $meta )
-
Fires immediately after a new site is created.
- do_action( ‘wp_initialize_site’, WP_Site $new_site, array $args )
-
Fires when a site’s initialization routine should be executed.
- do_action( ‘wp_insert_site’, WP_Site $new_site )
-
Fires once a site has been inserted into the database.
Changelog
| Version | Description |
|---|---|
| 5.1.0 | Introduced. |
Skip to note 2 content
vee
To add/create/insert many sites at once. For testing purpose only. Use the code below
<br />
add_action('admin_head', function() {<br />
if (isset($_GET['test_create_site'])) {<br />
$current_network = get_current_site();<br />
$network_path = $current_network->path;<br />
$network = get_network();<br />
$main_domain = $network->domain;</p>
<p> for ($i = 1; $i $main_domain,<br />
'path' => $network_path . 'site' . $i,<br />
'title' => "Bulk Site $i",<br />
'user_id' => 1 // ID of the site admin<br />
));<br />
if (is_object($insert) && is_a($insert, 'WP_Error')) {<br />
wp_die($insert);<br />
}<br />
}<br />
}<br />
});<br />
Activate plugin and access any admin page with query string ?test_create_site=true but you have to be careful about timeout.