Main functions
This is the function list you can use in DX Auth library.
login($login, $password, $remember = TRUE)
Login user. If login succeed, returning TRUE, else FALSE.
$login is username or email address or both depend on setting in dx_auth config file.
$password is user password.
$remember is remember user next time they open the website (remember me feature).
If function returning FALSE you can use get_auth_error() function to return error string.
logout()
Logout user.
register($username, $password,$email)
Register new user. If register succeed, return new user record, else return FALSE.
If DX_email_activation value in dx_auth config file is TRUE then it will email activation, and requires user to activate the account.
If DX_email_activation is FALSE and DX_email_account_details value in dx_auth config file is TRUE then it will email user account details.
This function will automatically set new registered user role_id to 1, so you need to make sure record in roles table which have id = 1, it's name field is 'normal user' or something similar.
forgot_password($login)
Sending an email with a key to reset their password. If succeed return TRUE else return FALSE.
$login is username or email.
Since password is encrypted in one way in one way, it's not possible to retreive back password. That's why we need to reset it.
If function returning FALSE you can use get_auth_error() function to return error string.
reset_password($username, $key = '')
Reset password based on username and key. Usually combined with forgot_password() function. If succeed return TRUE else return FALSE.
activate($username, $key = '')
Activate user based on username and key. It's used to activate user account after registration if DX_email_verification is set to TRUE in dx_auth config file.
change_password($old_pass, $new_pass)
Change password of current logged in user. Make sure you check if user already logged in before calling this function. If succeed return TRUE else return FALSE.
If function returning FALSE you can use get_auth_error() function to return error string.
cancel_account($password)
Delete current logged in user from database. Make sure you check if user already logged in before calling this function. If succeed return TRUE else return FALSE.
If function returning FALSE you can use get_auth_error() function to return error string.
get_user_id()
Return user id, only if user already logged in.
get_username()
Return username, only if user already logged in.
get_role_id()
Return user role id, only if user already logged in.
get_role_name()
Return user role name, only if user already logged in.
is_admin()
Check if user is admin, only if user already logged in.
If user role id is the same value with role_id field which have 'admin' string (case insensitive) in name field in roles table, function will return TRUE.
is_role($roles = array(), $use_role_name = TRUE, $check_parent = TRUE)
Check if user has $roles privilege.
If $use_role_name = TRUE then $roles is role name such as 'admin', 'editor', 'etc',
else $roles is role_id such as 0, 1, 2.
If $check_parent is TRUE means if roles not found in user role, it will check if user role parent has that roles.
You can pass an array or a string in $roles parameter.
For example:
if ($this->dx_auth->is_role('admin'))
{
// Do something
}
if ($this->dx_auth->is_role(array('admin', 'moderator'))
{
// Do something
}
// Using an Role ID as $roles parameter
if ($this->dx_auth->is_role('1', FALSE))
{
// Do something
}
if ($this->dx_auth->is_role(array('1', '2'), FALSE))
{
// Do something
}
is_logged_in()
Check if user already logged in.
is_banned()
Check if user is a banned user.
You should only call this function after you call login() function. So if login() function returning FALSE, you can check if user is banned or not using this function.
get_ban_reason()
Get ban reason of a banned user.
You should only call this function after you call login() function. So if login() function returning FALSE, and if user is banned, you can user this function to get the reason.
is_username_available($username)
Check if username is available to use, by making sure there is no same username in the database. Typical usage of this function is in form validation callback function.
is_email_available($email)
Check if email is available to use, by making sure there is no same email in the database. Typical usage of this function is in form validation callback function.
get_auth_error()
Get an error message when login(), forgot_password(), change_password(), cancel_account() function is returning FALSE.
is_max_login_attempts_exceeded()
Check if login attempts is more than max login attempts specified in dx_auth config file.
Login attempt increase count based on login attempted by IP address.
check_uri_permissions($allow = TRUE)
This will check if current logged in user is allowed to access current URI, based on his role, or his parent role.
Here is the detail what happen when you call this function:
First, function will check if user is logged in or not, if user haven't login then it will redirect to login URI.
But if user is logged in, then it will check if user is admin.
If user is admin, then it is allowed to access the URI.
But if user is not admin, it will check if user role and parent role is allowed to accesss current URI based on URI rule in permissions table in database.
If user is not allowed, it will redirect to deny access URI.
You can call check_uri_permissions() in the controller constructor to protect the whole controller.
class Home extends Controller
{
function Home()
{
parent::Controller();
$this->dx_auth->check_uri_permissions();
}
}
Or use it within a function
function hello_world()
{
$this->dx_auth->check_uri_permissions();
// Do something
}
Case example:
There is a user with role_id = 1 (normal user).
And then in permissions table, there is a record specify role_id = 1 have permission URI to access '/test/' URI.
Now this user want to access uri '/test/hi/'.
If you have code like this in Test controller :
class Test extends Controller
{
function Test()
{
parent::Controller();
// Secure controller
$this->dx_auth->check_uri_permissions();
}
function hi()
{
echo 'Hi';
}
function hello()
{
echo 'Hello';
}
}
This user will pass the check and access '/test/hi/' URI, and echo 'Hi'.
Because if permission URI set to '/test/', it means grant access to class Test and all it's function.
If you want to limit role access to function only, you can specify '/class/function/' when setting permission URI.
For example, in previous case example if you change role_id = 1 URI permission to '/test/hi/',
user will able to access 'test/hi/' URI, but cannot access 'test/hello/' URI.
You also can set URI permission to '/' to enable role access all URI.
It is possible to reverse all this explanation by specifiying $allow = TRUE when calling check_uri_permissions().
So instead of allowing user to access URI when URI permission found, it will disallow user to access URI when URI permission found.
To set URI permission, you have to use function given in permissions model, or make your own. See the example on how to set the permission.
For CL Auth user, notice that URI permission now renamed to '/class/function/' instead of '/class/function'.
Inheritance
If user role have parent role, then user also have access to parent role, and so on. To describe this, let's have this URI Permission illustration.
User
{
'/home/'
'/help/'
}
Moderator: User
{
'/moderator/'
}
Super_Moderator: Moderator
{
'/super/'
}
Big_Moderator: Moderator
{
'/big/'
}
This means, Super_Moderator role can access Moderator and User URI, but cannot access Big_Moderator URI.
To use this feature, you need to specify parent for each role in parent_id field in roles table.
In previous case, here is the illustration of the roles table
id parent_id name ------------------------- 1 0 User 2 0 Admin 3 1 Moderator 4 3 Super Moderator 5 3 Big Moderator
Note Using this function is optional, you might don't want to use it if you pretty comfortable checking the user manually using function like is_admin(), is_role(), is_logged_in(), etc.
get_permission_value($key, $check_parent = TRUE)
Get permission value from specified key. Call this function only when user is logged in already.
$key is permission array key (Note: permissions is saved as array in table).
If $check_parent is TRUE means if permission value not found in user role, it will try to get permission value from parent role.
Returning value if permission found, otherwise returning NULL.
To set permission, you have to use function given in permissions model, or make your own. See the example on how to set the permission.
Note Using this function is optional, you might don't want to use it if you pretty comfortable checking the user manually, and give permission manually using function like is_admin(), is_role(), etc.
get_permissions_value($key, $array_key = 'default')
Get permissions value from specified key. Call this function only when user is logged in already.
This function will search key in user permission, and it's parents permissions.
$key is permission array key (Note: permissions is saved as array in table).
$array_key = 'default'. Retrurning array ordered using 0, 1, 2 as array key.
$array_key = 'role_id'. Retrurning array ordered using role_id as array key.
$array_key = 'role_name'. Retrurning array ordered using role_name as array key.
Returning array of value if permission found, otherwise returning NULL.
To set permission, you have to use function given in permissions model, or make your own. See the example on how to set the permission.
Note Using this function is optional, you might don't want to use it if you pretty comfortable checking the user manually, and give permission manually using function like is_admin(), is_role(), etc.
deny_access($uri = 'deny')
Calling this function will redirect user depending on $uri variable. Default $uri is 'deny'
$uri = 'deny' will redirect user to 'DX_deny_uri' specified in dx_auth config file.
$uri = 'login' will redirect user to 'DX_login_uri' specified in dx_auth config file.
$uri = 'banned' will redirect user to 'DX_banned_uri' specified in dx_auth config file.
catpcha()
Creating a captcha to be used in form validation.
get_catpcha_image()
Get HTML image of created catpcha. Use this function in view file.
is_captcha_expired()
Check if created captcha already expired or not. Use this in callback form validation function.
is_captcha_match($code)
Check if created catpcha text match with the $code. Use this in callback form validation function.
reCAPTCHA functions
Below is reCAPTCHA function list. Because of name limitation in reCAPTCHA API (everything should have fixed name), reCAPTCHA function is separated from native DX Auth captcha.
To use reCAPTCHA function you have to set DX_recaptcha_public_key and DX_recaptcha_private_key in dx_auth config file. To get the key you can register at reCAPTCHA website.
You can find an example to use reCAPTCHA in registration here.
get_recaptcha_reload_link($text = 'Get another CAPTCHA')
Get reCAPTCHA reload captcha link, with $text as anchor text. Use this function in view file.
get_recaptcha_switch_image_audio_link($switch_image_text = 'Get an image CAPTCHA', $switch_audio_text = 'Get an audio CAPTCHA')
Get reCAPTCHA switch image or audio link. Use this function in view file.
get_recaptcha_label($image_text = 'Enter the words above', $audio_text = 'Enter the numbers you hear')
Get reCAPTCHA label telling user to input captcha in the inputbox. Use this function in view file.
get_recaptcha_input()
Get reCAPTCHA input box to input captcha. Use this function in view file.
You should use this function, otherwise reCAPTCHA image won't show up because reCAPTCHA javascript will try to find this input box.
get_recaptcha_image()
Get reCATPCHA image. Use this function in view file.
get_recaptcha_html()
Get reCAPTCHA javascript and non javasript html. Use this function in view file.
This is the main part of reCAPTCHA function.
Call this function after you are using some or all get_recaptcha_xxx function above.
Meaning this function should be called the last.
is_recaptcha_match()
Check if created reCAPTCHA text match with the text that user inputed in get_recaptcha_input() function. Use this in callback form validation function.
check_role_uri()
This function is obsolete in version 1.0.2 above. Use check_uri_permissions() to have same effect with new permission table.