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.

Basic Usage of Login drivers

The Auth class works mainly with one or more login drivers and offers a set of 2 methods for all other drivers. One getting a driver instance and a second answering whether a loaded driver of that type validates. Below are first the methods for checking and getting the drivers.

check($specific = null)

Checks either all loaded Login drivers or just those specified as the parameter.

Static Yes
Parameters
Param Default Description
$specific null null to check all or one ore more driver id's (single string or array of strings)
Returns bool, whether one of the (given) drivers successfully validated the login
Example
if ( ! Auth::check())
{
	Response::redirect('login');
}

// specific driver
Auth::check('simpleauth');

// Multiple drivers
Auth::check(array('simpleauth', 'twitter'));

instance($instance = null)

Retrieves a loaded driver, when multiple drivers are set in config the first driver will also be the default.

Static Yes
Parameters
Param Default Description
$instance null null to fetch the default driver, or a driver id to get a specific one
Returns Auth_Login_Driver
Example
// Logout the default driver
Auth::instance()->logout();

// Login the SimpleAuth driver
Auth::instance('simpleauth')->login(Input::post('username'), Input::post('password'));

Driver methods

The methods below should be available on all Auth drivers in at least the way described here, but will often have specific parameters added for their implementation.

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
$user = Auth::instance()->get_user_array();

login()

Must be implemented specific to the driver to login the user.

Static No
Parameters None by default
Returns bool
Example
Auth::instance('simpleauth')->login($username, $password);

logout()

Must be implemented specific to the driver to logout the user, and work without parameters.

Static No
Parameters None
Returns void
Example
Auth::instance('simpleauth')->logout();

get_email()

Fetches the current logged in user's emailaddress.

Static No
Parameters None
Returns string
Example
$email = Auth::instance('simpleauth')->get_email();

get_screen_name()

Fetches the current logged in user's screen name.

Static No
Parameters None
Returns string
Example
$name = Auth::instance('simpleauth')->get_screen_name();

Basic Usage of Group drivers

Group drivers are for assigning users to user groups.

member($group, $specific = null)

Checks if user is a member of the given group in either all loaded Group drivers or just those specified as the 2nd parameter.

Static Yes
Parameters
Param Default Description
$group required group id
$specific null null to check all or one ore more driver id's (single string or array of strings)
Returns bool, whether one of the (given) drivers had the current user registered as a member
Example
if ( ! Auth::member(100))
{
	Response::redirect('no_admin');
}

// specific driver
Auth::member(1, 'simplegroup');

// Multiple drivers
Auth::check(0, array('simplegroup', 'genericgroup'));

group($instance = null)

Retrieves a loaded group driver, when multiple drivers are set in config the first driver will also be the default.

Static Yes
Parameters
Param Default Description
$instance null null to fetch the default driver, or a driver id to get a specific one
Returns Auth_Group_Driver
Example
Auth::group()->get_name();

Basic Usage of ACL drivers

Group drivers are for assigning users to user groups.
ACL uses input of a location and required rights on that location as input for the checking of rights, what that exactly means is up to you. There are 2 common ways in which these are implemented:

  • Location = Controller, Rights = Methods
    In this scenario you could have a Controller_Articles with methods like action_list() and action_create() which you could check using: Auth::has_access('articles.list');
  • Location = Model, Rights = specific operations
    In this scenario you could have a Model_Article and before allowing any operation within the model you first check if the user has the required CRUD rights: Auth::has_access('article.[read,update]');

These are but examples, it's up to you how you interpret and use these.

has_access($condition, $specific = null)

Checks if user is has access for the given condition in either all loaded Acl drivers or just those specified as the 2nd parameter.

Static Yes
Parameters
Param Default Description
$condition required takes a location and the required rights on the location as either a string or an array
$specific null null to check all or one ore more driver id's (single string or array of strings)
Returns bool, whether the user gets access to all given rights in the given location from the loaded (or specified) ACL drivers.
Example
// check if user is allowed to comment
if ( ! Auth::has_access('comments.create'))
{
	Response::redirect('no_admin');
}

// check if user can also update & delete comments
Auth::has_access('comments.[update,delete]');

// The same with an array instead of a string
Auth::has_access(array('comments', array('update', 'delete')));

acl($instance = null)

Retrieves a loaded ACL driver, when multiple drivers are set in config the first driver will also be the default.

Static Yes
Parameters
Param Default Description
$instance null null to fetch the default driver, or a driver id to get a specific one
Returns Auth_Acl_Driver
Example
Auth::acl();