函数文档

wp_delete_site()

💡 云策文档标注

概述

wp_delete_site() 函数用于从数据库中删除一个站点,返回删除的站点对象或错误对象。它包含参数验证、钩子触发和数据库清理等步骤。

关键要点

  • 参数:$site_id(整数,必需),指定要删除的站点ID。
  • 返回值:成功时返回 WP_Site 对象,失败时返回 WP_Error 对象。
  • 验证:检查站点ID是否为空和站点是否存在,否则返回错误。
  • 钩子:触发 wp_validate_site_deletion、wp_uninitialize_site、wp_delete_site 等动作钩子,以及已弃用的 delete_blog 和 deleted_blog。
  • 清理:删除站点元数据(如果支持)、从数据库表中移除站点记录,并清理缓存。

代码示例

function wp_delete_site( $site_id ) {
    global $wpdb;

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

    $old_site = get_site( $site_id );
    if ( ! $old_site ) {
        return new WP_Error( 'site_not_exist', __( 'Site does not exist.' ) );
    }

    $errors = new WP_Error();
    do_action( 'wp_validate_site_deletion', $errors, $old_site );

    if ( ! empty( $errors->errors ) ) {
        return $errors;
    }

    do_action_deprecated( 'delete_blog', array( $old_site->id, true ), '5.1.0' );
    do_action( 'wp_uninitialize_site', $old_site );

    if ( is_site_meta_supported() ) {
        $blog_meta_ids = $wpdb->get_col( $wpdb->prepare( "SELECT meta_id FROM $wpdb->blogmeta WHERE blog_id = %d ", $old_site->id ) );
        foreach ( $blog_meta_ids as $mid ) {
            delete_metadata_by_mid( 'blog', $mid );
        }
    }

    if ( false === $wpdb->delete( $wpdb->blogs, array( 'blog_id' => $old_site->id ) ) ) {
        return new WP_Error( 'db_delete_error', __( 'Could not delete site from the database.' ), $wpdb->last_error );
    }

    clean_blog_cache( $old_site );
    do_action( 'wp_delete_site', $old_site );
    do_action_deprecated( 'deleted_blog', array( $old_site->id, true ), '5.1.0' );

    return $old_site;
}

注意事项

  • 该函数自 WordPress 5.1.0 版本引入。
  • 删除操作前会通过 wp_validate_site_deletion 钩子进行验证,插件可以添加错误以阻止删除。
  • 已弃用的钩子 delete_blog 和 deleted_blog 仍被触发,但建议使用新钩子。
  • 函数内部处理了站点元数据的删除(如果启用),并确保数据库操作失败时返回错误。

📄 原文内容

Deletes a site from the database.

Parameters

$site_idintrequired
ID of the site that should be deleted.

Return

WP_Site|WP_Error The deleted site object on success, or error object on failure.

Source

function wp_delete_site( $site_id ) {
	global $wpdb;

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

	$old_site = get_site( $site_id );
	if ( ! $old_site ) {
		return new WP_Error( 'site_not_exist', __( 'Site does not exist.' ) );
	}

	$errors = new WP_Error();

	/**
	 * Fires before a site should be deleted from the database.
	 *
	 * Plugins should amend the `$errors` object via its `WP_Error::add()` method. If any errors
	 * are present, the site will not be deleted.
	 *
	 * @since 5.1.0
	 *
	 * @param WP_Error $errors   Error object to add validation errors to.
	 * @param WP_Site  $old_site The site object to be deleted.
	 */
	do_action( 'wp_validate_site_deletion', $errors, $old_site );

	if ( ! empty( $errors->errors ) ) {
		return $errors;
	}

	/**
	 * Fires before a site is deleted.
	 *
	 * @since MU (3.0.0)
	 * @deprecated 5.1.0
	 *
	 * @param int  $site_id The site ID.
	 * @param bool $drop    True if site's table should be dropped. Default false.
	 */
	do_action_deprecated( 'delete_blog', array( $old_site->id, true ), '5.1.0' );

	/**
	 * Fires when a site's uninitialization routine should be executed.
	 *
	 * @since 5.1.0
	 *
	 * @param WP_Site $old_site Deleted site object.
	 */
	do_action( 'wp_uninitialize_site', $old_site );

	if ( is_site_meta_supported() ) {
		$blog_meta_ids = $wpdb->get_col( $wpdb->prepare( "SELECT meta_id FROM $wpdb->blogmeta WHERE blog_id = %d ", $old_site->id ) );
		foreach ( $blog_meta_ids as $mid ) {
			delete_metadata_by_mid( 'blog', $mid );
		}
	}

	if ( false === $wpdb->delete( $wpdb->blogs, array( 'blog_id' => $old_site->id ) ) ) {
		return new WP_Error( 'db_delete_error', __( 'Could not delete site from the database.' ), $wpdb->last_error );
	}

	clean_blog_cache( $old_site );

	/**
	 * Fires once a site has been deleted from the database.
	 *
	 * @since 5.1.0
	 *
	 * @param WP_Site $old_site Deleted site object.
	 */
	do_action( 'wp_delete_site', $old_site );

	/**
	 * Fires after the site is deleted from the network.
	 *
	 * @since 4.8.0
	 * @deprecated 5.1.0
	 *
	 * @param int  $site_id The site ID.
	 * @param bool $drop    True if site's tables should be dropped. Default false.
	 */
	do_action_deprecated( 'deleted_blog', array( $old_site->id, true ), '5.1.0' );

	return $old_site;
}

Hooks

do_action_deprecated( ‘deleted_blog’, int $site_id, bool $drop )

Fires after the site is deleted from the network.

do_action_deprecated( ‘delete_blog’, int $site_id, bool $drop )

Fires before a site is deleted.

do_action( ‘wp_delete_site’, WP_Site $old_site )

Fires once a site has been deleted from the database.

do_action( ‘wp_uninitialize_site’, WP_Site $old_site )

Fires when a site’s uninitialization routine should be executed.

do_action( ‘wp_validate_site_deletion’, WP_Error $errors, WP_Site $old_site )

Fires before a site should be deleted from the database.

Changelog

Version Description
5.1.0 Introduced.