Setting User Account Data | User Guide | flexi auth | A User Authentication Library for CodeIgniter

Help with Function Parameters

Show / Hide Help

Name: The name of the function parameter (argument).

Data Type: The data type that is expected by the parameter.

bool : Requires a boolean value of 'TRUE' or 'FALSE'.
string : Requires a textual value.
int : Requires a numeric value. It does not matter whether the value is an integer, float, decimal etc.
array : Requires an array.

Required: Defines whether the parameter requires a value to be submitted.

Default: Defines the default parameter value that is used if no other value is submitted.

insert_user()

Inserts user account and profile data, returning the users new id.

Library and Requirements

Available via the standard library.

Function Parameters

insert_user(email, username, password, user_data, group_id, activate) Help

Name	Data Type	Required	Default	Description
email	string	Yes	FALSE	Defines the user email address.
username	string	Yes/No	FALSE	Defines the users username. If the username table column is defined as an identity column via the 'identity_cols' setting in the config. file, then an argument value is required.
password	string	Yes	FALSE	Defines the users password (As plain text).
user_data	array	No	FALSE	Defines any custom user data that is to be inserted to the database. This data would typically be user profile data as such as the users name, address etc.
group_id	int	No	FALSE	Defines the user group that the user should be assigned to.
activate	bool	No	FALSE	Defines whether the users account should be immediately activated.

How it Works

The function initially checks that the users email address and username (If defined) are unique.
If the username if not unique, and the config. file is defined to auto increment usernames, then the function will start a loop, suffixing a number to the username until a unique username is found.

The function thens check whether a group id was defined via the functions arguments, if no value is found, then the default group id defined via the config. file will be used.

The users password is then hashed using the PHPASS library with any additional static and database salt that may have been defined via the config. file.

The function will then proceed to automatically set other data required by the library, as such as the users ip address an account activatation token, and whether to auto suspend the users account on insert.

A database transaction is then started so that if any SQL errors occur during the transaction, all database changes are auto rolled back to their original values.

The compiled user data is then inserted to the database. Any defined custom user data is then looped through and inserted to the relevant custom user tables.

Once the data is inserted, the function will check whether to auto activate the users account. The account can be defined to be activated for a short time period, or indefinitely via the config. file.
If the account is not auto activated, an email with an activation token is emailed to the user.

Finally, the function returns the newly inserted users id.

Notes

To insert custom user data via the function, an associative array must be passed to the 'user_data' argument.

The function relates each array key with the name of each table column, the assoicated array value contains the value that is to be inserted into the table.

For the function to be able to match the array keys with each table column, the name of each table column must be defined via the config. file.

// Example of defining custom columns within the libraries primary user account table.
$config['database']['user_acc']['custom_columns'] = array(
	'custom_col_1', 'custom_col_2', 'custom_col_3'
);

// Example of defining custom columns within a custom user table.
$config['database']['custom']['custom_user_table']['custom_columns'] = array(
	'custom_col_1', 'custom_col_2', 'custom_col_3'
);

Return Values

Failure:FALSE | An error message will be set.

Success:int | id of the inserted record | A status message will be set.

Example

// Example : Insert a new user with two custom user columns.
$email = 'user@email.com';
$username = 'custom_username';
$password = 'password123';
$user_data = array(
	'custom_col_1' => 'custom_value_1',
	'custom_col_2' => 'custom_value_2'
);
$group_id = 1;
$activate = FALSE;

$this->flexi_auth->insert_user($email, $username, $password, $user_data, $group_id, $activate);

update_user()

Updates the main user account table and any related custom user tables with the submitted data.

Library and Requirements

Available via the standard library.

Function Parameters

update_user(user_id, user_data) Help

Name	Data Type	Required	Default	Description
user_id	int	Yes	FALSE	Defines the id of the user to be updated.
user_data	array	Yes	FALSE	Defines the user data that is to be updated.

How it Works

The function first runs an SQL SELECT query to get the identity of the users account being updated.

The submitted user data array is then checked to determine whether the users identity is being updated.
If it is, then the function checks whether the new identity is unique and available.

A database transaction is then started so that if any SQL errors occur during the transaction, all database changes are auto rolled back to their original values.

The function then loops through each row within the user data array adding the data to an SQL update statement.
If a new password is included in the array, the function will automatically hash the password.

If the users identity is in the array, the function will update the browsers session data once the update is successful.

Notes

To update user data via the function, an associative array must be passed to the 'user_data' argument.

The function relates each array key with the name of each table column, the assoicated array value contains the value that is to be inserted into the table.

For the function to be able to match the array keys with each table column, the name of each table column must be defined via the config. file.

// Example of defining custom columns within the libraries user account table.
$config['database']['user_acc']['custom_columns'] = array(
	'custom_col_1', 'custom_col_2', 'custom_col_3'
);

// Example of defining custom columns within a custom user table.
$config['database']['custom']['custom_user_table']['custom_columns'] = array(
	'custom_col_1', 'custom_col_2', 'custom_col_3'
);

Return Values

Failure:FALSE | An error message will be set.

Success:TRUE | A status message will be set.

Examples

// Example : Updating the users email, password and two custom columns.
$user_id = 101;
$user_data = array(
	'email' => 'user@email.com',
	'password' => 'password123',
	'custom_col_1' => 'custom_value_1',
	'custom_col_2' => 'custom_value_2'
);

$this->flexi_auth->update_user($user_id, $user_data);

delete_user()

Deletes a user account and all related custom user tables from the database.

Library and Requirements

Available via the standard library.

Function Parameters

delete_user(user_id) Help

Name	Data Type	Required	Default	Description
user_id	int	Yes	FALSE	Defines the user id of the user account to be deleted.

How it Works

A database transaction is started so that if any SQL errors occur during the transaction, all database changes are auto rolled back to their original values.

All user session data is then deleted from the database, followed by the users account data, all related custom user data and any related user privilege data.

Return Values

Failure:FALSE | An error message will be set.

Success:TRUE | A status message will be set.

Example

$user_id = 101;

$this->flexi_auth->delete_user($user_id);

insert_custom_user_data()

Inserts data into a custom user table and returns the table name and row id of each record inserted.

Library and Requirements

Available via the standard library.

Function Parameters

insert_custom_user_data(user_id, custom_data) Help

Name	Data Type	Required	Default	Description
user_id	int	Yes	FALSE	Defines the user id of the user to insert data to.
custom_data	array	Yes	FALSE	Defines the custom user data that is to be inserted to the database. This data would typically be user profile data as such as the users name, address etc.

How it Works

The function loops through all the custom user tables that are defined via the config. file.
Within the loop, the function matches the names of the table columns with the array keys of the custom user data array.

Once the custom user data has been matched to the related custom user table, the data is inserted into each table.

The name and id of each table and row is then added to the returned array data.

Notes

To update custom user data via the function, an associative array must be passed to the 'custom_data' argument.

The function relates each array key with the name of each table column, the assoicated array value contains the value that is to be inserted into the table.

For the function to be able to match the array keys with each table column, the name of each table column must be defined via the config. file.

// Example of defining custom columns within a custom user table.
$config['database']['custom']['custom_user_table']['custom_columns'] = array(
	'custom_col_1', 'custom_col_2', 'custom_col_3'
);

Return Values

Failure:FALSE | An error message will be set.

Success:Array | A status message will be set.

Example

$custom_data = array(
	'custom_col_1' => 'custom_value_1',
	'custom_col_2' => 'custom_value_2'
);

$this->flexi_auth->insert_custom_user_data($custom_data);

update_custom_user_data()

Updates a custom user table with any submitted data.

Library and Requirements

Available via the standard library.

Function Parameters

update_custom_user_data(table, row_id, custom_data) Help

Name	Data Type	Required	Default	Description
table	string	No	FALSE	Defines the name of the table to update data to. If no specific table is defined, the function will loop through all custom tables defined via the config. file.
row_id	int	No	FALSE	Defines the table row id of the table to update data to. If no specific row id is defined, the function will attempt to find the primary or foreign key value defined within the custom user data.
custom_data	array	Yes	FALSE	Defines the custom user data that is to be updated. This data would typically be user profile data as such as the users name, address etc.

How it Works

If a specific table and row id have been specified, the function will simply loop through the custom user data can create an SQL update statement.

If no table is specified, the function will loop through each custom user table defined via the config. file.
Within each loop, the function will attempt to match the custom user data values with the primary or foreign key of each table define via the config. file.
If the tables primary or foreign key column is found within the custom user data, it will be used for the SQL WHERE statement.

The function then loops through the custom data and tries to match it with each custom table, when data is matched, it is added to an SQL update statement, and the data is removed from the custom data array.

Once the loop has finish the function checks whether all the custom data has been assigned to an SQL update statement.
If any custom data remains unassigned, the function returns FALSE to prevent updating some custom data, and not others.
If all custom data has been assigned to an SQL update statement, then each update statement is run.

Notes

If defining which row to update via a primary/foreign key value within the custom data array, then it is important to ensure all custom table columns are named uniquely.
This means no other custom user table should have an identically named column, otherwise the wrong table column could be updated.

Typically, if only updating data within one table, you should pass the 'table' and 'row_id' arguments to the function.

To update custom user data via the function, an associative array must be passed to the 'custom_data' argument.

The function relates each array key with the name of each table column, the assoicated array value contains the value that is to be inserted into the table.

For the function to be able to match the array keys with each table column, the name of each table column must be defined via the config. file.

// Example of defining custom columns within a custom user table.
$config['database']['custom']['custom_user_table']['custom_columns'] = array(
	'custom_col_1', 'custom_col_2', 'custom_col_3'
);

Return Values

Failure:FALSE | An error message will be set.

Success:TRUE | A status message will be set.

Examples

// Example #1 : Defining a table and row id to update with custom user data.
$table = 'custom_table';
$row_id = '101';
$custom_data = array(
	'custom_col_1' => 'custom_value_1',
	'custom_col_2' => 'custom_value_2'
);

$this->flexi_auth->update_custom_user_data($table, $row_id, $custom_data);

// Example #2 : Defining the table and row id to update within the custom user data array.
$custom_data = array(
	'custom_tbl_1_primary_key' => '101',
	'custom_tbl_1_col_1' => 'custom_value_1a',
	'custom_tbl_1_col_2' => 'custom_value_2a',
	'custom_tbl_2_primary_key' => '201',
	'custom_tbl_2_col_1' => 'custom_value_1b'
);

$this->flexi_auth->update_custom_user_data(FALSE, FALSE, $custom_data);

delete_custom_user_data()

Deletes a data row from a custom user table.

Library and Requirements

Available via the standard library.

Function Parameters

delete_custom_user_data(table, row_id) Help

Name	Data Type	Required	Default	Description
table	string	Yes	FALSE	Defines the name of the table to delete data from.
row_id	int	Yes	FALSE	Defines the table row id of the table to delete data from.

How it Works

The function loops through the custom tables defined via the config. file.
When a table is matched, an SQL delete statement is run that matches the tables primary key against the 'row_id'.

Return Values

Failure:FALSE | An error message will be set.

Success:TRUE | A status message will be set.

Example

$table = 'custom_table';
$row_id = 101;

$this->flexi_auth->delete_custom_user_data($table, $row_id);

activate_user()

Activates a users account allowing them to login to their account.

Library and Requirements

Available via the lite and standard libraries standard library.

Function Parameters

activate_user(user_id, activation_token, verify_token) Help

Name	Data Type	Required	Default	Description
user_id	int	Yes	FALSE	Defines the id of the user account to be activated.
activation_token	string	No	FALSE	Defines the token to be validated in order for the account to be activated. User accounts can be activated without passing a token if the 'verify_token' argument is set as FALSE.
verify_token	bool	No	TRUE	Defines whether the account can only be activated if a valid activation token is passed.

How it Works

If the function is defined to verify an activation token, an SQL SELECT query is run to find a user with a matching user id and activation token.

Provided the token is validated, an SQL UPDATE statement is run to remove the existing activation token and to set the account as active.

Return Values

Failure:FALSE | An error message will be set.

Success:TRUE | A status message will be set.

Examples

// Example #1 : Activate a users account using a token.
$user_id = 101;
$activation_token = '9e89d44df40a7387ba4921f5f18bb8dd8ebfdb80';
$verify_token = TRUE;

$this->flexi_auth->activate_user($user_id, $activation_token, $verify_token);

// Example #2 : Activate a users account without using a token.
$user_id = '101';

$this->flexi_auth->activate_user($user_id);

deactivate_user()

Deactivates a users account, preventing them from logging in.

Library and Requirements

Available via the lite and standard libraries standard library.

Function Parameters

deactivate_user(user_id) Help

Name	Data Type	Required	Default	Description
user_id	int	Yes	FALSE	Defines the id of the user account to be deactivated.

How it Works

The function generates an activation token that will be required in order to re-activate the account.

An SQL UPDATE statement is then run deactivating the account and setting the re-activation token.

Return Values

Failure:FALSE | An error message will be set.

Success:TRUE | A status message will be set.

Example

$user_id = 101;

$this->flexi_auth->deactivate_user($user_id);

delete_unactivated_users()

Delete users that have not activated their account within a defined time period.

Library and Requirements

Available via the standard library.

Function Parameters

delete_unactivated_users(inactive_days, sql_where) Help

Name	Data Type	Required	Default	Description
inactive_days	int	Yes	28	Defines the number of days that inactive accounts must be acivated within to be exempt from being deleted.
sql_where	string \| array	No	FALSE	Set the SQL WHERE statement used to filter the database records to return. Read the defining SQL documentation for further information.

How it Works

The function runs an SQL SELECT query returning all unactivated functions that were registered outside of the defined time period.

All returned records are then looped through and deleted.

Return Values

Failure:FALSE | An error message will be set.

Success:TRUE | A status message will be set.

Examples

// Example #1 : Delete all unactivated user accounts older than 14 days.
$inactive_days = 14;

$this->flexi_auth->delete_unactivated_users($inactive_days);

// Example #2 : Delete all unactivated user accounts older than 14 days with an additional SQL WHERE clause.
$inactive_days = 14;

// Read the defining SQL documentation for further information on setting SQL statements.
$sql_where = array(...);

$this->flexi_auth->delete_unactivated_users($inactive_days, $sql_where);

change_password()

Validates a submitted 'current' password against the database, if valid, the database is updated with the users 'new' password.

Library and Requirements

Available via the standard library.

Function Parameters

change_password(identity, current_password, new_password) Help

Name	Data Type	Required	Default	Description
identity	string	Yes	FALSE	Defines the primary identity of the user whose password is to be updated. The primary identity is either the users email address or username, which is defined via the 'primary_identity_col' setting in the config. file.
current_password	string	Yes	FALSE	Defines the users current unhashed password.
new_password	string	Yes	FALSE	Defines the users new unhashed password.

How it Works

The function first validates that the submitted current password matches the current database records.

The function then performs and SQL SELECT query to get the users id and database password salt (If set) that will be used when hashing the new password.

Then all database login sessions related to the users id are deleted, forcing any browsers logged in via a 'Remember me' cookie to login the next visit.

Finally, the users new password is hashed using the PHPASS library and is saved to the user account table.

Notes

The current and new passwords should be passed to the function in plain text, the function then performs the required hashing to secure the password.

Return Values

Failure:FALSE | An error message will be set.

Success:TRUE | A status message will be set.

Example

$identity = 'user@email.com';
$current_password = 'password';
$new_password = 'password123';

$this->flexi_auth->change_password($identity, $current_password, $new_password);

forgotten_password()

Sends the user an email containing a link to verify the user has requested to change their forgotten password.

Library and Requirements

Available via the standard library.

Function Parameters

forgotten_password(identifier) Help

Name	Data Type	Required	Default	Description
identifier	string	Yes	FALSE	The email or username of the user requesting to reset their forgotten password.

How it Works

The function creates a random token that will be used to validate the reset of the users password.

If the config. file defines that forgotten password token should expire after a set time period, then a time limit (Defined via the config. file) is set.

The token and time limit (If set) are then saved to the database.

The function then runs an SQL SELECT query to get the users id, email and the new password token.
Using this data, an email is then sent to the user which contains a link to reset the users password.

Return Values

Failure:FALSE | An error message will be set.

Success:TRUE | A status message will be set.

Example

$identifier = 'user@email.com';

$this->flexi_auth->forgotten_password($identifier);

validate_forgotten_password()

Validates a forgotten password token that is typically passed via a link from an email sent by the 'forgotten_password()' function.

Library and Requirements

Available via the standard library.

Function Parameters

validate_forgotten_password(user_id, token) Help

Name	Data Type	Required	Default	Description
user_id	int	Yes	FALSE	Defines the id of the user reseting their password.
token	string	Yes	FALSE	Defines the token to be validated in order for the password to be reset.

How it Works

The function runs an SQL SELECT query to check whether the defined user and token exist within the user account table.

Return Values

Failure:FALSE

Success:TRUE

Example

$user_id = 101;
$token = '11f4ba606abadd56810768b5dcb5b758cb974e3a';

$this->flexi_auth->validate_forgotten_password($user_id, $token);

forgotten_password_complete()

This function is similar to the 'validate_forgotten_password()' function. However, if validated the function also updates the database with a new password, then if defined, an email will be sent to the user containing the new password.

Library and Requirements

Available via the standard library.

Function Parameters

forgotten_password_complete(user_id, token, new_password, send_email) Help

Name	Data Type	Required	Default	Description
user_id	int	Yes	FALSE	Defines the id of the user reseting their password.
token	string	Yes	FALSE	Defines the token to be validated in order for the password to be reset.
new_password	string	No	FALSE	Defines the new password to be set. If no password is defined, a new random password will be generated.
send_email	bool	No	FALSE	Defines whether the new password should be emailed to the user.

How it Works

The function runs an SQL SELECT query to check whether the defined user and token exist within the user account table.

Provided the token is valid, the function then runs another SQL SELECT query to get the users primary identity, email and database password salt (If set).

If a new password has been defined, the function will update the users password. If no new password is set, then a randomly generated password is set.

If defined, the function then emails the new password to the user.

Notes

The new passwords should be passed to the function in plain text, the function then performs the required hashing to secure the password.

Return Values

Failure:FALSE | An error message will be set.

Success:string | The new password | A status message will be set.

Example

$user_id = 101;
$token = '11f4ba606abadd56810768b5dcb5b758cb974e3a';
$new_password = 'password123';
$send_email = 'user@email.com';

$this->flexi_auth->forgotten_password_complete($user_id, $forgot_password_token, $new_password , $send_email);

update_email_via_verification()

Sends the user a verification email to their new email address, the user must then click a link within the email to update their accounts email address.

The function serves two purposes. Firstly it validates that the user has spelt their new email address correctly.
Secondly, it validates that the email address is owned by the user and is not fraudulent.

Library and Requirements

Available via the standard library.

Function Parameters

update_email_via_verification(user_id, new_email) Help

Name	Data Type	Required	Default	Description
user_id	int	Yes	FALSE	Defines the id of the user to be updated.
new_email	string	Yes	FALSE	Defines the users new email address.

How it Works

The function generates a random email verification token that will be required to validate the new email address.

The function then runs an SQL UPDATE statement to update the users account table with the verification token and the new email address.
However, rather than replacing the users current email address, the new address is saved to another column incase the user never validates their new email address.

The function then sends the user an email with a link containing the email verification token.

Return Values

Failure:FALSE | An error message will be set.

Success:TRUE | A status message will be set.

Example

$user_id = 101;
$new_email = 'user@email.com';

$this->flexi_auth->update_email_via_verification($user_id, $new_email);

verify_updated_email()

Verifies a submitted email verification token and updates the users account with the new email address.

Library and Requirements

Available via the standard library.

Function Parameters

verify_updated_email(user_id, update_email_token) Help

Name	Data Type	Required	Default	Description
user_id	int	Yes	FALSE	Defines the id of the user to be updated.
update_email_token	string	Yes	FALSE	Defines the token to be validated in order for the email address to be updated.

How it Works

The function runs an SQL SELECT query to find a user with a email user id an email verification token.

Provided a user is matched, the function then updates the users email address and removes users email verification data.

If the users primary identity column is email, then users session data will be updated with the new email address.

Return Values

Failure:FALSE | An error message will be set.

Success:TRUE | A status message will be set.

Example

$user_id = 101;
$update_email_token = '5600433cb5defbd2c83e0877d2713ef0c54473da';

$this->flexi_auth->verify_updated_email($user_id, $update_email_token);

flexi auth

flexi cart

User Guide | Setting User Account Data

Set User Account Data

User CRUD Functions

Custom User Data CRUD Functions

User Activation Functions

Password Management Functions

Email Management Functions

Help with Function Parameters

insert_user()

Library and Requirements

Function Parameters

How it Works

Notes

Return Values

Example

update_user()

Library and Requirements

Function Parameters

How it Works

Notes

Return Values

Examples

delete_user()

Library and Requirements

Function Parameters

How it Works

Return Values

Example

insert_custom_user_data()

Library and Requirements

Function Parameters

How it Works

Notes

Return Values

Example

update_custom_user_data()

Library and Requirements

Function Parameters

How it Works

Notes

Return Values

Examples

delete_custom_user_data()

Library and Requirements

Function Parameters

How it Works

Return Values

Example

activate_user()

Library and Requirements

Function Parameters

How it Works

Return Values

Examples

deactivate_user()

Library and Requirements

Function Parameters

How it Works

Return Values

Example

delete_unactivated_users()

Library and Requirements

Function Parameters

How it Works

Return Values

Examples

change_password()

Library and Requirements

Function Parameters

How it Works

Notes

Return Values

Example

forgotten_password()

Library and Requirements

Function Parameters

How it Works

Return Values