SimpleAuth Usage

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).

The Simpleauth group driver stores its group definitions in the simpleauth configuration file. It provides the logic for checking if a user is a member of a group, and for retrieving group information, or the roles defined to to a group.

The Simpleauth acl driver is role driven, and stores its acl definitions in the simpleauth configuration file. It provides the logic for checking if a user has access to a named ACL.

Static vs Dynamic

As explained in the introduction, the Auth package provides a static interface to most of the method available, providing you only a single driver set. These methods will be defined below as "Static: Yes". All methods are also accessable via chaining on the Auth instance object, including the ones marked as static.

Class methods

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

The validate_user method validates user credentials. This method supports both email address and username as valid credential.

Static Yes
Parameters
Param Default Description
$username_or_email 
''
 Either the users username or email address
$password 
''
 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.
Example 
// validate the a username and password
if ($user = Auth::validate_user($name, $pass))
{
	// the combination of $name and $pass validated, print the users screen name
	echo $user['username'];
}

This method only validates if a given combination of username and password is correct. It does NOT log the user in!

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

The login method performs a login request. If a parameter is not given, it will attempt to retrieve it from posted data, used the form fieldnames configured in the simpleauth.php configuration file. Internally it calls the validate_user() method to validate the request before attempting a login.

Static Yes
Parameters
Param Default Description
$username_or_email 
''
 Either the users username or email address
$password 
''
 The users password
Returns boolean. returns true if the login was succesful, false otherwise.
Example 
// perform a login
if (Auth::login($name, $pass))
{
	// the user is succesfully logged in
}

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

check()

The check method checks if a logged-in user is present.

Static Yes
Parameters None
Returns boolean. returns true if a logged-in user is present, false otherwise.
Example 
// login if we're not logged-in
if ( ! Auth::check())
{
	Response::redirect('/login');
}

force_login($user_id = '')

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

Static Yes
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.
Example 
// perform a forced login for user 12121
if (Auth::force_login(12121))
{
	// the user is succesfully logged in. Any previously logged-in user will be logged out!
}

logout()

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

Static Yes
Parameters None
Returns boolean. returns true if the logout was succesful, false otherwise.
Example 
// perform a logout
Auth::logout();

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 Yes
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 or user metadata 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.
Example 
// create a new user
Auth::create_user(
	'anewuser',
	'thisismysecretpassword',
	'anewuser@example.org',
	1,
	array(
		'fullname' => 'A. New User',
	)
);

update_user($values, $username = null)

The update_user method allows you to update values in the user record, either for a named user, or for the current logged-in user.

Static Yes
Parameters
Param Default Description
$values 
array()
 Associative array with column name / value pairs for the columns or profile fields you want to update.
$username 
null
 The name of the user you want to update
Throws SimpleUserUpdateException
Returns boolean. returns true if columns were updated, or false if no columns were affected.
Example 
// update the data for the current user
Auth::update_user(
	array(
		'email'        => 'anewemail@example.org',  // set a new email address
		'password'     => 'thisismynewpassword',    // set a new password
		'old_password' => 'thisismysecretpassword', // to do so, give the current one!
		'phone'        => '+1 (555) 123-1212',	    // and add the phone number to the metadata
	)
);

This method is primary provided to allow the user to do profile updates. And as a security measure, it will not allow you to change the username, and 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 Yes
Parameters
Param Default Description
$old_password required The users current password
$new_password required The users new password
$username 
null
 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.
Example 
// change the password for the current user
Auth::change_password('mycurrentpassword','mynewpassword');

This method is provided to allow the user to change his password. And as a security measure, you have to pass the current password in "old_password".

reset_password($username)

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

Static Yes
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.
Example 
// reset the password for the current user
$new_password = Auth::reset_password('thisusername');

delete_user($username)

The delete_user method allows you to delete a user account.

Static Yes
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).
Example 
// delete the user
Auth::delete_user('thisusername');

create_login_hash()

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

Static Yes
Parameters None
Returns string, the generated login hash.
Example 
// generate a new random hash
Auth::create_login_hash();

This method is normally used when a user logs in, but you can use this as an extra security measure by rotating the hash regularly for logged-in users.

Note that login hash protection is not used when multiple logins is enabled!

get($field, $default = null)

The get method is a generic getter for user properties, either from the user record, or from the metadata.

Static Yes
Parameters
Param Default Description
$field required The name of the property you want the value of
$default 
null
 The value to return is the property is not set
Returns mixed.
Example 
// get the user creation date
$created_at = Auth::get('created_at');

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. It uses this structure because you can have multiple login drivers active, each can have a different id for the currently logged-in user.

Static Yes
Parameters None
Returns mixed. returns a numeric array in the form array([0]=>driver_id, [1]=>user_id) if a user is logged in, or false otherwise.
Example 
// get all login id information
$id_info = Auth::get_user_id();

// print driver and id info
if ($id_info)
{
	foreach ($id_info as $info)
	{
		echo 'Driver: ',$info[0],' with ID ',$info[1],'<br />';
	}
}
else
{
	echo 'Nobody is logged in!';
}

// if you only use one driver, you can also do
list($driver, $userid) = Auth::get_user_id();

// or this if you only need the userid
list(, $userid) = Auth::get_user_id();

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 Yes
Parameters None
Returns mixed. returns an array in the form array(array(driver, group_id)) if a user is logged in, or false otherwise.
Example 
// get all group id information
$id_info = Auth::get_groups();

// print driver and id info
if ($id_info)
{
	foreach ($id_info as $info)
	{
		echo 'Driver: ',$info[0],' with group ID ',$info[1],'<br />';
	}
}
else
{
	echo 'Nobody is logged in!';
}

// if you only use one driver, you can also do
list($driver, $groupid) = Auth::get_groups();

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

get_email()

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

Static Yes
Parameters None
Returns mixed. returns an email address if a user is logged in, or false if there is no user logged-in.
Example 
// get the current users email address
$email = Auth::get_email();

// note that there is a difference between false and empty:
if ($email === false)
{
	// nobody logged in
}
if (empty($email))
{
	// a user is logged in, but doesn't have an email address
}

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

get_screen_name()

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

Static Yes
Parameters None
Returns mixed. returns a string containing the name, or false if there is no user logged-in.
Example 
// get the current users screen name
$name = Auth::get_screen_name();

// name is required, so if not present it means nobody is logged in
if (empty($name))
{
	// nobody logged in
}

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

get_profile_fields($field = null, $default = null)

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

Static Yes
Parameters
Param Default Description
$field 
null
 The name of the profile field you want to get.
$default 
null
 The value you want returned if the requested profile field does not exist.
Returns mixed
Example 
// get all profile fields defined
$profile = Auth::get_profile_fields();

member($group, $user = null)

The member method allows you to check if a user is member of a given group.

Static Yes
Parameters
Param Default Description
$group required The id of the group you want to check for membership
$user 
null
 A specific user, identified by the result of get_user_id(), or null for the currently logged-in user.
Returns boolean. true if the user is member of the group, or false if not.
Example 
// Check if the current user is an administrator
if (Auth::member(100))
{
	// we are in the administrator group!
}

groups($driver = null)

The groups method allows you to fetch all defined groups, or all defined groups in a specific driver.

Static Yes
Parameters
Param Default Description
$driver 
null
 The name of the group driver you want to get groups of
Returns array. If the group driver does not exist or no groups are defined, an empty array is returned.
Example 
// Get all defined groups (for all loaded group drivers)
$groups = Auth::groups();

// Get all the groups from the default group driver
$groups = Auth::group()->groups();

// Get all the groups from a specific driver
$groups = Auth::group('Simplegroup')->groups();

You need to call this method on the Auth group drivers instance if you want groups defined by a specific driver.

If you use multiple drivers, this method only works reliably if the group id's are unique over all drivers!

roles($driver = null)

The roles method allows you to fetch all defined roles, or all defined roles in a specific driver.

Static Yes
Parameters
Param Default Description
$driver 
null
 The name of the group driver you want to get roles of
Returns array. If the acl driver does not exist or no roles are defined, an empty array is returned.
Example 
// Get all defined roles (for all loaded acl drivers)
$roles = Auth::roles();

// Get all the roles from the default acl driver
$roles = Auth::acl()->roles();

// Get all the roles from a specific driver
$roles = Auth::acl('Simpleacl')->roles();

You need to call this method on the Auth acl drivers instance if you want groups defined by a specific driver.

If you use multiple drivers, this method only works reliably if the role id's are unique over all drivers!

get_name($group = null)

The get_name method allows you to fetch the name of a specific group. If no group is given, it will return the name of the group of the current logged-in user.

Static No
Parameters
Param Default Description
$group 
null
 The id of the group you want to get the name of
Returns mixed. The name of the group, or null if a group with the given id does not exist.
Example 
// Get all the name for the group of the current logged-in user
$name = Auth::group()->get_name();

// Get the name of a specific group from a specific driver
$name = Auth::group('Simplegroup')->get_name(100);	// returns 'Administrators'

If you use multiple drivers, this method only works reliably if the group id's are unique over all drivers!

has_access($condition)

The has_access method allows you to check if the current logged-in user has access to a specific location with specific rights.

Static Yes
Parameters
Param Default Description
$condition required The access condition you want to check
Returns boolean. true if the user has access, or false if not.
Example 
// check if the user has access to read blog posts
if (Auth::has_access('blog.read'))
{
	// yes, the user has access
}

// if you have multiple login instances, use the instance to call this method.
// you can also check for multiple rights in one go
if (Auth::instance('simpleauth')->has_access('blog.[read,write,delete]'))
{
	// yes, the user has access and may read, write and delete
}

// you can also specify the rights to check as an array
if (Auth::has_access(array('blog' => array('read'), 'comments' => array('read')))
{
	// yes, the user has access to read blogs and comments
}

// if you have multiple login instances, you can also pick a specific ACL driver
if (Auth::acl('simpleacl')->has_access('blog.[read,write,delete]'))
{
	// yes, the user has access and may read, write and delete
}

guest_login()

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

Static Yes
Parameters None
Returns boolean. returns true if the guest support is enabled, or false if not.
Example 
// redirect to login if we we require a user and no guest access is enabled
if ( ! Auth::check() and ! Auth::guest_login())
{
	Response::redirect('/login');
}

remember_me($user_id = null)

The remember_me method allows you to set a remember_me cookie. If $user_id is not given, the current logged-in user is used.

Static Yes
Parameters
Param Default Description
$user_id 
null
 The id of the user to be remembered
Returns boolean. returns true if the remember me cookie was correctly set, or false if there was no user_id present, or the remember_me functionality was disabled in the configuration.
Example 
// process the login form POST, and set the remember-me cookie if needed
if (\Input::method() == 'POST')
{
	// check the credentials.
	if (\Auth::instance()->login(\Input::param('username'), \Input::param('password')))
	{
		// does the user want to be remembered?
		if (\Input::param('rememberme', false))
		{
			// create the remember-me cookie
			\Auth::remember_me();
		}
		else
		{
			// delete the remember-me cookie if present
			\Auth::dont_remember_me();
		}

		// logged in, go the homepage
		\Response::redirect('/');
	}
	else
	{
		// login failed, show an error message
		$data['username']    = \Input::param('username');
		$data['login_error'] = \Lang::get('login.failure');
	}
}

dont_remember_me()

The dont_remember_me method destroys the remember_me cookie, if present.

Static Yes
Parameters None
Example See remember_me() for an example