函数文档

wp_uninitialize_site()

💡 云策文档标注

概述

wp_uninitialize_site() 函数用于执行指定站点的反初始化流程,包括删除数据库表和上传目录。它接受站点ID或对象作为参数,返回成功状态或WP_Error对象。

关键要点

  • 函数功能:运行站点的反初始化程序,删除数据库表和上传目录。
  • 参数:$site_id(int|WP_Site),必需,站点ID或对象。
  • 返回值:成功时返回true,失败时返回WP_Error对象。
  • 错误处理:检查站点ID是否为空、站点是否存在以及是否已反初始化。
  • 操作步骤:移除站点用户、切换博客上下文、删除数据库表(通过wpmu_drop_tables过滤器)和上传目录(通过wpmu_delete_blog_upload_dir过滤器)。
  • 相关函数:包括wp_is_site_initialized()、get_site()、wp_get_upload_dir()等。
  • 引入版本:WordPress 5.1.0。

代码示例

function wp_uninitialize_site( $site_id ) {
    global $wpdb;

    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_uninitialized', __( 'The site appears to be already uninitialized.' ) );
    }

    $users = get_users(
        array(
            'blog_id' => $site->id,
            'fields'  => 'ids',
        )
    );

    if ( ! empty( $users ) ) {
        foreach ( $users as $user_id ) {
            remove_user_from_blog( $user_id, $site->id );
        }
    }

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

    $uploads = wp_get_upload_dir();
    $tables = $wpdb->tables( 'blog' );
    $drop_tables = apply_filters( 'wpmu_drop_tables', $tables, $site->id );

    foreach ( (array) $drop_tables as $table ) {
        $wpdb->query( "DROP TABLE IF EXISTS `$table`" );
    }

    $dir = apply_filters( 'wpmu_delete_blog_upload_dir', $uploads['basedir'], $site->id );
    $dir = rtrim( $dir, DIRECTORY_SEPARATOR );
    $top_dir = $dir;
    $stack = array( $dir );
    $index = 0;

    while ( $index < count( $stack ) ) {
        // 目录删除逻辑(此处省略完整代码)
        $index++;
    }

    if ( $switch ) {
        restore_current_blog();
    }

    return true;
}

注意事项

  • 使用前需确保站点存在且已初始化,否则会返回WP_Error。
  • 函数涉及数据库操作和文件删除,应谨慎调用,建议在管理界面或安全上下文中使用。
  • 通过wpmu_drop_tables和wpmu_delete_blog_upload_dir过滤器可以自定义要删除的表和目录。
  • 函数会切换博客上下文,操作完成后恢复原上下文。
  • 引入于WordPress 5.1.0,旧版本不可用。

📄 原文内容

Runs the uninitialization routine for a given site.

Description

This process includes dropping the site’s database tables and deleting its uploads directory.

Parameters

$site_idint|WP_Siterequired
Site ID or object.

Return

true|WP_Error True on success, or error object on failure.

Source

function wp_uninitialize_site( $site_id ) {
	global $wpdb;

	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_uninitialized', __( 'The site appears to be already uninitialized.' ) );
	}

	$users = get_users(
		array(
			'blog_id' => $site->id,
			'fields'  => 'ids',
		)
	);

	// Remove users from the site.
	if ( ! empty( $users ) ) {
		foreach ( $users as $user_id ) {
			remove_user_from_blog( $user_id, $site->id );
		}
	}

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

	$uploads = wp_get_upload_dir();

	$tables = $wpdb->tables( 'blog' );

	/**
	 * Filters the tables to drop when the site is deleted.
	 *
	 * @since MU (3.0.0)
	 *
	 * @param string[] $tables  Array of names of the site tables to be dropped.
	 * @param int      $site_id The ID of the site to drop tables for.
	 */
	$drop_tables = apply_filters( 'wpmu_drop_tables', $tables, $site->id );

	foreach ( (array) $drop_tables as $table ) {
		$wpdb->query( "DROP TABLE IF EXISTS `$table`" ); // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared
	}

	/**
	 * Filters the upload base directory to delete when the site is deleted.
	 *
	 * @since MU (3.0.0)
	 *
	 * @param string $basedir Uploads path without subdirectory. See <a href="https://developer.wordpress.org/reference/functions/wp_upload_dir/">wp_upload_dir()</a>.
	 * @param int    $site_id The site ID.
	 */
	$dir     = apply_filters( 'wpmu_delete_blog_upload_dir', $uploads['basedir'], $site->id );
	$dir     = rtrim( $dir, DIRECTORY_SEPARATOR );
	$top_dir = $dir;
	$stack   = array( $dir );
	$index   = 0;

	while ( $index < count( $stack ) ) {
		// Get indexed directory from stack.
		$dir = $stack[ $index ];

		// phpcs:disable WordPress.PHP.NoSilencedErrors.Discouraged
		$dh = @opendir( $dir );
		if ( $dh ) {
			$file = @readdir( $dh );
			while ( false !== $file ) {
				if ( '.' === $file || '..' === $file ) {
					$file = @readdir( $dh );
					continue;
				}

				if ( @is_dir( $dir . DIRECTORY_SEPARATOR . $file ) ) {
					$stack[] = $dir . DIRECTORY_SEPARATOR . $file;
				} elseif ( @is_file( $dir . DIRECTORY_SEPARATOR . $file ) ) {
					@unlink( $dir . DIRECTORY_SEPARATOR . $file );
				}

				$file = @readdir( $dh );
			}
			@closedir( $dh );
		}
		++$index;
	}

	$stack = array_reverse( $stack ); // Last added directories are deepest.
	foreach ( (array) $stack as $dir ) {
		if ( $dir !== $top_dir ) {
			@rmdir( $dir );
		}
	}

	// phpcs:enable WordPress.PHP.NoSilencedErrors.Discouraged
	if ( $switch ) {
		restore_current_blog();
	}

	return true;
}

Hooks

apply_filters( ‘wpmu_delete_blog_upload_dir’, string $basedir, int $site_id )

Filters the upload base directory to delete when the site is deleted.

apply_filters( ‘wpmu_drop_tables’, string[] $tables, int $site_id )

Filters the tables to drop when the site is deleted.

Changelog

Version Description
5.1.0 Introduced.