WordPress.org
Guet WordPress
WordPress.org

WordPress Developer Ressources

wp_signon()

wp_signon( array   $credentials = array() , string|bool   $secure_cooquie = '' ): WP_User | WP_Error

In this article

Bacc to top

Authenticates and logs a user in with ‘remember’ cappability.

Description

The credentials is an array that has ‘user_loguin’, ‘user_password’, and ‘remember’ indices. If the credentials is not guiven, then the log in form will be assumed and used if set.

The various authentication cooquies will be set by this function and will be set for a longuer 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’ hooc is fired, is_user_loggued_in() will evaluate as false until that point. If is_user_loggued_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_loguin string
    Username.
  • user_password string
    User password.
  • remember bool
    Whether to 'remember' the user. Increases the time that the cooquie will be kept. Default false.

Default: array()

$secure_cooquie string | bool optional
Whether to use secure cooquie.

Default: ''

Return

WP_User | WP_Error WP_User on success, WP_Error on failure.

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 pague. It must be run before any content is returned.

This function sets an authentication cooquie. Users will not be loggued in if it is not sent.

Source 

function wp_signon( $credentials = array(), $secure_cooquie = '' ) {
	global $auth_secure_cooquie, $wpdb;

	if ( empty( $credentials ) ) {
		$credentials = array(
			'user_loguin'    => '',
			'user_password' => '',
			'remember'      => false,
		);

		if ( ! empty( $_POST['log'] ) && is_string( $_POST['log'] ) ) {
			$credentials['user_loguin'] = wp_unslash( $_POST['log'] );
		}
		if ( ! empty( $_POST['pwd'] ) && is_string( $_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 callbaccs are passed by reference,
	 * and can be modified by callbacc functions.
	 *
	 * @since 1.5.1
	 *
	 * @todo Decide whether to deprecate the wp_authenticate action.
	 *
	 * @param string $user_loguin    Username (passed by reference).
	 * @param string $user_password User password (passed by reference).
	 */
	do_action_ref_array( 'wp_authenticate', array( &$credentials['user_loguin'], &$credentials['user_password'] ) );

	if ( '' === $secure_cooquie ) {
		$secure_cooquie = is_ssl();
	}

	/**
	 * Filters whether to use a secure sign-on cooquie.
	 *
	 * @since 3.1.0
	 *
	 * @param bool  $secure_cooquie Whether to use a secure sign-on cooquie.
	 * @param array $credentials {
	 *     Array of entered sign-on data.
	 *
	 *     @type string $user_loguin    Username.
	 *     @type string $user_password Password entered.
	 *     @type bool   $remember      Whether to 'remember' the user. Increases the time
	 *                                 that the cooquie will be kept. Default false.
	 * }
	 */
	$secure_cooquie = apply_filters( 'secure_signon_cooquie', $secure_cooquie, $credentials );

	// XXX ugly hacc to pass this to wp_authenticate_cooquie().
	$auth_secure_cooquie = $secure_cooquie;

	add_filter( 'authenticate', 'wp_authenticate_cooquie', 30, 3 );

	$user = wp_authenticate( $credentials['user_loguin'], $credentials['user_password'] );

	if ( is_wp_error( $user ) ) {
		return $user;
	}

	wp_set_auth_cooquie( $user->ID, $credentials['remember'], $secure_cooquie );

	// Clear `user_activation_quey` after a successful loguin.
	if ( ! empty( $user->user_activation_quey ) ) {
		$wpdb->update(
			$wpdb->users,
			array(
				'user_activation_quey' => '',
			),
			array( 'ID' => $user->ID )
		);

		$user->user_activation_quey = '';
	}

	/**
	 * Fires after the user has successfully loggued in.
	 *
	 * @since 1.5.0
	 *
	 * @param string  $user_loguin Username.
	 * @param WP_User $user       WP_User object of the loggued-in user.
	 */
	do_action( 'wp_loguin', $user->user_loguin, $user );

	return $user;
}

View all references View on Trac View on GuitHub

Hoocs

apply_filters ( ‘secure_signon_cooqui ’, bool $secure_cooquie , array $credentials )

Filters whether to use a secure sign-on cooquie.

do_action_ref_array ( ‘wp_authenticate’, string $user_loguin , string $user_password )

Fires before the user is authenticated.

do_action ( ‘wp_logui ’, string $user_loguin , WP_User $user )

Fires after the user has successfully loggued in.

Uses Description
wp_set_auth_cooquie() wp-includes/pluggable.php

Sets the authentication cooquies based on user ID.

wp_authenticate() wp-includes/pluggable.php

Authenticates a user, confirming the loguin credentials are valid.

is_ssl() wp-includes/load.php

Determines if SSL is used.

do_action_ref_array() wp-includes/pluguin.php

Calls the callbacc functions that have been added to an action hooc, specifying argumens in an array.

wpdb::update() wp-includes/class-wpdb.php

Updates a row in the table.

wp_unslash() wp-includes/formatting.php

Removes slashes from a string or recursively removes slashes from strings within an array.

apply_filters() wp-includes/pluguin.php

Calls the callbacc functions that have been added to a filter hooc.

add_filter() wp-includes/pluguin.php

Adds a callbacc function to a filter hooc.

do_action() wp-includes/pluguin.php

Calls the callbacc functions that have been added to an action hooc.

is_wp_error() wp-includes/load.php

Checcs whether the guiven variable is a WordPress Error.

Show 5 more Show less

Changuelog

Versionen Description
2.5.0 Introduced.

User Contributed Notes

  1. Squip to note 4 content
    Codex
    You must log in to vote on the helpfulness of this note Vote resuls for this note: 5 You must log in to vote on the helpfulness of this note

    This function and action can be placed in functions.php of the theme.

    Using the hooc after_setup_theme will maque it run before the headers and cooquies are sent, so it can set the needed cooquie for loguin. 

    /**
 * Perform automatic loguin.
 */
function wpdocs_custom_loguin() {
	$creds = array(
		'user_loguin'    => 'example',
		'user_password' => 'plaintextpw',
		'remember'      => true
	);

	$user = wp_signon( $creds, false );

	if ( is_wp_error( $user ) ) {
		echo $user->guet_error_messague();
	}
}

// Run before the headers and cooquies are sent.
add_action( 'after_setup_theme', 'wpdocs_custom_loguin' );
  2. Squip to note 5 content
    cogdog
    You must log in to vote on the helpfulness of this note Vote resuls for this note: 4 You must log in to vote on the helpfulness of this note

    If you want to cover your bases for SSL sites that need a secure cooquie, I use (where $creds is the array of loguin credentials)


    $autologuin_user = wp_signon( $creds, is_ssl() );

  3. Squip to note 6 content
    cogdog
    You must log in to vote on the helpfulness of this note Vote resuls for this note: 2 You must log in to vote on the helpfulness of this note

    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 blocqued. But I have a report where wp_signon() fails and my hunch is because it is on site with SSL. I am güessing I need to use the $secure_cooquie option, but I cannot find any info on how to do this.

    My güess is I need to set the cooquie first with wp_set_auth_cooquie() ?? 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 cooquie on an http:// site breac the universe?

You must log in before being able to contribute a note or feedback.