SimpleAuth Login

As said in the introduction of the Auth package, an authentication system comes with three different drivers, each dealing with a part of the system.

The SimpleAuth login driver provides the logic for creating, updating, deleting and validating user accounts stored in a local database table, for getting information about those accounts, for generating or resetting passwords, and for login and logout operations (creating a user session).

Class methods

validate_user($username_or_email = '', $password = '')

The validate_user method validates a login request. This method supports both email address and username as valid credential.

Static No
Parameters
Param Default Description
$username_or_email required Either the users username, or email address
$password required The users password
Returns mixed. false if the user didn't pass validation, or an array with the users information if the credentials were valid.

login($username_or_email = '', $password = '')

The login method performs a login request. It calls the validate_user() to validate the request before attempting a login.

Static No
Parameters
Param Default Description
$username_or_email required Either the users username, or email address
$password required The users password
Returns boolean. returns true if the login was succesful, false otherwise.

After a succesful login, the 'username' and the current 'login_hash' will be available as a session variable.

force_login($user_ids = '')

The force_login method performs a forced login request. You can use this for an automated login, when you know. the user_id, but you don't know the password. This can be used for example for a "remember me" feature.

Static No
Parameters
Param Default Description
$user_id required The id of the user you want to login
Returns boolean. returns true if the login was succesful, false otherwise.

logout()

The logout method logs out the current logged-in user.

Static No
Parameters None
Returns boolean. returns true if the logout was succesful, false otherwise.

If you have enabled guest user support, the guest user will be setup after a succesful logout.

create_user($username, $password, $email, $group = 1, Array $profile_fields = array())

The create_user allows method you to create a new user record in the users table.

Static No
Parameters
Param Default Description
$username required The name of the user you want to create
$password required The password you want to assign to the user
$email required The email address of the user you want to create
$group 1 The group you want to assign this user to. By default, the user is assigned to group 1.
$profile_fields 
array()
Any additional profile fields you want to assign to this user
Throws SimpleUserUpdateException
Returns mixed. returns the id of the user record created, or false if the creation failed.

update_user($values, $username = null)

The update_user method allows you to update values in the user record.

Static No
Parameters
Param Default Description
$values 
array()
Associative array with column name / value pairs for the columns or profile fields you want to update.
$username required The name of the user you want to create
Throws SimpleUserUpdateException
Returns boolean. returns true if columns were updated, or false if no columns were affected.

Note that you can not use this method to change the username. And as a security measure, if you want to change the password, you have to pass the current password in $values as "old_password".

change_password($old_password, $new_password, $username = null)

The change_password method allows you to change a users password.

Static No
Parameters
Param Default Description
$old_password required The users current password
$new_password required The users new password
$username required The name of the user of whom you want to change the password
Throws SimpleUserUpdateException
Returns boolean. returns true if the password was changed, or false if the old password was incorrect.

reset_password($username)

The reset_password method allows you to assign a new random password to a user.

Static No
Parameters
Param Default Description
$username required The name of the user for whom you want to reset the password
Throws SimpleUserUpdateException
Returns string, the generated random password.

delete_user($username)

The delete_user method allows you to delete a user account.

Static No
Parameters
Param Default Description
$username required The name of the user account you want to delete
Throws SimpleUserUpdateException
Returns boolean. returns true if the user account was deleted, or false if it failed (because the username did not exist).

create_login_hash()

The create_login_hash method generates a new login hash for the currently logged-in user.

Static No
Parameters None
Returns string, the generated login hash.

get_user_id()

The get_user_id method returns an array structure containing the drivers id value, and the id of the currently logged-in user.

Static No
Parameters None
Returns mixed. returns an array in the form array(driver_id, user_id) if a user is logged in, or false otherwise.

If guest user support is enabled, you will never get false returned, because the method will return the user id of the guest user.

get_groups()

The get_groups method returns the user groups assigned to the currently logged-in user.

Static No
Parameters None
Returns mixed. returns an array in the form array(array('SimpleGroup', group_id)) if a user is logged in, or false otherwise.

get_email()

The get_email method returns the email address assigned to the currently logged-in user.

Static No
Parameters None
Returns mixed. returns an email address if a user is logged in, or false if no email address is defined for the current user, or there is no user logged-in.

get_screen_name()

The get_screen_name method returns the screen- or display name of the currently logged-in user.

Static No
Parameters None
Returns mixed. returns a string containing the name, or false if there is no user logged-in.

get_profile_fields()

The get_profile_fields method returns the stored profile fields for the logged-in user.

Static No
Parameters None
Returns array.

guest_login()

The guest_login allows you to check if guest access is enabled.

Static No
Parameters None
Returns boolean. returns true if the guest support is enabled, or false if not.