Documentation

Author:Ben Edmunds

Ion Auth

Ion Auth is a simple and lightweight authentication library for the CodeIgniter framework

License

Ion Auth is released under the Apache License v2.0. You can read the license here: http://www.apache.org/licenses/LICENSE-2.0

Installation

1. Download the latest version: http://github.com/benedmunds/CodeIgniter-Ion-Auth/zipball/master
2. Copy the files from this package to the correspoding folder in your application folder. For example, copy Ion_auth/config/ion_auth.php to system/application/config/ion_auth.php.

The default login is:

• Email: admin@admin.com
• Password: password

Loading Ion Auth

You load Ion Auth just link any other library:

$this->load->library('ion_auth');

You can also autoload the library.

Configuration Options

Ion Auth is extremely configurable. The following configuration options are available:

• $config['tables']['groups']
• $config['tables']['users']
• $config['tables']['meta']
• $config['site_title']
• $config['admin_email']
• $config['default_group']
• $config['admin_group']
• $config['join']
• $config['columns']
• $config['identity']
• $config['min_password_length']
• $config['max_password_length']
• $config['email_activation']
• $config['remember_users']
• $config['user_expire']
• $config['user_extend_on_login']
• $config['email_templates']
• $config['email_activate']
• $config['email_forgot_password']
• $config['email_forgot_password_complete']
• $config['salt_length']
• $config['store_salt']
• $config['message_start_delimiter']
• $config['message_end_delimiter']
• $config['error_start_delimiter']
• $config['error_end_delimiter']

Using Config File

To change configuration options simply edit the config/ion_auth.php file.

Config

Edit the ion_auth $config array as needed:

• 'tables['groups']' - The table name to use for the groups table. DEFAULT is 'groups'.
• 'tables['users']' - The table name to use for the users table. DEFAULT is 'users'.
• 'tables['meta']' - The table name to use for the meta table. DEFAULT is 'meta'.
• 'site_title' - The title of your site, used for email.
• 'admin_email' - Your administrator email address. DEFAULT is 'admin@example.com'.
• 'default_group' - Name of the default user group. DEFAULT is 'members'.
• 'admin_group' - Name of the admin group. DEFAULT is 'admin'.
• 'join' - Column to use for joining users and meta table. DEFAULT is 'user_id'.
• 'columns' - The columns in the meta table. DEFAULT is 'array('first_name', 'last_name', 'company', 'phone')'.
• 'identity' - Column to use for uniquely identifing user/logging in/etc. Usual choices are 'email' OR 'username'. You should add an index in the users table for whatever you set this option to. DEFAULT is 'email'.
• 'min_password_length' - Minimum length of passwords. DEFAULT is '8'.
• 'max_password_length' - Maximum length of passwords. DEFAULT is '20'.
• 'email_activation' - TRUE or FALSE. Sets whether to require email activation or not. DEFAULT is 'false'.
• 'remember_users' - TRUE or FALSE. Sets whether to enable 'remember me' functionality or not. DEFAULT is 'true'.
• 'user_expire' - Sets how long to remember the user for in seconds. DEFAULT is '86500'.
• 'user_extend_on_login' - TRUE or FALSE. Extend the users session expiration on login. DEFAULT is 'false'.
• 'email_templates' - Folder where the email view templates are stored. DEFAULT is 'auth/email/'.
• 'email_activate' - Filname of the email activation view template. DEFAULT is 'activate.tpl.php'.
• 'email_forgot_password' - Filname of the forgot password email view template. DEFAULT is 'forgot_password.tpl.php'.
• 'email_forgot_password_complete' - Filname of the forgot password complete email view template. DEFAULT is 'new_password.tpl.php'.
• 'salt_length' - Length of the encryption salt. DEFAULT is '10'.
• 'store_salt' - TRUE or FALSE. Store the salt in a separate database column or not. This can be useful for integrating with existing apps. DEFAULT is 'false'.
• 'message_start_delimiter' - Starting delimiter for messages. DEFAULT is '<p>'.
• 'message_end_delimiter' - Ending delimiter for messages. DEFAULT is '</p>'.
• 'error_start_delimiter' - Starting delimiter for errors. DEFAULT is '<p>'.
• 'error_end_delimiter' - Ending delimiter for errors. DEFAULT is '</p>'.

Class Function Reference

NOTE: Methods available in the model are called through the controller using PHP5 magic. You should never use ion_auth_model->method() in your applications.

login()

Logs the user into the system.

Parameters

1. 'Username' - string REQUIRED. Usually username or email but depends on your config.
2. 'Password' - string REQUIRED.
3. 'Remember' - boolean OPTIONAL. TRUE sets the user to be remembered if enabled in the config

Return

• boolean. TRUE if the user was successfully logged in FALSE if the user was not logged in.

Usage

		$identity = 'ben.edmunds@gmail.com';
		$password = '12345678';
		$remember = TRUE; // remember the user
		$this->ion_auth->login($identity, $password, $remember);
	

logout()

Logs the user out of the system.

Usage

		$this->ion_auth->logout();
	

register()

Register (create) a new user.

Parameters

1. 'Username' - string REQUIRED.
2. 'Password' - string REQUIRED.
3. 'Email' - string REQUIRED.
4. 'Additional Data' - multidimensional array REQUIRED.
5. 'Group Name' - string OPTIONAL. If not passed the default group name set in the config will be used.

Return

• boolean. TRUE if the user was successfully created FALSE if the user was not created.

Usage

		$username = 'ben.edmunds@gmail.com';
		$password = '12345678';
		$email = 'benedmunds';
		$additional_data = array(
								'first_name' => 'Ben',
								'last_name' => 'Edmunds',
								);
		$group_name = 'users';
		$this->ion_auth->register($username, $password, $email, $additional_data, $group_name)
	

update_user()

Update a user.

Parameters

1. 'Id' - integer REQUIRED.
2. 'Data' - multidimensional array REQUIRED.

Return

• boolean. TRUE if the user was successfully updated FALSE if the user was not updated.

Usage

		$id = 12;
		$data = array(
					'first_name' => 'Ben',
					'last_name' => 'Edmunds',
					'password' => '123456789',
					 );
		$this->ion_auth->update_user($id, $data)
	

delete_user()

Delete a user.

Parameters

1. 'Id' - integer REQUIRED.

Return

• boolean. TRUE if the user was successfully deleted FALSE if the user was not deleted.

Usage

		$id = 12;
		$this->ion_auth->delete_user($id)
	

forgotten_password()

Resets a users password by emailing the user a reset code.

Parameters

1. 'Email' - string REQUIRED.

Return

• boolean. TRUE if the users password was successfully reset FALSE if the users password was not reset.

Usage

		//Working code for this example is in the example Auth controller in the github repo
		function forgot_password()
		{
			$this->form_validation->set_rules('email', 'Email Address', 'required');
			if ($this->form_validation->run() == false) {
				//setup the input
				$this->data['email'] = array('name'    => 'email',
											 'id'      => 'email',
											);
				//set any errors and display the form
				$this->data['message'] = (validation_errors()) ? validation_errors() : $this->session->flashdata('message');
				$this->load->view('auth/forgot_password', $this->data);
			}
			else {
				//run the forgotten password method to email an activation code to the user
				$forgotten = $this->ion_auth->forgotten_password($this->input->post('email'));

				if ($forgotten) { //if there were no errors
					$this->session->set_flashdata('message', $this->ion_auth->messages());
					redirect("auth/login", 'refresh'); //we should display a confirmation page here instead of the login page
				}
				else {
					$this->session->set_flashdata('message', $this->ion_auth->errors());
					redirect("auth/forgot_password", 'refresh');
				}
			}
		}
	

forgotten_password_complete()

Final step of resetting a users password. The user comes to this page from their email.

Parameters

1. 'Code' - string REQUIRED.

Return

• string. The users new password.

Usage

		//Working code for this example is in the example Auth controller in the github repo
		public function reset_password($code)
		{
			$reset = $this->ion_auth->forgotten_password_complete($code);

			if ($reset) {  //if the reset worked then send them to the login page
				$this->session->set_flashdata('message', $this->ion_auth->messages());
				redirect("auth/login", 'refresh');
			}
			else { //if the reset didnt work then send them back to the forgot password page
				$this->session->set_flashdata('message', $this->ion_auth->errors());
				redirect("auth/forgot_password", 'refresh');
			}
		}
	

logged_in()

Check to see if a user is logged in.

Return

• boolean. TRUE if the user is logged in FALSE if the user is not logged in.

Usage

		if (!$this->ion_auth->logged_in())
		{
			redirect('auth/login');
		}
	

is_admin()

Check to see if the currently logged in user is an admin.

Return

• boolean. TRUE if the user is an admin FALSE if the user is not an admin.

Usage

		if (!$this->ion_auth->is_admin())
		{
			$this->session->set_flashdata('message', 'You must be an admin to view this page');
			redirect('welcome/index');
		}
	

is_group()

Check to see if the currently logged in user is in the passed in group.

Parameters

1. 'Group Name' - string or array of stringsREQUIRED.

Return

• boolean. TRUE if the user is in the group FALSE if the user is not in the group.

Usage

		$group = 'gangstas';
		if (!$this->ion_auth->is_group($group))
		{
			$this->session->set_flashdata('message', 'You must be a gangsta to view this page');
			redirect('welcome/index');
		}
	

username_check()

Check to see if the username is already registered.

Parameters

1. 'Username' - string REQUIRED.

Return

• boolean. TRUE if the user is registered FALSE if the user is not registered.

Usage

		//This is a lame example but it works.  Usually you would use this method with form_validation.
		$username = $this->input->post('username');
		$password = $this->input->post('password');
		$email = $this->input->post('email');
		$additional_data = array(
								'first_name' => $this->input->post('first_name'),
								'last_name' => $this->input->post('last_name'),
								);
		if (!$this->ion_auth->username_check($username))
		{
			$group_name = 'users';
			$this->ion_auth->register($username, $password, $email, $additional_data, $group_name)
		}
	

email_check()

Check to see if the email is already registered.

Parameters

1. 'Email' - string REQUIRED.

Return

• boolean. TRUE if the user is registered FALSE if the user is not registered.

Usage

		//This is a lame example but it works.  Usually you would use this method with form_validation.
		$username = $this->input->post('username');
		$password = $this->input->post('password');
		$email = $this->input->post('email');
		$additional_data = array(
								'first_name' => $this->input->post('first_name'),
								'last_name' => $this->input->post('last_name'),
								);
		if (!$this->ion_auth->email_check($email))
		{
			$group_name = 'users';
			$this->ion_auth->register($username, $password, $email, $additional_data, $group_name)
		}
	

identity_check()

Check to see if the identity is already registered.

Parameters

1. 'Identity' - string REQUIRED.

Return

• boolean. TRUE if the user is registered FALSE if the user is not registered.

Usage

		//This is a lame example but it works.
		$user = $this->ion_auth->get_user();
		$data = array(
					'identity' => $this->input->post('identity'),
					'first_name' => $this->input->post('first_name'),
					'last_name' => $this->input->post('last_name'),
					 );
		if ($data['identity'] === $user->username || $data['identity'] === $user->email || $this->ion_auth->identity_check($data['identity']) === FALSE)
		{
			$this->ion_auth->update_user($user->id, $data)
		}
	

get_user()

Get a user.

Parameters

1. 'Id' - integer OPTIONAL. If a user id is not passed the id of the currently logged in user will be used.

Return

• 			stdClass Object (
  				[id] => 1
  				[group_id] => 1
  				[ip_address] => 127.0.0.1
  				[username] => administrator
  				[password] => 59beecdf7fc966e2f17fd8f65a4a9aeb09d4a3d4
  				[salt] => 9462e8eee0
  				[email] => admin@admin.com
  				[activation_code] => 19e181f2ccc2a7ea58a2c0aa2b69f4355e636ef4
  				[forgotten_password_code] => 81dce1d0bc2c10fbdec7a87f1ff299ed7e4c9e4a
  				[remember_code] => 9d029802e28cd9c768e8e62277c0df49ec65c48c
  				[created_on] => 1268889823
  				[last_login] => 1279464628
  				[active] => 0
  				[group] => admin
  				[group_description] => Administrator
  				[first_name] => Admin
  				[last_name] => Account
  				[company] => Some Corporation
  				[phone] => (123)456-7890
  			)
  			

Usage

		$user = $this->ion_auth->get_user();
		echo $user->email;
	

get_user_array()

Get a user.

Parameters

1. 'Id' - integer OPTIONAL. If a user id is not passed the id of the currently logged in user will be used.

Return

• Array
  			(
  				[id] => 1
  				[group_id] => 1
  				[ip_address] => 127.0.0.1
  				[username] => administrator
  				[password] => 59beecdf7fc966e2f17fd8f65a4a9aeb09d4a3d4
  				[salt] => 9462e8eee0
  				[email] => admin@admin.com
  				[activation_code] => 19e181f2ccc2a7ea58a2c0aa2b69f4355e636ef4
  				[forgotten_password_code] => 81dce1d0bc2c10fbdec7a87f1ff299ed7e4c9e4a
  				[remember_code] => 9d029802e28cd9c768e8e62277c0df49ec65c48c
  				[created_on] => 1268889823
  				[last_login] => 1279464628
  				[active] => 0
  				[group] => admin
  				[group_description] => Administrator
  				[first_name] => Admin
  				[last_name] => Account
  				[company] => Some Corporation
  				[phone] => (123)456-7890
  			)
  			

Usage

		$user = $this->ion_auth->get_user_array();
		echo $user['email'];
	

get_user_by_email()

Get a user by their email address.

Parameters

1. 'Email' - string REQUIRED.

Return

• 			stdClass Object (
  				[id] => 1
  				[group_id] => 1
  				[ip_address] => 127.0.0.1
  				[username] => administrator
  				[password] => 59beecdf7fc966e2f17fd8f65a4a9aeb09d4a3d4
  				[salt] => 9462e8eee0
  				[email] => admin@admin.com
  				[activation_code] => 19e181f2ccc2a7ea58a2c0aa2b69f4355e636ef4
  				[forgotten_password_code] => 81dce1d0bc2c10fbdec7a87f1ff299ed7e4c9e4a
  				[remember_code] => 9d029802e28cd9c768e8e62277c0df49ec65c48c
  				[created_on] => 1268889823
  				[last_login] => 1279464628
  				[active] => 0
  				[group] => admin
  				[group_description] => Administrator
  				[first_name] => Admin
  				[last_name] => Account
  				[company] => Some Corporation
  				[phone] => (123)456-7890
  			)
  			

Usage

		$email = 'ben.edmunds@gmail.com';
		$user = $this->ion_auth->get_user_by_email($email);
		echo $user->first_name;
	

get_users()

Get the users.

Parameters

1. 'Group Name' - string OPTIONAL. If a group is not supplied all users will be returned.

Return

• array of objects

Usage

		$admin_group = 'admin';
		$admin_users = $this->ion_auth->get_users($admin_group);
	

get_users_array()

Get the users.

Parameters

1. 'Group Name' - string OPTIONAL. If a group is not supplied all users will be returned.

Return

• multidimensional array

Usage

		$admin_group = 'admin';
		$admin_users = $this->ion_auth->get_users($admin_group);
	

get_newest_users()

Get the newest users.

Parameters

1. 'Limit' - integer OPTIONAL. Default value is 10.

Return

• array of objects

Usage

		$admin_group = 'admin';
		$newest_admin_users = $this->ion_auth->get_newest_users($admin_group);
	

get_newest_users_array()

Get the newest users.

Parameters

1. 'Limit' - integer OPTIONAL. Default value is 10.

Return

• multidimensional array

Usage

		$admin_group = 'admin';
		$newest_admin_users = $this->ion_auth->get_newest_users_array($admin_group);
	

get_active_users()

Get the active users.

Parameters

1. 'Group name' - string OPTIONAL. If a group is not supplied all users will be returned.

Return

• array of objects

Usage

		$admin_group = 'admin';
		$active_admin_users = $this->ion_auth->get_active_users($admin_group);
	

get_active_users_array()

Get the active users.

Parameters

1. 'Group name' - string OPTIONAL. If a group is not supplied all users will be returned.

Return

• multidimensional array

Usage

		$admin_group = 'admin';
		$active_admin_users = $this->ion_auth->get_active_users_array($admin_group);
	

get_inactive_users()

Get the inactive users.

Parameters

1. 'Group name' - string OPTIONAL. If a group is not supplied all users will be returned.

Return

• array of objects

Usage

		$admin_group = 'admin';
		$inactive_admin_users = $this->ion_auth->get_inactive_users($admin_group);
	

get_inactive_users_array()

Get the inactive users.

Parameters

1. 'Group name' - string OPTIONAL. If a group is not supplied all users will be returned.

Return

• multidimensional array

Usage

		$admin_group = 'admin';
		$inactive_admin_users = $this->ion_auth->get_inactive_users_array($admin_group);
	

get_groups()

Get the groups.

Return

• array of objects

Usage

		$groups = $this->ion_auth->get_groups();
	

get_group()

Get a group.

Parameters

1. 'Id' - integer REQUIRED.

Return

• object

Usage

		$group_id = 2;
		$group = $this->ion_auth->get_group($group_id);
	

get_group_by_name()

Get a group.

Parameters

1. 'Name' - string REQUIRED.

Return

• object

Usage

		$group_name = 'users';
		$group = $this->ion_auth->get_group_by_name($group_name);
	

messages()

Get messages.

Return

• string

Usage

		$id = 12;
		$data = array(
					'first_name' => 'Ben',
					'last_name' => 'Edmunds',
					 );
		if ($this->ion_auth->update_user($id, $data))
		{
			$messages = $this->ion_auth->messages();
			echo $messages;
		}
		else
		{
			$errors = $this->ion_auth->errors();
			echo $errors;
		}
	

set_message_delimiters()

Set the message delimiters.

Parameters

1. 'Start Delimiter' - string REQUIRED.
2. 'End Delimiter' - string REQUIRED.

Usage

		$id = 12;
		$data = array(
					'first_name' => 'Ben',
					'last_name' => 'Edmunds',
					 );
		if ($this->ion_auth->update_user($id, $data))
		{
			$this->ion_auth->set_message_delimiters('<p><strong>','</strong></p>');
			$messages = $this->ion_auth->messages();
			echo $messages;
		}
		else
		{
			$this->ion_auth->set_error_delimiters('<p><strong>','</strong></p>');
			$errors = $this->ion_auth->errors();
			echo $errors;
		}
	

errors()

Get the errors.

Return

• string

Usage

		$id = 12;
		$data = array(
					'first_name' => 'Ben',
					'last_name' => 'Edmunds',
					 );
		if ($this->ion_auth->update_user($id, $data))
		{
			$messages = $this->ion_auth->messages();
			echo $messages;
		}
		else
		{
			$errors = $this->ion_auth->errors();
			echo $errors;
		}
	

set_error_delimiters()

Set the error delimiters.

Parameters

1. 'Start Delimiter' - string REQUIRED.
2. 'End Delimiter' - string REQUIRED.

Usage

		$id = 12;
		$data = array(
					'first_name' => 'Ben',
					'last_name' => 'Edmunds',
					 );
		if ($this->ion_auth->update_user($id, $data))
		{
			$this->ion_auth->set_message_delimiters('<p><strong>','</strong></p>');
			$messages = $this->ion_auth->messages();
			echo $messages;
		}
		else
		{
			$this->ion_auth->set_error_delimiters('<p><strong>','</strong></p>');
			$errors = $this->ion_auth->errors();
			echo $errors;
		}
	

extra_where()

Allows extra where field to be used for user fetching/unique checking etc. Basically this allows users to be unique based on one other thing than the identifier which is helpful for sites using multiple domains on a single database.

Parameters

1. string or array REQUIRED.

String Usage

		$this->ion_auth->extra_where("meta.domain = 'yourmother.com'");
	

Array Usage

		$where = array('meta.domain', 'yourmother.com');
		$this->ion_auth->extra_where($where);
	

extra_set()

Allows extra set field to be used for user registration. This is helpful for sites using multiple domains on a single database.

Parameters

1. string or array REQUIRED.

String Usage

		$this->ion_auth->extra_set("meta.domain = 'yourmother.com'");
	

Array Usage

		$where = array('meta.domain', 'yourmother.com');
		$this->ion_auth->extra_set($where);
	

Top of Page

CodeIgniter  ·  Copyright © 2010 Ben Edmunds  ·  Ellislab, Inc.