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();
|