函数文档

wp_delete_user()

💡 云策文档标注

概述

wp_delete_user() 是 WordPress 中用于删除用户的核心函数,支持可选地将用户的文章和链接重新分配给其他用户。在单站点环境中,用户会从数据库中完全删除;而在多站点环境中,用户仅从当前站点移除,不会从数据库删除。

关键要点

  • 函数接受两个参数:$id(必需,用户ID)和 $reassign(可选,新用户ID,默认为 null)。
  • 如果 $reassign 为 null,则删除用户的所有文章和链接;否则,将这些内容重新分配给指定用户。
  • 在插件中使用此函数时,必须包含 ./wp-admin/includes/user.php 文件,否则会引发“call to undefined function”错误。
  • 函数执行过程中会触发 'delete_user' 和 'deleted_user' 钩子,并应用 'post_types_to_delete_with_user' 过滤器。
  • 返回布尔值 true 表示操作完成,false 表示参数无效或用户不存在。

代码示例

// 示例:删除当前登录用户(需安全验证)
if ( is_user_logged_in() && ! empty( $_GET['DeleteMyAccount'] ) ) {
    add_action( 'init', 'wpdocs_remove_logged_in_user' );
}

function wpdocs_remove_logged_in_user() {
    if ( ! wp_verify_nonce( 'delete_account' ) ) {
        return;
    }
    require_once( ABSPATH . 'wp-admin/includes/user.php' );
    $current_user = wp_get_current_user();
    wp_delete_user( $current_user->ID );
}

注意事项

  • 在多站点安装中,用户仅从站点移除,不会从数据库删除,需使用 wpmu_delete_user() 进行完全删除。
  • 确保在调用前验证用户权限和参数,避免误操作。
  • 函数依赖于全局 $wpdb 对象,属于管理员函数,应在后台或受控环境中使用。

📄 原文内容

Delete user and optionally reassign posts and links to another user.

Description

Note that on a Multisite installation the user only gets removed from the site and does not get deleted from the database.

If the $reassign parameter is not assigned to a user ID, then all posts will be deleted of that user. The action ‘delete_user’ that is passed the user ID being deleted will be run after the posts are either reassigned or deleted.
The user meta will also be deleted that are for that user ID.

Parameters

$idintrequired
User ID.
$reassignintoptional
Reassign posts and links to new User ID.

Default:null

Return

bool True when finished.

More Information

  • If you wish to use this function in a plugin then you must include the ./wp-admin/includes/user.php file in your plugin function, else it will throw a ‘call to undefined function’ error
  • Uses global: (object) $wpdb
  • This is an Admin function.
  • Uses: do_action() Calls ‘deleted_user’ hook

Source

function wp_delete_user( $id, $reassign = null ) {
	global $wpdb;

	if ( ! is_numeric( $id ) ) {
		return false;
	}

	$id   = (int) $id;
	$user = new WP_User( $id );

	if ( ! $user->exists() ) {
		return false;
	}

	// Normalize $reassign to null or a user ID. 'novalue' was an older default.
	if ( 'novalue' === $reassign ) {
		$reassign = null;
	} elseif ( null !== $reassign ) {
		$reassign = (int) $reassign;
	}

	/**
	 * Fires immediately before a user is deleted from the site.
	 *
	 * Note that on a Multisite installation the user only gets removed from the site
	 * and does not get deleted from the database.
	 *
	 * @since 2.0.0
	 * @since 5.5.0 Added the `$user` parameter.
	 *
	 * @param int      $id       ID of the user to delete.
	 * @param int|null $reassign ID of the user to reassign posts and links to.
	 *                           Default null, for no reassignment.
	 * @param WP_User  $user     WP_User object of the user to delete.
	 */
	do_action( 'delete_user', $id, $reassign, $user );

	if ( null === $reassign ) {
		$post_types_to_delete = array();
		foreach ( get_post_types( array(), 'objects' ) as $post_type ) {
			if ( $post_type->delete_with_user ) {
				$post_types_to_delete[] = $post_type->name;
			} elseif ( null === $post_type->delete_with_user && post_type_supports( $post_type->name, 'author' ) ) {
				$post_types_to_delete[] = $post_type->name;
			}
		}

		/**
		 * Filters the list of post types to delete with a user.
		 *
		 * @since 3.4.0
		 *
		 * @param string[] $post_types_to_delete Array of post types to delete.
		 * @param int      $id                   User ID.
		 */
		$post_types_to_delete = apply_filters( 'post_types_to_delete_with_user', $post_types_to_delete, $id );
		$post_types_to_delete = implode( "', '", $post_types_to_delete );
		$post_ids             = $wpdb->get_col( $wpdb->prepare( "SELECT ID FROM $wpdb->posts WHERE post_author = %d AND post_type IN ('$post_types_to_delete')", $id ) );
		if ( $post_ids ) {
			foreach ( $post_ids as $post_id ) {
				wp_delete_post( $post_id );
			}
		}

		// Clean links.
		$link_ids = $wpdb->get_col( $wpdb->prepare( "SELECT link_id FROM $wpdb->links WHERE link_owner = %d", $id ) );

		if ( $link_ids ) {
			foreach ( $link_ids as $link_id ) {
				wp_delete_link( $link_id );
			}
		}
	} else {
		$post_ids = $wpdb->get_col( $wpdb->prepare( "SELECT ID FROM $wpdb->posts WHERE post_author = %d", $id ) );
		$wpdb->update( $wpdb->posts, array( 'post_author' => $reassign ), array( 'post_author' => $id ) );
		if ( ! empty( $post_ids ) ) {
			foreach ( $post_ids as $post_id ) {
				clean_post_cache( $post_id );
			}
		}
		$link_ids = $wpdb->get_col( $wpdb->prepare( "SELECT link_id FROM $wpdb->links WHERE link_owner = %d", $id ) );
		$wpdb->update( $wpdb->links, array( 'link_owner' => $reassign ), array( 'link_owner' => $id ) );
		if ( ! empty( $link_ids ) ) {
			foreach ( $link_ids as $link_id ) {
				clean_bookmark_cache( $link_id );
			}
		}
	}

	// FINALLY, delete user.
	if ( is_multisite() ) {
		remove_user_from_blog( $id, get_current_blog_id() );
	} else {
		$meta = $wpdb->get_col( $wpdb->prepare( "SELECT umeta_id FROM $wpdb->usermeta WHERE user_id = %d", $id ) );
		foreach ( $meta as $mid ) {
			delete_metadata_by_mid( 'user', $mid );
		}

		$wpdb->delete( $wpdb->users, array( 'ID' => $id ) );
	}

	clean_user_cache( $user );

	/**
	 * Fires immediately after a user is deleted from the site.
	 *
	 * Note that on a Multisite installation the user may not have been deleted from
	 * the database depending on whether `wp_delete_user()` or `wpmu_delete_user()`
	 * was called.
	 *
	 * @since 2.9.0
	 * @since 5.5.0 Added the `$user` parameter.
	 *
	 * @param int      $id       ID of the deleted user.
	 * @param int|null $reassign ID of the user to reassign posts and links to.
	 *                           Default null, for no reassignment.
	 * @param WP_User  $user     WP_User object of the deleted user.
	 */
	do_action( 'deleted_user', $id, $reassign, $user );

	return true;
}

Hooks

do_action( ‘deleted_user’, int $id, int|null $reassign, WP_User $user )

Fires immediately after a user is deleted from the site.

do_action( ‘delete_user’, int $id, int|null $reassign, WP_User $user )

Fires immediately before a user is deleted from the site.

apply_filters( ‘post_types_to_delete_with_user’, string[] $post_types_to_delete, int $id )

Filters the list of post types to delete with a user.

Changelog

Version Description
2.0.0 Introduced.

User Contributed Notes

  1. Skip to note 3 content

    Allow users to terminate their user accounts.

    if ( is_user_logged_in() && ! empty( $_GET['DeleteMyAccount'] ) ) {
    	add_action( 'init', 'wpdocs_remove_logged_in_user' );
    }
    
    /**
     * Remove the logged in user.
     */
    function wpdocs_remove_logged_in_user() {
    	// Verify that the user intended to take this action.
    	if ( ! wp_verify_nonce( 'delete_account' ) ) {
    		return;
    	}
    
    	require_once( ABSPATH.'wp-admin/includes/user.php' );
    	$current_user = wp_get_current_user();
    	wp_delete_user( $current_user->ID );
    }

  2. Skip to note 4 content

    /**
    * Delete User based on some meta keys
    * Check For Deletion Status if it is 1 then user is deleted
    **/
    $site_id     = 123;
    $client_id   = 1;
    $mem_id      = 2;
    require_once( ABSPATH.'wp-admin/includes/user.php' );
    //get single user based on multiple meta keys
    $user = 
          reset(
               get_users(
                  array(
                        'role'       => 'subscriber',
                        'count_total'=> false,
                        'number'     => 1,
                        'meta_query' => array(
                            array(
                                'key'     => 'mb_client_id',
                                'value'   => $client_id,
                                'compare' => '=='
                            ),
                            array(
                                'key'     => 'mb_site_id',
                                'value'   => $site_id,
                                'compare' => '=='
                            ),
                            array(
                                'key'     => 'mb_membership_id',
                                'value'   => $mem_id,
                                'compare' => '=='
                            )
                        )
                    )
                )
            );
    // If user exists
    if ( $user ) {
    	$response = wp_delete_user( $user->ID );
        if ( $response == 1 ) {
    	return array(
    		'code'   => 'valid_data',
            'data'   => array(
            'status' => 200,
            )
          );
        } else {
    			wp_die( "user_not_deleted" );
          }
     } else {
    		wp_die( "user_not_deleted" );
     }