Jump to content

Developer Documentation

Creating standard login handlers

Basic skeleton

Here is a basic skeleton for a standard login handler: 

namespace IPS\Login;

class _Example extends LoginAbstract
{
	/**
	 * @brief	Authentication types
	 */
	public $authTypes = \IPS\Login::AUTH_TYPE_USERNAME;
		
	/**
	 * Authenticate
	 *
	 * @param	array	$values	Values from from
	 * @return	\IPS\Member
	 * @throws	\IPS\Login\Exception
	 */
	public function authenticate( $values )
	{
		/* Init */
		$username	= $values['auth'];	// Depending on the value of $authTypes this may be an email instead
		$password	= $values['password'];
		
		/* Find member */
		try
		{
			$member = \IPS\Member::load( $username );
		}
		catch ( \OutOfRangeException $e )
		{
			throw new \IPS\Login\Exception( \IPS\Member::loggedIn()->language()->addToStack('login_err_no_account', FALSE, array( 'sprintf' => array( \IPS\Member::loggedIn()->language()->addToStack('username') ) ) ), \IPS\Login\Exception::NO_ACCOUNT );
		}
		
		/* Check password */
		if ( $password !== 'the-correct-password' ) // Implement correct check here
		{
			throw new \IPS\Login\Exception( 'login_err_bad_password', \IPS\Login\Exception::BAD_PASSWORD, NULL, $member );
		}
		
		/* Return member */
		return $member;
	}

    /**
     * ACP Settings Form
     *
     * @param    string    $url    URL to redirect user to after successful submission
     * @return    array    List of settings to save - settings will be stored to core_login_handlers.login_settings DB field
     * @code
         return array( 'savekey'    => new \IPS\Helpers\Form\[Type]( ... ), ... );
     * @endcode
     */
    public function acpForm()
    {
        return array();
    }
    
     /**
     * Can a member change their email/password with this login handler?
     *
     * @param    string        $type    'username' or 'email' or 'password'
     * @param    \IPS\Member    $member    The member
     * @return    bool
     */
    public function canChange( $type, \IPS\Member $member )
    {
        return TRUE;
    }
}

 

Auth types

The $authTypes property defines whether your login handler expects a username or email address or either. It is a bitwise field, and the acceptable values are: 

// Username
public $authTypes = \IPS\Login::AUTH_TYPE_USERNAME;

// Email address
public $authTypes = \IPS\Login::AUTH_TYPE_EMAIL;

// Username or email address
public $authTypes = \IPS\Login::AUTH_TYPE_USERNAME + \IPS\Login::AUTH_TYPE_EMAIL;

If you want to base this off a setting, or do any other setup for your login handler, you can implement an init() method in your class, like so: 

public function init()
{
	if( $SOME_SETTING )
	{
		$this->authTypes = \IPS\Login::AUTH_TYPE_USERNAME;
	}
}

 

The authenticate() method

The authenticate() function receives the values from the form (the username/email address and password) and can either return an \IPS\Member object if the login was successful, or throw an \IPS\Login\Exception object if it wasn't. If throwing an \IPS\Login\Exception object, the message is displayed to the user, and the code should be one of the following values: 

// Something went wrong with the login handler which wasn't the user's fault.
throw new \IPS\Login\Exception( "Login Failed.", \IPS\Login\Exception::INTERNAL_ERROR );

// The password the user provided was incorrect.
throw new \IPS\Login\Exception( "Login Failed.", \IPS\Login\Exception::BAD_PASSWORD );

// The username or email address the user provided did not match any account.
throw new \IPS\Login\Exception( "Login Failed.", \IPS\Login\Exception::NO_ACCOUNT );

// The username or email address matches an existing account but which has not been used by this login handler 
// before and an account merge is required (see below)
throw new \IPS\Login\Exception( "Login Failed.", \IPS\Login\Exception::MERGE_SOCIAL_ACCOUNT );

If your login handler needs to create an account for a user, and it is appropriate to do that, you can do that in the authenticate() method. For example: 

public function authenticate( $values )
{
    /* Init */
    $username	= $values['auth'];	// Depending on the value of $authTypes this may be an email instead
    $password	= $values['password'];

    /* Find member */
    try
    {
        $member = \IPS\Member::load( $username );
    }
    catch ( \OutOfRangeException $e )
    {
        $member = new \IPS\Member;
        $member->member_group_id = \IPS\Settings::i()->member_group;
        $member->name = $username;
        $member->email = '...'; // You'll need to get the email from your login handler's database
        // You may want to set additional properties here
        $member->save();
    }

    /* Check password */
    if ( $password !== 'the-correct-password' ) // Implement correct check here
    {
        throw new \IPS\Login\Exception( 'login_err_bad_password', \IPS\Login\Exception::BAD_PASSWORD, NULL, $member );
    }

    /* Return member */
    return $member;
}

The acpForm() and canChange() methods are discussed below.

  Report Document


Invision Community © 2024 IPS, Inc.
×
×
  • Create New...