Usage Instructions
The Authentication Library is the easiest Authentication library to use for CodeIgniter. You do not need to write any code, period.
Configurable items
The Authentication Library comes with a few configurable items located in config/Auth.php. The first is an array of all the user groups and the group ID's of the groups.
$config['auth_groups'] = array( 'admin' => '1', 'editor' => '2', 'user' => '100' );
The second is the default place to redirect users to on a successful login. The Authentication Library will fall back on this if there wasn't a value set using it's parameter.
$config['auth_login'] = 'admin/';
The next configurable item, as of 1.0.2, determines whether or not The Authentication Library should remember users by default. This should be a boolean, TRUE/FALSE.
$config['auth_remember'] = TRUE;
The next 3 configurable items are the directory for your view files, admin controller files and models. The lines are below.
$config['auth_controllers_root'] = 'admin/'; $config['auth_models_root'] = ''; $config['auth_views_root'] = 'auth/';
Finally you can set the name of your user table and groups tables. The lines are below.
$config['auth_user_table'] = 'users'; $config['auth_group_table'] = 'groups';
The Application Controller
Normally when using CodeIgniter, your Controllers will usually look like this.
<?php
class Example extends Controller
{
function Example()
{
parent::Controller();
}
}
/* End of file: example.php */
/* Location: application/controllers/example.php */
However, when you need to use The Authentication Library, you should extend the Application controller instead of Controller. The Application controller is in the file MY_Controller.php in libraries/. Your controller will now look like this.
<?php
class Example extends Application
{
function Example()
{
parent::Application();
}
}
/* End of file: example.php */
/* Location: application/controllers/example.php */
This has been done to use the Form Validation library available from CodeIgniter 1.7.0 and above, which only runs callbacks in Controllers. To keep within the simplicity of The Authentication Library, I needed to create a new controller.
The Application Controller also has a number of other functions which are there to save you time and money. This means you do not need to call the login, logout and register functions directly, although if you do wish to in other areas of your application you can call upon these functions as showed below.
Login
The login function calls upon the login function of The Authentication Library so you don't have to. If you navigate to http://yourdomain.ext/index.php/admin/login you will see the login form. If you wish to display the login form somewhere else on your website, you can do so by using the following function.
$this->auth->login();
The login function accepts one parameter, this is the URI string where you want the user to be redirected to after a successful login. You may want to override the function in the application controller for the login, in which case you can simply add the following to your controller.
function login()
{
$this->auth->login('user/dashboard');
// user/dashboard is a made up URI string
}
Logout
There is a logout function in the Application class. This allows you to logout by destroying all session and cookie data. You can access this by going to http://yourdomain.ext/index.php/admin/logout. You will not need to change the behaviour of this, but if you wish to have it in another controller too, you can use the following function.
$this->auth->logout();
The logout function does not accept any parameters.
Register
The register function is also self contained, and can be accessed via http://yourdomain.ext/index.php/admin/register. If you wish to have this in aother controller, you can do so by adding this.
$this->auth->register();
The register function does not accept any parameters.
Restrict access to controllers
Use the function below to restrict access to a function.
$this->auth->restrict('user_level', TRUE);
This works directly with the config file, so you will need to change the $config['auth_groups'] if you have more than the 3 default groups. You should pass the name of the user group to the first parameter, not the user id. The function works in heirachy; for example, if you restrict access to 'users' groups above the user group will also have access to that function. If left blank the function will restrict access to only people who are logged in. However, if you pass a boolean value TRUE to the second parameter, you can restrict access to just the user group provided.
If you look inside the admin controller (controllers/admin.php), you will see a number of dummy functions that restrict access to every user group. These serve as an example to show you how you would go about using the restrict function in a real application.
The Authentication Library Helper
The Authentication Library comes with a helper which is used to make your life easier when coding with the library.
Printing a username
To print a users name, you simply use the following line of code.
echo username();
Test if a user is logged in
Instead of $this->auth->logged_in(); you can simply use the following code block to test if a user is logged in.
if(logged_in() === TRUE)
{
echo("You are logged in.");
}
else
{
echo("You must be logged in.");
}
Check if a user belongs to a certain group
For things like dynamic navigation, it is imperative to find out what group a user is in. This is made possible using the following function.
if(user_group('admin') === TRUE)
{
echo("You are an admin");
}
else
{
echo("You are not an admin.");
}
Simply pass the name of the group to the function and let the function do the rest!
Print the user table name
When performing operations on the user table, you will need to reference the correct name. But if you ever change this you need to update all of your references to the table name. With a simple function, you can use the table name you have set in your config file.
echo user_table();
Print the group table name
As above, there is also a function to display the group table name as specified in the config file.
echo group_table();
Loading views and models.
You are able to easily build the path to any view or model by using the two helper values, $this->views and $this->models. You would use these as shown below.
$this->load->view($this->views . "dashboard.php"); $this->load->model($this->models."usermodel", 'users');