wp_signon( array $credentials = array(), string|bool $secure_cookie = '' ): WP_User|WP_Error
Authenticates and logs a user in with ‘remember’ capability.
Contents
Description
The credentials is an array that has ‘user_login’, ‘user_password’, and ‘remember’ indices. If the credentials is not given, then the log in form will be assumed and used if set.
The various authentication cookies will be set by this function and will be set for a longer period depending on if the ‘remember’ credential is set to true.
Note: wp_signon() doesn’t handle setting the current user. This means that if the function is called before the ‘init’ hook is fired, is_user_logged_in() will evaluate as false until that point. If is_user_logged_in() is needed in conjunction with wp_signon() , wp_set_current_user() should be called explicitly.
Parameters
-
$credentials
array Optional -
User info in order to sign on.
user_login
stringUsername.user_password
stringUser password.remember
boolWhether to'remember'
the user. Increases the time that the cookie will be kept. Default false.
Default:
array()
-
$secure_cookie
string|bool Optional -
Whether to use secure cookie.
Default:
''
Return
More Information
If you don’t provide $credentials, wp_signon uses the $_POST variable (the keys being “log”, “pwd” and “rememberme”).
This function sends headers to the page. It must be run before any content is returned.
This function sets an authentication cookie. Users will not be logged in if it is not sent.
Source
File: wp-includes/user.php
.
View all references
function wp_signon( $credentials = array(), $secure_cookie = '' ) {
if ( empty( $credentials ) ) {
$credentials = array(
'user_login' => '',
'user_password' => '',
'remember' => false,
);
if ( ! empty( $_POST['log'] ) ) {
$credentials['user_login'] = wp_unslash( $_POST['log'] );
}
if ( ! empty( $_POST['pwd'] ) ) {
$credentials['user_password'] = $_POST['pwd'];
}
if ( ! empty( $_POST['rememberme'] ) ) {
$credentials['remember'] = $_POST['rememberme'];
}
}
if ( ! empty( $credentials['remember'] ) ) {
$credentials['remember'] = true;
} else {
$credentials['remember'] = false;
}
/**
* Fires before the user is authenticated.
*
* The variables passed to the callbacks are passed by reference,
* and can be modified by callback functions.
*
* @since 1.5.1
*
* @todo Decide whether to deprecate the wp_authenticate action.
*
* @param string $user_login Username (passed by reference).
* @param string $user_password User password (passed by reference).
*/
do_action_ref_array( 'wp_authenticate', array( &$credentials['user_login'], &$credentials['user_password'] ) );
if ( '' === $secure_cookie ) {
$secure_cookie = is_ssl();
}
/**
* Filters whether to use a secure sign-on cookie.
*
* @since 3.1.0
*
* @param bool $secure_cookie Whether to use a secure sign-on cookie.
* @param array $credentials {
* Array of entered sign-on data.
*
* @type string $user_login Username.
* @type string $user_password Password entered.
* @type bool $remember Whether to 'remember' the user. Increases the time
* that the cookie will be kept. Default false.
* }
*/
$secure_cookie = apply_filters( 'secure_signon_cookie', $secure_cookie, $credentials );
global $auth_secure_cookie; // XXX ugly hack to pass this to wp_authenticate_cookie().
$auth_secure_cookie = $secure_cookie;
add_filter( 'authenticate', 'wp_authenticate_cookie', 30, 3 );
$user = wp_authenticate( $credentials['user_login'], $credentials['user_password'] );
if ( is_wp_error( $user ) ) {
return $user;
}
wp_set_auth_cookie( $user->ID, $credentials['remember'], $secure_cookie );
/**
* Fires after the user has successfully logged in.
*
* @since 1.5.0
*
* @param string $user_login Username.
* @param WP_User $user WP_User object of the logged-in user.
*/
do_action( 'wp_login', $user->user_login, $user );
return $user;
}
Hooks
-
apply_filters( 'secure_signon_cookie',
bool $secure_cookie ,array $credentials ) -
Filters whether to use a secure sign-on cookie.
-
do_action_ref_array( 'wp_authenticate',
string $user_login ,string $user_password ) -
Fires before the user is authenticated.
-
do_action( 'wp_login',
string $user_login ,WP_User $user ) -
Fires after the user has successfully logged in.
Changelog
Version | Description |
---|---|
2.5.0 | Introduced. |
User Contributed Notes
You must log in before being able to contribute a note or feedback.
This function and action can be placed in functions.php of the theme.
Using the hook after_setup_theme will make it run before the headers and cookies are sent, so it can set the needed cookie for login.
If you want to cover your bases for SSL sites that need a secure cookie, I use (where
$creds
is the array of login credentials)$autologin_user = wp_signon( $creds, is_ssl() );
Top ↑
Feedback
If you’re not explicitly setting the usage of secure cookies, not passing a second argument will default to setting based on the
is_ssl
method. — By Brad Cavanaugh —I have some sites where in code I log in a visitor to a hidden account (to enable media uploads form front end form), admin bar is hidden, and access to dashboard is blocked. But I have a report where
wp_signon()
fails and my hunch is because it is on site with SSL. I am guessing I need to use the$secure_cookie
option, but I cannot find any info on how to do this.My guess is I need to set the cookie first with
wp_set_auth_cookie()
?? The option there for$secure
too is unclear.And if this is a case, do I need to test first if the host is running SSL? Will setting this cookie on an http:// site break the universe?
Top ↑
Feedback
If your website is using SSL (Secure Socket Layer), then it is recommended to set the secure flag on the authentication cookie by setting the ‘secure’ argument to true when calling
wp_set_auth_cookie()
. However, since you’re usingwp_signon()
which already sets the authentication cookie, you can pass the ‘secure’ argument directly towp_signon()
, for example:The second argument of
wp_signon()
($secure_cookie
) is used to determine whether the WordPress’ default authentication actions should be run or not. By setting it tofalse
, you are indicating that you don’t want the default authentication actions to run, but you still want the authentication cookie to be set. If you set it to true, the default authentication actions will run, but it will also make WordPress start a new session and overwrite any existing authentication cookie, effectively logging out the user. — By wpdevlol —