Auth package

The Auth package provides a standardized interface for authentication in Fuel. This allows our users to write their own drivers and easily integrate a new driver to work with old code by keeping the basic methods consistent.

Auth_Login_Driver

This driver is the base class for all Auth login drivers. It is defined as an abstract class which contains all methods generic to all login drivers, and abstract method definitions for all methods any login driver MUST implement.

Driver configuration

A login driver can load additional drivers that it depends on. Generally, these are Group drivers. But your implementation could introduce and use custom driver types as well. To do so, add this structure to your driver class: 

// autoload the Simplegroup group driver when loading this login driver
// this also defines the additional user record fields this driver has a getter for
	protected $config = array(
		'drivers' => array('group' => array('Simplegroup')),
		'additional_fields' => array('profile_fields'),
	);

Static interface

For ease of use, the Auth package provides a static interface on the public methods of the Login driver. for this reason, the login base driver also defines the methods member() and has_access(), which provide static access to these methods in the group and ACL driver.

Using the static interface, you can do

// returns 'simpleauth'
$id = Auth::get_id();

instead of

// returns 'simpleauth'
$id = Auth::instance()->get_id();

This only works if "verify_multiple_logins" is set to false in the Auth config, as you can not map a static interface to multiple active login drivers!

Generic methods

Generic methods are defined in the login base driver, and are available to all Auth login drivers through extension. These methods provide functions to create and retrieve instances, to set and get configuration values, as well as generic method for password hashing and access to the ACL and Group drivers.

The methods defined in the classes but not documented here are used internally, and should not be called directly.

get_id()

Returns the drivers unique id. This can be used to identify the driver, or to select a specific driver instance.

Static No
Parameters None
Returns The drivers id string.
Example 
// returns 'simpleauth'
$id = Auth::instance('simpleauth')->get_id();

set_config($key, $value)

Sets a driver configuration value.

Static No
Parameters
Param Default Description
$key required Configuration key name
$value required Value for this configuration key
Returns void
Example 
// set a config value
Auth::instance()->set_config('key', 'value');

get_config($key, $default = null)

Gets a driver configuration value.

Static No
Parameters
Param Default Description
$key required Configuration key name
$default null Default value to be returned if the requested key does not exist
Returns mixed
Example 
// get a config value, return false if it doesn't exist
$key = Auth::instance()->get_config('key', false);

guest_login()

Returns if the driver supports guest logins (a non-authenticated guest user).

Static No
Parameters None.
Returns boolean
Example 
// check if the default instance supports guests
if (Auth::instance()->guest_login())
{
	// this driver supports guest logins!
}

By default, this method returns 'false'. If your login driver supports guest logins, overload this method in your driver class.

get_user_array(Array $additional_fields = array())

Returns an array describing the current logged in user, always includes at least a screenname and an emailaddress. Additional fields can be configured in the driver config or requested through the $additional_fields array, but they must have a get_user_fieldname() method within the driver to be gettable.

Static No
Parameters
Param Default Description
$additional_fields array() an array with fieldnames to fetch
Returns array
Example 
// call the method on the default instance
$user = Auth::instance()->get_user_array();

// call the method on a specific instance
$user = Auth::instance('simpleauth')->get_user_array();

// static call (if "verify_multiple_logins" is set to false)
$user = Auth::get_user_array();

You can define the 'additional_fields' in the driver configuration array to have them included by default when you call this method.

hash_password($password)

Returns a base64 encoded hash of the given password. This method uses the very secure pbkdf2 hashing algorithm.

Static No
Parameters
Param Default Description
$password required The password to hash
Returns string
Example 
// hash a users password
$password = Auth::instance()->hash_password($password);

Abstract methods

Every login driver you develop MUST provide all of these methods, and the MUST return the values documented here.

perform_check()

Internal class method which checks if there is a valid session for the current user. It is up to you how your driver will determine this.

Static No
Parameters None
Returns boolean, true if there is a valid user session, false if there isn't.

This method is called by Auth::check(), it should not be called directly by the application.

validate_user()

The validate_user method validates a login request. It is up to you how your driver will do this.

Static No
Parameters None
Returns mixed. it should return false if the user didn't pass validation. Any value that evaluates to true is considered to be valid.

Applications calling this method should not make assumptions about the return value if it isn't false!

login()

The login method performs a login request. It should call the validate_user() to validate the request. It is up to you how your driver will do this.

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

If your driver has guest user support, it must setup the guest before returning false.

logout()

The logout method logs out the current logged-in user. It is up to you how your driver will do this.

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

If your driver has guest user support, it must setup the guest as current user after a succesful logout.

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 your driver has guest user support, it must return the array with the (dummy) user_id of your guest, and not false!

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(driver_id, group_id), array(driver_id, group_id), etc) if a user is logged in, or false otherwise.

If your driver has guest user support, it must return the array your guest user groups, and not false!

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.

If your driver has guest user support, don't forget to return false if the guest does not have an email address defined!

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.

If your driver has guest user support, it must return the guests display name, and not false!