wp_insert_user() – функция для добавления или обновления пользователя

2.0.0 wp-includes / user.php / Кодекс WordPress

В случае успеха функция возвращает ID созданного/обновлённого пользователя, в случае неудачи – объект WP_Error. Некоторые из таких ситуаций:

«Имя пользователя не может быть длиннее 60 символов.» – до описания этой функции я вообще не знал об этом ограничении!
«Нельзя создать пользователя с пустым логином.» – логично.
«Извините, это имя пользователя уже существует!» – да, такие вещи лучше проверять функцией username_exists().
«Ярлык пользователя не может быть длиннее 50 символов.» – это про nicename разговор.
«Извините, этот адрес email уже используется!» – да, проверяйте функцией email_exists().
«Неверный ID пользователя.» – в том случае, когда вы решили обновить пользователя, указали его ID, а пользователя с таким ID оказывается и не существует вовсе.
«Извините, это имя пользователя не разрешено.» – в том случае, если вы используете имена пользователя, которые запрещены хуком illegal_user_logins (пример). По умолчанию разрешено всё.
«Отметить пользователя как спамера можно только на мультисайт установке.» – это если вы решили использовать параметр spam, а у вас обычная установка, а не мультисайт!
«Недостаточно данных для создания пользователя.» – ну тут понятно, не заполнили нормально $userdata.

Пример использования

Давайте начну с примера.

$new_user_id = wp_insert_user(
	array(
		'user_login' => 'mishanew',
		'user_email' => 'misha@misha.blog',
		'user_pass' => '12345', // только вы так не делайте, прошу!
		'role' => 'administrator',
	)
);
 
if( ! is_wp_error( $new_user_id ) ) { // если не ошибка
	// потом например вы можете добавить немного метаданных
	update_user_meta( $new_user_id, 'first_name', 'Misha' );
}

Параметры

Ну что, теперь давайте разберёмся в параметрах функции.

wp_insert_user( $userdata )

$userdata

(массив|WP_User) Массив с параметрами, также можно передать уже объект существующего пользователя.

ID: (целое число) указывается только тогда, когда нужно обновить существующего пользователя. И НЕТ, мы не можем задать произвольный ID при создании!
user_pass: (строка) Пароль пользователя в виде строки. Можно сгенерировать функцей wp_generate_password()
user_login: (строка) Логин, имя пользователя. Уникальный для каждого пользователя сайта!
user_email: (строка) Email. Уникальный для каждого пользователя сайта!
user_url: (строка) Сайт пользователя.
user_nicename: (строка) Ярлык. По сути это логин пользователя, который будет использоваться в URL. Можете указать свой, если не укажете, WordPress автосгенерирует его из логина. Например если у вас в качестве логина используются емайлы, скажем misha@misha.blog, то получится mishamisha-blog.
display_name: (строка) Отображаемое имя, по умолчанию – логин.
first_name: (строка) Имя.
last_name: (строка) Фамилия.
description: (строка) Значение поля Обо мне – Биография в профиле пользователя
rich_editing: (логическое) Включить / Отключить визуальный редактор. По умолчанию true – включено.
syntax_highlighting: (логическое) Включить / Отключить подсветку синтаксиса при редактировании кода. По умолчанию true – включено.
comment_shortcuts: (логическое) Использовать ли горячие клавиши для проверки комментариев. По умолчанию false – нет. Подробнее об этом.
admin_color: (строка) Цветовая тема админки. По умолчанию – fresh (стандартная). Существуют значения light – Светлая, blue – Синяя, coffee – Кофе, ectoplasm – Эктоплазма, midnight – Полночь, ocean – Океан, sunrise – Рассвет.
use_ssl: (логическое) Установите true, чтобы обязать пользователя логиниться через SSL (https://).
user_registered: (строка) Можете указать дату регистрации в формате Y-m-d H:i:s. По умолчанию – текущая GMT дата.
show_admin_bar_front: (логическое) Показывать верхнюю панель при просмотре сайта или нет. По умолчанию true – показывать.
role: (строка) Роль пользователя. По умолчанию из настроек – get_option('default_role')
locale: (строка) Язык админки пользователя
spam: (логическое) (только Мультисайт ) Укажите true, чтобы отметить пользователя как спам.

Если вы перейдёте в Пользователи > Ваш профиль, вы увидите, что практически все перечисленные параметры представлены там в виде полей/чекбоксов.

Хуки

Фильтр-хуки pre_, например pre_username

Большинство из передаваемых в функцию параметров пользователя можно отфильтровать перед их использованием. Вот полный список:

pre_user_login
pre_user_email
pre_user_display_name
pre_user_nicename
pre_user_nickname
pre_user_url
pre_user_first_name
pre_user_last_name
pre_user_description

К примеру вы хотите добавлять перед логином пользователя последовательность из случайных букв, тогда ваш хук будет выглядеть так:

add_filter( 'pre_user_login', function( $user_login ) {
 
	return substr( str_shuffle( "abcdefghijklmnopqrstuvwxyz" ), 0, 4 ) . '_' . $user_login;
 
});

illegal_user_logins

При помощи этого хука можно задать определённые имена пользователей, которые вы бы хотели запретить для регистрации, пример:

add_filter( 'illegal_user_logins', function( $illegal_logins ) {
 
	return array( 'Loh', 'administrator', 'admin' );
 
} );

wp_pre_insert_user_data

Хук wp_pre_insert_user_data позволяет отфильтровать основные параметры пользователя, которые отправляются в таблицу wp_users, я говорю о: логин, пароль, емайл, урл, дата регистрации, ярлык, отображаемое имя.

Чтобы не напрягать правое полушарие, покажу тот же самый пример, что был тут на примере pre_user_login.

// $update – если true, то обновление, false – создание нового
// $user_id – думаю не нужно вам объяснять, в каких случаях он равен null
add_filter( 'wp_pre_insert_user_data', function( $userdata, $update, $user_id ) {
 
	$userdata[ 'user_login' ] = substr( str_shuffle( "abcdefghijklmnopqrstuvwxyz" ), 0, 4 ) . '_' . $userdata[ 'user_login' ];
	return $userdata;
 
}, 10, 3 );

insert_user_meta

Обратите внимание, что при создании пользователя функцией wp_insert_user() часть данных записывается в обычную таблицу пользователей в базе данных wp_users, а часть в мета wp_usermeta.

И хук insert_user_meta позволяет перед записью метаданных в базу данных, что-нибудь с ними провернуть. Предположим, вы хотите зафорсить пользователей всегда использовать Светлую цветовую схему. И это блин возможно с помощью хука insert_user_meta и совершенно бесплатно! 😁

// $user – объект пользователя WP_User
// $update – если true, то обновление, false – создание нового
add_filter( 'insert_user_meta', function( $meta, $user, $update ) {
 
	$meta['admin_color'] = 'light';
	return $meta;
 
} );

profile_update

Запускается тогда, когда мы обновляем существующего пользователя, то есть когда передан параметр ID в функцию.

add_action( 'profile_update', function( $user_id, $old_user_data ) {
 
	// делаем что-то
 
}, 10, 2 );

user_register

В противоположность предыдущему хуку – срабатывает когда мы именно регистрируем нового пользователя, а не обновляем существующего

add_action( 'user_register', function( $user_id ) {
 
	// делаем что-то
 
} );

make_spam_user и make_ham_user

Хуки противоположны друг другу, первый запускается, если параметр spam отмечен как true, второй – ~~если пользователь ветчина~~ во всех остальных случаях.

Срабатывают сразу после хука profile_update, только при обновлении пользователей.

add_action( 'make_spam_user', function( $user_id ) {
 
	// делаем что-либо
 
});

Миша

Впервые познакомился с WordPress в 2009 году. Организатор и спикер на конференциях WordCamp. Преподаватель в школе Нетология.

Пишите, если нужна помощь с сайтом или разработка с нуля.

Использование
Параметры
Хуки