Функция wp_signon() используется для авторизации пользователя в WordPress по переданным логину (или email), паролю и параметру «remember» (запомнить). Она возвращает объект пользователя WP_User при успешной авторизации или объект ошибки WP_Error, если авторизация не удалась.
wp_signon( array $credentials = array(), string|bool $secure_cookie = '' ): WP_User|WP_Error
Параметры функции
- $credentials (массив) — массив данных для авторизации пользователя:
user_login— логин пользователя (или email).user_password— пароль пользователя.remember— запомнить пользователя, если установлено вtrue.
$_POST. Например:
array(
'user_login' => $_POST['log'],
'user_password' => $_POST['pwd'],
'remember' => $_POST['rememberme'],
)
- $secure_cookie (строка или логический) — использовать ли защищенные куки. По умолчанию функция автоматически определяет, использовать ли куки для защищенного соединения, основываясь на наличии SSL-сертификата на сайте. Можно явно указать:
true— использовать защищенные куки (SECURE_AUTH_COOKIE).false— использовать обычные куки (AUTH_COOKIE).
Возвращаемые значения
WP_User— объект пользователя при успешной авторизации.WP_Error— объект ошибки в случае неудачной авторизации.
Особенности
- Установка куки: Функция отправляет заголовки и устанавливает куки, что означает, что ее нужно вызывать до вывода какого-либо контента на странице (HTML, текста).
- Проверка авторизации:
wp_signon()не устанавливает текущего пользователя. Это значит, что если функция вызвана до событияinit, проверкаis_user_logged_in()вернётfalse. Для установки текущего пользователя вручную используется функцияwp_set_current_user().
Основные хуки
Функция взаимодействует с рядом хуков:
wp_authenticate— вызывается перед проверкой данных пользователя.secure_signon_cookie— используется для изменения поведения защищенной куки.wp_login— вызывается при успешной авторизации пользователя.
Пример авторизации пользователя по логину и паролю:
$creds = array();
$creds['user_login'] = 'Leonid';
$creds['user_password'] = 'password';
$creds['remember'] = true;
$user = wp_signon( $creds, false );
if ( is_wp_error($user) ) {
echo $user->get_error_message();
}
В этом примере происходит попытка авторизовать пользователя с логином Leonid и паролем password, с включенной опцией «Запомнить меня».
Пример авторизации через данные из $_POST:
$user = wp_signon();
if ( is_wp_error($user) ) {
echo $user->get_error_message();
}В данном случае, если переданы данные формы с ключами log, pwd и rememberme, функция автоматически попытается авторизовать пользователя.
Авторизация с проверкой SSL и использованием защищенных куков:
$creds = array(
'user_login' => 'example',
'user_password' => 'plaintextpw',
'remember' => true
);
$user = wp_signon( $creds, is_ssl() ); // Если SSL используется, передаем true
if ( is_wp_error($user) ) {
echo $user->get_error_message();
}
В данном примере проверяется, используется ли SSL на сайте, и, если да, функция устанавливает защищенные куки.
Автоматическая авторизация через хук
Функцию можно использовать для автоматической авторизации пользователя при загрузке темы, вызвав её до отправки заголовков страницы:
function wpdocs_custom_login() {
$creds = array(
'user_login' => 'example',
'user_password' => 'plaintextpw',
'remember' => true
);
$user = wp_signon( $creds, false );
if ( is_wp_error($user) ) {
echo $user->get_error_message();
}
}
// Хук для выполнения функции перед отправкой заголовков
add_action( 'after_setup_theme', 'wpdocs_custom_login' );
Этот код авторизует пользователя автоматически при загрузке темы, используя учетные данные, переданные в массиве $creds.
Заключение
Функция wp_signon() — это мощный инструмент для авторизации пользователей в WordPress. Она гибкая и позволяет использовать как защищенные, так и обычные куки, а также автоматически авторизовать пользователей на основе данных формы.