FuelPHP, a PHP 5.3 Framework Documentation

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

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

''

''

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

''

''

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

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.

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

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

array()

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

array()

null

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

null

// reset the password for the current user
Auth::change_password('thisismynewpassword','thisismysecretpassword');

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.

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

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

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

null

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

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

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

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

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

null

null

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

null

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

null

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

null

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

null

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

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

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

null

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