# wp_insert_user()

URL: https://chugunov.pro/api-wordpress/functions/wp_insert_user/
Проверено на WordPress 6.9, обновлено 06.08.2026.
Источник: независимый русскоязычный справочник chugunov.pro. Не является официальной документацией WordPress.

Тип: функция.
Появился в версии: 2.0.0.

## Сигнатура

```php
wp_insert_user( array|object|WP_User $userdata ): int|WP_Error
```

## Описание

С большинством полей массива $userdata связаны фильтры значений. Исключения — 'ID', 'rich_editing', 'syntax_highlighting', 'comment_shortcuts', 'admin_color', 'use_ssl', 'user_registered', 'user_activation_key', 'spam' и 'role'. Фильтры имеют префикс 'pre_user_', за которым следует имя поля. Например, для поля 'description' будет фильтр 'pre_user_description', к которому можно подключиться.

## Параметры

- `$userdata` `array|object|WP_User` — обязательный. Массив, объект или объект WP_User с аргументами данных пользователя.
  
  ID int ID пользователя. Если указан, пользователь будет обновлён.
  
  user_pass string Пароль пользователя в открытом виде для новых пользователей.
  
  Хешированный пароль для существующих пользователей.
  
  user_login string Логин пользователя.
  
  user_nicename string URL-совместимое имя пользователя.
  
  user_url string URL пользователя.
  
  user_email string Адрес электронной почты пользователя.
  
  display_name string Отображаемое имя пользователя.
  
  По умолчанию — логин пользователя.
  
  nickname string Псевдоним пользователя.
  
  По умолчанию — логин пользователя.
  
  first_name string Имя пользователя. Для новых пользователей используется для формирования первой части отображаемого имени, если $display_name не указано.
  
  last_name string Фамилия пользователя. Для новых пользователей используется для формирования второй части отображаемого имени, если $display_name не указано.
  
  description string Биографическое описание пользователя.
  
  rich_editing string Включать ли визуальный редактор для пользователя.
  
  Принимает 'true' или 'false' как строковый литерал, а не логическое значение. Значение по умолчанию 'true'.
  
  syntax_highlighting string Включать ли редактор кода с подсветкой для пользователя.
  
  Принимает 'true' или 'false' как строковый литерал, а не логическое значение. Значение по умолчанию 'true'.
  
  comment_shortcuts string Включать ли клавиатурные сокращения для модерации комментариев для пользователя. Принимает 'true' или 'false' как строковый литерал, а не логическое значение. Значение по умолчанию 'false'.
  
  admin_color string Цветовая схема администрирования для пользователя. Значение по умолчанию 'modern'.
  
  use_ssl bool Должен ли пользователь всегда обращаться к панели администрирования по https. Значение по умолчанию false.
  
  user_registered string Дата регистрации пользователя в UTC. Формат — 'Y-m-d H:i:s'.
  
  user_activation_key string Ключ сброса пароля. По умолчанию пусто.
  
  spam bool Только Multisite. Помечен ли пользователь как спам.
  
  Значение по умолчанию false.
  
  show_admin_bar_front string Отображать ли панель администрирования для пользователя в публичной части сайта. Принимает 'true' или 'false' как строковый литерал, а не логическое значение. Значение по умолчанию 'true'.
  
  role string Роль пользователя.
  
  locale string Локаль пользователя. По умолчанию пусто.
  
  meta_input array Массив произвольных значений метаданных пользователя с ключами по ключу метаданных.
  
  По умолчанию пусто.

## Возвращаемое значение

`int|WP_Error` — WP_Error

## Исходный код

Файл: `wp-includes/user.php:2205`

```php
function wp_insert_user( $userdata ) {
	global $wpdb;

	if ( $userdata instanceof stdClass ) {
		$userdata = get_object_vars( $userdata );
	} elseif ( $userdata instanceof WP_User ) {
		$userdata = $userdata->to_array();
	} elseif ( $userdata instanceof Traversable ) {
		$userdata = iterator_to_array( $userdata );
	} elseif ( $userdata instanceof ArrayAccess ) {
		$userdata_obj = $userdata;
		$userdata     = array();
		foreach (
			array(
				'ID',
				'user_pass',
				'user_login',
				'user_nicename',
				'user_url',
				'user_email',
				'display_name',
				'nickname',
				'first_name',
				'last_name',
				'description',
				'rich_editing',
				'syntax_highlighting',
				'comment_shortcuts',
				'admin_color',
				'use_ssl',
				'user_registered',
				'user_activation_key',
				'spam',
				'show_admin_bar_front',
				'role',
				'locale',
				'meta_input',
			) as $key
		) {
			if ( isset( $userdata_obj[ $key ] ) ) {
				$userdata[ $key ] = $userdata_obj[ $key ];
			}
		}
	} else {
		$userdata = (array) $userdata;
	}

	// Are we updating or creating?
	if ( ! empty( $userdata['ID'] ) ) {
		$user_id       = (int) $userdata['ID'];
		$update        = true;
		$old_user_data = get_userdata( $user_id );

		if ( ! $old_user_data ) {
			return new WP_Error( 'invalid_user_id', __( 'Invalid user ID.' ) );
		}

		// Slash current user email to compare it later with slashed new user email.
		$old_user_data->user_email = wp_slash( $old_user_data->user_email );

		// Hashed in wp_update_user(), plaintext if called directly.
		$user_pass = ! empty( $userdata['user_pass'] ) ? $userdata['user_pass'] : $old_user_data->user_pass;
	} else {
		$update = false;

		if ( empty( $userdata['user_pass'] ) ) {
			wp_trigger_error(
				__FUNCTION__,
				__( 'The user_pass field is required when creating a new user. The user will need to reset their password before logging in.' ),
				E_USER_WARNING
			);

			// Set the password as an empty string to force the password reset flow.
			$userdata['user_pass'] = '';
		}

		// Hash the password.
		$user_pass = wp_hash_password( $userdata['user_pass'] );
	}

	$sanitized_user_login = sanitize_user( $userdata['user_login'] ?? '', true );

	/**
	 * Filters a username after it has been sanitized.
	 *
	 * This filter is called before the user is created or updated.
	 *
	 * @since 2.0.3
	 *
	 * @param string $sanitized_user_login Username after it has been sanitized.
	 */
	$pre_user_login = apply_filters( 'pre_user_login', $sanitized_user_login );

	// Remove any non-printable chars from the login string to see if we have ended up with an empty username.
	$user_login = trim( $pre_user_login );

	// user_login must be between 0 and 60 characters.
	if ( empty( $user_login ) ) {
		return new WP_Error( 'empty_user_login', __( 'Cannot create a user with an empty login name.' ) );
	} elseif ( mb_strlen( $user_login ) > 60 ) {
		return new WP_Error( 'user_login_too_long', __( 'Username may not be longer than 60 characters.' ) );
	}

	if ( ! $update && username_exists( $user_login ) ) {
		return new WP_Error( 'existing_user_login', __( 'Sorry, that username already exists!' ) );
	}

	/**
	 * Filters the list of disallowed usernames.
	 *
	 * @since 4.4.0
	 *
	 * @param array $usernames Array of disallowed usernames.
	 */
	$illegal_logins = (array) apply_filters( 'illegal_user_logins', array() );

	if ( in_array( strtolower( $user_login ), array_map( 'strtolower', $illegal_logins ), true ) ) {
		return new WP_Error( 'invalid_username', __( 'Sorry, that username is not allowed.' ) );
	}

	/*
	 * If a nicename is provided, remove unsafe user characters before using it.
	 * Otherwise build a nicename from the user_login.
	 */
	if ( ! empty( $userdata['user_nicename'] ) ) {
		$user_nicename = sanitize_user( $userdata['user_nicename'], true );
	} else {
		$user_nicename = mb_substr( $user_login, 0, 50 );
	}

	$user_nicename = sanitize_title( $user_nicename );

	/**
	 * Filters a user's nicename before the user is created or updated.
	 *
	 * @since 2.0.3
	 *
	 * @param string $user_nicename The user's nicename.
	 */
	$user_nicename = apply_filters( 'pre_user_nicename', $user_nicename );

	// Check if the sanitized nicename is empty.
	if ( empty( $user_nicename ) ) {
		return new WP_Error( 'empty_user_nicename', __( 'Cannot create a user with an empty nicename.' ) );
	} elseif ( mb_strlen( $user_nicename ) > 50 ) {
		return new WP_Error( 'user_nicename_too_long', __( 'Nicename may not be longer than 50 characters.' ) );
	}

	$user_nicename_check = $wpdb->get_var( $wpdb->prepare( "SELECT ID FROM $wpdb->users WHERE user_nicename = %s AND user_login != %s LIMIT 1", $user_nicename, $user_login ) );

	if ( $user_nicename_check ) {
		$suffix = 2;
		while ( $user_nicename_check ) {
			// user_nicename allows 50 chars. Subtract one for a hyphen, plus the length of the suffix.
			$base_length         = 49 - mb_strlen( $suffix );
			$alt_user_nicename   = mb_substr( $user_nicename, 0, $base_length ) . "-$suffix";
			$user_nicename_check = $wpdb->get_var( $wpdb->prepare( "SELECT ID FROM $wpdb->users WHERE user_nicename = %s AND user_login != %s LIMIT 1", $alt_user_nicename, $user_login ) );
			++$suffix;
		}
		$user_nicename = $alt_user_nicename;
	}

	$raw_user_email = empty( $userdata['user_email'] ) ? '' : $userdata['user_email'];

	/**
	 * Filters a user's email before the user is created or updated.
	 *
	 * @since 2.0.3
	 *
	 * @param string $raw_user_email The user's email.
	 */
	$user_email = apply_filters( 'pre_user_email', $raw_user_email );

	/*
	 * If there is no update, just check for `email_exists`. If there is an update,
	 * check if current email and new email are the same, and check `email_exists`
	 * accordingly.
	 */
	if ( ( ! $update || ( ! empty( $old_user_data ) && 0 !== strcasecmp( $user_email, $old_user_data->user_email ) ) )
		&& ! defined( 'WP_IMPORTING' )
		&& email_exists( $user_email )
	) {
		return new WP_Error( 'existing_user_email', __( 'Sorry, that email address is already used!' ) );
	}

	$raw_user_url = empty( $userdata['user_url'] ) ? '' : $userdata['user_url'];

	/**
	 * Filters a user's URL before the user is created or updated.
	 *
	 * @since 2.0.3
	 *
	 * @param string $raw_user_url The user's URL.
	 */
	$user_url = apply_filters( 'pre_user_url', $raw_user_url );

	if ( mb_strlen( $user_url ) > 100 ) {
		return new WP_Error( 'user_url_too_long', __( 'User URL may not be longer than 100 characters.' ) );
	}

	$user_registered = empty( $userdata['user_registered'] ) ? gmdate( 'Y-m-d H:i:s' ) : $userdata['user_registered'];

	$user_activation_key = empty( $userdata['user_activation_key'] ) ? '' : $userdata['user_activation_key'];

	if ( ! empty( $userdata['spam'] ) && ! is_multisite() ) {
		return new WP_Error( 'no_spam', __( 'Sorry, marking a user as spam is only supported on Multisite.' ) );
	}

	$spam = empty( $userdata['spam'] ) ? 0 : (bool) $userdata['spam'];

	// Store values to save in user meta.
	$meta = array();

	$nickname = empty( $userdata['nickname'] ) ? $user_login : $userdata['nickname'];

	/**
	 * Filters a user's nickname before the user is created or updated.
	 *
	 * @since 2.0.3
	 *
	 * @param string $nickname The user's nickname.
	 */
	$meta['nickname'] = apply_filters( 'pre_user_nickname', $nickname );

	$first_name = empty( $userdata['first_name'] ) ? '' : $userdata['first_name'];

	/**
	 * Filters a user's first name before the user is created or updated.
	 *
	 * @since 2.0.3
	 *
	 * @param string $first_name The user's first name.
	 */
	$meta['first_name'] = apply_filters( 'pre_user_first_name', $first_name );

	$last_name = empty( $userdata['last_name'] ) ? '' : $userdata['last_name'];

	/**
	 * Filters a user's last name before the user is created or updated.
	 *
	 * @since 2.0.3
	 *
	 * @param string $last_name The user's last name.
	 */
	$meta['last_name'] = apply_filters( 'pre_user_last_name', $last_name );

	if ( empty( $userdata['display_name'] ) ) {
		if ( $update ) {
			$display_name = $user_login;
		} elseif ( $meta['first_name'] && $meta['last_name'] ) {
			$display_name = sprintf(
				/* translators: 1: User's first name, 2: Last name. */
				_x( '%1$s %2$s', 'Display name based on first name and last name' ),
				$meta['first_name'],
				$meta['last_name']
			);
		} elseif ( $meta['first_name'] ) {
			$display_name = $meta['first_name'];
		} elseif ( $meta['last_name'] ) {
			$display_name = $meta['last_name'];
		} else {
			$display_name = $user_login;
		}
	} else {
		$display_name = $userdata['display_name'];
	}

	/**
	 * Filters a user's display name before the user is created or updated.
	 *
	 * @since 2.0.3
	 *
	 * @param string $display_name The user's display name.
	 */
	$display_name = apply_filters( 'pre_user_display_name', $display_name );

	$description = empty( $userdata['description'] ) ? '' : $userdata['description'];

	/**
	 * Filters a user's description before the user is created or updated.
	 *
	 * @since 2.0.3
	 *
	 * @param string $description The user's description.
	 */
	$meta['description'] = apply_filters( 'pre_user_description', $description );

	$meta['rich_editing'] = empty( $userdata['rich_editing'] ) ? 'true' : $userdata['rich_editing'];

	$meta['syntax_highlighting'] = empty( $userdata['syntax_highlighting'] ) ? 'true' : $userdata['syntax_highlighting'];

	$meta['comment_shortcuts'] = empty( $userdata['comment_shortcuts'] ) || 'false' === $userdata['comment_shortcuts'] ? 'false' : 'true';

	$admin_color         = empty( $userdata['admin_color'] ) ? 'modern' : $userdata['admin_color'];
	$meta['admin_color'] = preg_replace( '|[^a-z0-9 _.\-@]|i', '', $admin_color );

	$meta['use_ssl'] = empty( $userdata['use_ssl'] ) ? '0' : '1';

	$meta['show_admin_bar_front'] = empty( $userdata['show_admin_bar_front'] ) ? 'true' : $userdata['show_admin_bar_front'];

	$meta['locale'] = $userdata['locale'] ?? '';

	$compacted = compact( 'user_pass', 'user_nicename', 'user_email', 'user_url', 'user_registered', 'user_activation_key', 'display_name' );
	$data      = wp_unslash( $compacted );

	if ( ! $update ) {
		$data = $data + compact( 'user_login' );
	}

	if ( is_multisite() ) {
		$data = $data + compact( 'spam' );
	}

	/**
	 * Filters user data before the record is created or updated.
	 *
	 * It only includes data in the users table, not any user metadata.
	 *
	 * @since 4.9.0
	 * @since 5.8.0 The `$userdata` parameter was added.
	 * @since 6.8.0 The user's password is now hashed using bcrypt by default instead of phpass.
	 *
	 * @param array    $data {
	 *     Values and keys for the user.
	 *
	 *     @type string $user_login      The user's login. Only included if $update == false
	 *     @type string $user_pass       The user's password.
	 *     @type string $user_email      The user's email.
	 *     @type string $user_url        The user's url.
	 *     @type string $user_nicename   The user's nice name. Defaults to a URL-safe version of user's login.
	 *     @type string $display_name    The user's display name.
	 *     @type string $user_registered MySQL timestamp describing the moment when the user registered. Defaults to
	 *                                   the current UTC timestamp.
	 * }
	 * @param bool     $update   Whether the user is being updated rather than created.
	 * @param int|null $user_id  ID of the user to be updated, or NULL if the user is being created.
	 * @param array    $userdata The raw array of data passed to wp_insert_user().
	 */
	$data = apply_filters( 'wp_pre_insert_user_data', $data, $update, ( $update ? $user_id : null ), $userdata );

	if ( empty( $data ) || ! is_array( $data ) ) {
		return new WP_Error( 'empty_data', __( 'Not enough data to create this user.' ) );
	}

	if ( $update ) {
		if ( $user_email !== $old_user_data->user_email || $user_pass !== $old_user_data->user_pass ) {
			$data['user_activation_key'] = '';
		}
		$wpdb->update( $wpdb->users, $data, array( 'ID' => $user_id ) );
	} else {
		$wpdb->insert( $wpdb->users, $data );
		$user_id = (int) $wpdb->insert_id;
	}

	$user = new WP_User( $user_id );

	if ( ! $update ) {
		/** This action is documented in wp-includes/pluggable.php */
		do_action( 'wp_set_password', $userdata['user_pass'], $user_id, $user );
	}

	/**
	 * Filters a user's meta values and keys immediately after the user is created or updated
	 * and before any user meta is inserted or updated.
	 *
	 * Does not include contact methods. These are added using `wp_get_user_contact_methods( $user )`.
	 *
	 * For custom meta fields, see the 'insert_custom_user_meta' filter.
	 *
	 * @since 4.4.0
	 * @since 5.8.0 The `$userdata` parameter was added.
	 *
	 * @param array $meta {
	 *     Default meta values and keys for the user.
	 *
	 *     @type string   $nickname             The user's nickname. Default is the user's username.
	 *     @type string   $first_name           The user's first name.
	 *     @type string   $last_name            The user's last name.
	 *     @type string   $description          The user's description.
	 *     @type string   $rich_editing         Whether to enable the rich-editor for the user. Default 'true'.
	 *     @type string   $syntax_highlighting  Whether to enable the rich code editor for the user. Default 'true'.
	 *     @type string   $comment_shortcuts    Whether to enable keyboard shortcuts for the user. Default 'false'.
	 *     @type string   $admin_color          The color scheme for a user's admin screen. Default 'modern'.
	 *     @type int|bool $use_ssl              Whether to force SSL on the user's admin area. 0|false if SSL
	 *                                          is not forced.
	 *     @type string   $show_admin_bar_front Whether to show the admin bar on the front end for the user.
	 *                                          Default 'true'.
	 *     @type string   $locale               User's locale. Default empty.
	 * }
	 * @param WP_User $user     User object.
	 * @param bool    $update   Whether the user is being updated rather than created.
	 * @param array   $userdata The raw array of data passed to wp_insert_user().
	 */
	$meta = apply_filters( 'insert_user_meta', $meta, $user, $update, $userdata );

	$custom_meta = array();
	if ( array_key_exists( 'meta_input', $userdata ) && is_array( $userdata['meta_input'] ) && ! empty( $userdata['meta_input'] ) ) {
		$custom_meta = $userdata['meta_input'];
	}

	/**
	 * Filters a user's custom meta values and keys immediately after the user is created or updated
	 * and before any user meta is inserted or updated.
	 *
	 * For non-custom meta fields, see the 'insert_user_meta' filter.
	 *
	 * @since 5.9.0
	 *
	 * @param array   $custom_meta Array of custom user meta values keyed by meta key.
	 * @param WP_User $user        User object.
	 * @param bool    $update      Whether the user is being updated rather than created.
	 * @param array   $userdata    The raw array of data passed to wp_insert_user().
	 */
	$custom_meta = apply_filters( 'insert_custom_user_meta', $custom_meta, $user, $update, $userdata );

	$meta = array_merge( $meta, $custom_meta );

	if ( $update ) {
		// Update user meta.
		foreach ( $meta as $key => $value ) {
			update_user_meta( $user_id, $key, $value );
		}
	} else {
		// Add user meta.
		foreach ( $meta as $key => $value ) {
			add_user_meta( $user_id, $key, $value );
		}
	}

	foreach ( wp_get_user_contact_methods( $user ) as $key => $value ) {
		if ( isset( $userdata[ $key ] ) ) {
			update_user_meta( $user_id, $key, $userdata[ $key ] );
		}
	}

	if ( isset( $userdata['role'] ) ) {
		$user->set_role( $userdata['role'] );
	} elseif ( ! $update ) {
		$user->set_role( get_option( 'default_role' ) );
	}

	clean_user_cache( $user_id );

	if ( $update ) {
		/**
		 * Fires immediately after an existing user is updated.
		 *
		 * @since 2.0.0
		 * @since 5.8.0 The `$userdata` parameter was added.
		 *
		 * @param int     $user_id       User ID.
		 * @param WP_User $old_user_data Object containing user's data prior to update.
		 * @param array   $userdata      The raw array of data passed to wp_insert_user().
		 */
		do_action( 'profile_update', $user_id, $old_user_data, $userdata );

		if ( isset( $userdata['spam'] ) && $userdata['spam'] !== $old_user_data->spam ) {
			if ( '1' === $userdata['spam'] ) {
				/**
				 * Fires after the user is marked as a SPAM user.
				 *
				 * @since 3.0.0
				 *
				 * @param int $user_id ID of the user marked as SPAM.
				 */
				do_action( 'make_spam_user', $user_id );
			} else {
				/**
				 * Fires after the user is marked as a HAM user. Opposite of SPAM.
				 *
				 * @since 3.0.0
				 *
				 * @param int $user_id ID of the user marked as HAM.
				 */
				do_action( 'make_ham_user', $user_id );
			}
		}
	} else {
		/**
		 * Fires immediately after a new user is registered.
		 *
		 * @since 1.5.0
		 * @since 5.8.0 The `$userdata` parameter was added.
		 *
		 * @param int   $user_id  User ID.
		 * @param array $userdata The raw array of data passed to wp_insert_user().
		 */
		do_action( 'user_register', $user_id, $userdata );
	}

	return $user_id;
}
```

## История изменений

- 5.9.0 — The meta_input field can be passed to $userdata to allow addition of user meta data.
- 5.3.0 — The spam field can be passed to $userdata (Multisite only).
- 4.7.0 — The locale field can be passed to $userdata.
- 3.6.0 — The aim, jabber, and yim fields were removed as default user contact methods for new installations. See wp_get_user_contact_methods() .
- 2.0.0 — Introduced.

## Связанные

Использует: [`wp_trigger_error`](https://chugunov.pro/api-wordpress/functions/wp_trigger_error/), `WP_User::__construct`, [`sanitize_user`](https://chugunov.pro/api-wordpress/functions/sanitize_user/), [`sanitize_title`](https://chugunov.pro/api-wordpress/functions/sanitize_title/), [`wp_hash_password`](https://chugunov.pro/api-wordpress/functions/wp_hash_password/), [`wp_get_user_contact_methods`](https://chugunov.pro/api-wordpress/functions/wp_get_user_contact_methods/), [`username_exists`](https://chugunov.pro/api-wordpress/functions/username_exists/), [`email_exists`](https://chugunov.pro/api-wordpress/functions/email_exists/), [`clean_user_cache`](https://chugunov.pro/api-wordpress/functions/clean_user_cache/), [`update_user_meta`](https://chugunov.pro/api-wordpress/functions/update_user_meta/), [`add_user_meta`](https://chugunov.pro/api-wordpress/functions/add_user_meta/), `wpdb::update`, `wpdb::insert`, [`__`](https://chugunov.pro/api-wordpress/functions/__/), [`_x`](https://chugunov.pro/api-wordpress/functions/_x/), [`wp_slash`](https://chugunov.pro/api-wordpress/functions/wp_slash/), [`wp_unslash`](https://chugunov.pro/api-wordpress/functions/wp_unslash/), [`get_userdata`](https://chugunov.pro/api-wordpress/functions/get_userdata/), [`is_multisite`](https://chugunov.pro/api-wordpress/functions/is_multisite/), [`apply_filters`](https://chugunov.pro/api-wordpress/functions/apply_filters/), [`do_action`](https://chugunov.pro/api-wordpress/functions/do_action/), [`get_option`](https://chugunov.pro/api-wordpress/functions/get_option/), `wpdb::get_var`, `wpdb::prepare`, `WP_Error::__construct`.
Используется в: `WP_REST_Users_Controller::create_item`, [`edit_user`](https://chugunov.pro/api-wordpress/functions/edit_user/), [`wp_update_user`](https://chugunov.pro/api-wordpress/functions/wp_update_user/), [`wp_create_user`](https://chugunov.pro/api-wordpress/functions/wp_create_user/).

Оригинал в официальной документации: https://developer.wordpress.org/reference/functions/wp_insert_user/