Professional Documents
Culture Documents
Documentation
Ion Auth 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-IonAuth/zipball/2 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. 3. Run the appropriate SQL file from the /sql directory. The default login is: Email: admin@admin.com Password: password
Configuration Options
Ion Auth is extremely configurable. The following configuration options are available: $config['tables']['groups']
$config['tables']['users'] $config['tables']['users_groups'] $config['tables']['login_attempts'] $config['site_title'] $config['admin_email'] $config['default_group'] $config['admin_group'] $config['join']['users'] $config['join']['groups'] $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_type'] $config['email_templates'] $config['email_activate'] $config['email_forgot_password'] $config['email_forgot_password_complete'] $config['salt_length'] $config['store_salt'] $config['forgot_password_expiration'] $config['track_login_attempts'] $config['maximum_login_attempts']
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. Set to zero for no expiration. DEFAULT is '86500'. 'user_extend_on_login' - TRUE or FALSE. Extend the users session expiration on login. DEFAULT is 'false'. 'email_type' - Email content type. DEFAULT us 'html'. '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'. 'forgot_password_expiration' - Number of seconds before a forgot password request expires. If set to 0, requests will not expire. DEFAULT is 0. 'track_login_attempts' - Track the number of failed login attempts for each user or ip. DEFAULT is 'false'. 'maximum_login_attempts' - Set the maximum number of failed login attempts. This maximum is not enforced by the library, but is used by $this->ion_auth-
>is_max_login_attempts_exceeded(). The controller should check this function and act appropriately. If set to 0, there is no maximum. DEFAULT is 3. '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>'.
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
logout()
Logs the user out of the system. Usage
$ t h i s > i o n _ a u t h > l o g o u t ( ) ;
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' - array OPTIONAL. If not passed the default group name set in the config will be used.
Return mixed. The ID of the user if the user was successfully created, FALSE if the user was not created. Usage
$ u s e r n a m e=' b e n e d m u n d s ' ; $ p a s s w o r d=' 1 2 3 4 5 6 7 8 ' ; $ e m a i l=' b e n . e d m u n d s @ g m a i l . c o m ' ; $ a d d i t i o n a l _ d a t a=a r r a y ( ' f i r s t _ n a m e '= >' B e n ' , ' l a s t _ n a m e '= >' E d m u n d s ' , ) ;
$ t h i s > i o n _ a u t h > r e g i s t e r ( $ u s e r n a m e ,$ p a s s w o r d ,$ e m a i l ,$ a d d i t i o n a l _ d a t a ,$ g r o u
update()
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
$ i d=1 2 ; $ d a t a=a r r a y ( ' f i r s t _ n a m e '= >' B e n ' , ' l a s t _ n a m e '= >' E d m u n d s ' , ' p a s s w o r d '= >' 1 2 3 4 5 6 7 8 9 ' , ) ; $ t h i s > i o n _ a u t h > u p d a t e ( $ i d ,$ d a t a )
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
$ i d=1 2 ; $ t h i s > i o n _ a u t h > d e l e t e _ u s e r ( $ i d )
forgotten_password()
Resets a users password by emailing the user a reset code. Parameters 1. 'Identity' - string REQUIRED. (as defined in config/ion_auth.php) Return boolean. TRUE if the users password was successfully reset FALSE if the users password was not reset. Usage - this example assumes you have 'email' selected as the identity in config/ion_auth.php
/ / W o r k i n gc o d ef o rt h i se x a m p l ei si nt h ee x a m p l eA u t hc o n t r o l l e ri nt h eg i t h u b f u n c t i o nf o r g o t _ p a s s w o r d ( ) {
$ t h i s > f o r m _ v a l i d a t i o n > s e t _ r u l e s ( ' e m a i l ' ,' E m a i lA d d r e s s ' ,' r e q u i r e d ' ) i f( $ t h i s > f o r m _ v a l i d a t i o n > r u n ( )= =f a l s e ){ / / s e t u pt h ei n p u t $ t h i s > d a t a [ ' e m a i l ' ]=a r r a y ( ' n a m e ' = >' e m a i l ' , ' i d ' ) ; / / s e ta n ye r r o r sa n dd i s p l a yt h ef o r m
$ t h i s > d a t a [ ' m e s s a g e ' ]=( v a l i d a t i o n _ e r r o r s ( ) )?v a l i d a t i o n _ e r r $ t h i s > l o a d > v i e w ( ' a u t h / f o r g o t _ p a s s w o r d ' ,$ t h i s > d a t a ) ; } e l s e{
/ / r u nt h ef o r g o t t e np a s s w o r dm e t h o dt oe m a i la na c t i v a t i o nc o d e
i f( $ f o r g o t t e n ){/ / i ft h e r ew e r en oe r r o r s
e l s e{
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
i f( $ r e s e t ){ / / i ft h er e s e tw o r k e dt h e ns e n dt h e mt ot h el o g i np a g e
$ t h i s > s e s s i o n > s e t _ f l a s h d a t a ( ' m e s s a g e ' ,$ t h i s > i o n _ a u t h > m e s s a r e d i r e c t ( " a u t h / l o g i n " ,' r e f r e s h ' ) ; }
e l s e{/ / i ft h er e s e td i d n tw o r kt h e ns e n dt h e mb a c kt ot h ef o r g o tp a s s
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
i f( ! $ t h i s > i o n _ a u t h > l o g g e d _ i n ( ) ) { r e d i r e c t ( ' a u t h / l o g i n ' ) ; }
is_admin()
Check to see if the currently logged in user is an admin. Parameters 1. 'id' - integer OPTIONAL. If a user id is not passed the id of the currently logged in user will be used. Return
boolean. TRUE if the user is an admin FALSE if the user is not an admin. Usage
i f( ! $ t h i s > i o n _ a u t h > i s _ a d m i n ( ) ) {
in_group()
Check to see if the currently logged in user is in the passed in group. Parameters 1. 'Group ID or Name' - string, integer or array of strings and integers REQUIRED. 2. 'User ID' - integer OPTIONAL. If a user id is not passed the id of the currently logged in user will be used. Return boolean. TRUE if the user is in any of the given groups, FALSE otherwise. Usage
#s i n g l eg r o u p( b yn a m e ) $ g r o u p=' g a n g s t a s ' ; i f( ! $ t h i s > i o n _ a u t h > i n _ g r o u p ( $ g r o u p ) ) {
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
/ / T h i si sal a m ee x a m p l eb u ti tw o r k s . U s u a l l yy o uw o u l du s et h i sm e t h o dw i t h $ u s e r n a m e=$ t h i s > i n p u t > p o s t ( ' u s e r n a m e ' ) ; $ p a s s w o r d=$ t h i s > i n p u t > p o s t ( ' p a s s w o r d ' ) ; $ e m a i l=$ t h i s > i n p u t > p o s t ( ' e m a i l ' ) ; $ a d d i t i o n a l _ d a t a=a r r a y (
$ t h i s > i o n _ a u t h > r e g i s t e r ( $ u s e r n a m e ,$ p a s s w o r d ,$ e m a i l ,$ a d d i t i o n a l _ d a t }
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
/ / T h i si sal a m ee x a m p l eb u ti tw o r k s . U s u a l l yy o uw o u l du s et h i sm e t h o dw i t h $ u s e r n a m e=$ t h i s > i n p u t > p o s t ( ' u s e r n a m e ' ) ; $ p a s s w o r d=$ t h i s > i n p u t > p o s t ( ' p a s s w o r d ' ) ; $ e m a i l=$ t h i s > i n p u t > p o s t ( ' e m a i l ' ) ; $ a d d i t i o n a l _ d a t a=a r r a y (
$ t h i s > i o n _ a u t h > r e g i s t e r ( $ u s e r n a m e ,$ p a s s w o r d ,$ e m a i l ,$ a d d i t i o n a l _ d a t }
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
/ / T h i si sal a m ee x a m p l eb u ti tw o r k s . $ u s e r=$ t h i s > i o n _ a u t h > u s e r ( ) ; $ d a t a=a r r a y ( ' i d e n t i t y '= >$ t h i s > i n p u t > p o s t ( ' i d e n t i t y ' ) , ' f i r s t _ n a m e '= >$ t h i s > i n p u t > p o s t ( ' f i r s t _ n a m e ' ) , ' l a s t _ n a m e '= >$ t h i s > i n p u t > p o s t ( ' l a s t _ n a m e ' ) , ) ;
is_max_login_attempts_exceeded()
If login attempt tracking is enabled, checks to see if the number of failed login attempts for this identity or ip address has been exceeded. The controller must call this method and take any necessary actions. Login attempt limits are not enforced in the library. Parameters 1. 'Identity' - string REQUIRED. Return boolean. TRUE if maximum_login_attempts is exceeded FALSE if not or if login attempts not tracked. Usage
get_attempts_num()
Returns the number of failed login attempts for this identity or ip address. Parameters 1. 'Identity' - string REQUIRED. Return int. The number of failed login attempts for this identity or ip address. Usage
$ i d e n t i t y=' b e n . e d m u n d s @ g m a i l . c o m ' ; $ n u m _ a t t e m p t s=$ t h i s > i o n _ a u t h > g e t _ a t t e m p t s _ n u m ( $ i d e n t i t y ) ;
increase_login_attempts()
If login attempt tracking is enabled, records another failed login attempt for this identity or ip address. This method is automatically called during the login()
clear_login_attempts()
Clears all failed login attempt records for this identity or this ip address. This method is automatically called during the login() method if the login succeded. Parameters 1. 'Identity' - string REQUIRED. Usage
$ i d e n t i t y=' b e n . e d m u n d s @ g m a i l . c o m ' ; $ p a s s w o r d=' 1 2 3 4 5 6 7 8 ' ; i f( $ t h i s > i o n _ a u t h > l o g i n ( $ i d e n t i t y ,$ p a s s w o r d )= =T R U E ){ $ t h i s > i o n _ a u t h > c l e a r _ l o g i n _ a t t e m p t s ( $ i d e n t i t y ) }
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
s t d C l a s sO b j e c t( [ i d ]= >1 [ i p _ a d d r e s s ]= >1 2 7 . 0 . 0 . 1 [ u s e r n a m e ]= >a d m i n i s t r a t o r [ p a s s w o r d ]= >5 9 b e e c d f 7 f c 9 6 6 e 2 f 1 7 f d 8 f 6 5 a 4 a 9 a e b 0 9 d 4 a 3 d 4 [ s a l t ]= >9 4 6 2 e 8 e e e 0 [ e m a i l ]= >a d m i n @ a d m i n . c o m
[ a c t i v a t i o n _ c o d e ]= >1 9 e 1 8 1 f 2 c c c 2 a 7 e a 5 8 a 2 c 0 a a 2 b 6 9 f 4 3 5 5 e 6 3
[ f o r g o t t e n _ p a s s w o r d _ c o d e ]= >8 1 d c e 1 d 0 b c 2 c 1 0 f b d e c 7 a 8 7 f 1 f f 2
Usage
$ u s e r=$ t h i s > i o n _ a u t h > u s e r ( ) > r o w ( ) ; e c h o$ u s e r > e m a i l ;
users()
Get the users. Parameters 1. 'Group IDs' - array OPTIONAL. If an array of group ids are passed (or a single group id) this will return the users in those groups. Return array of objects Usage
$ u s e r s=$ t h i s > i o n _ a u t h > u s e r s ( ) > r e s u l t ( ) ;
group()
Get a group. Parameters 1. 'Id' - integer REQUIRED. Return object Usage
groups()
Get the groups. Return array of objects Usage
$ g r o u p s=$ t h i s > i o n _ a u t h > g r o u p s ( ) > r e s u l t ( ) ;
messages()
Get messages. Return string Usage
$ i d=1 2 ; $ d a t a=a r r a y ( ' f i r s t _ n a m e '= >' B e n ' , ' l a s t _ n a m e '= >' E d m u n d s ' ,
messages_array()
Get messages as an array. Return array Parameters 1. 'Langify' - boolean OPTIONAL. TRUE means that the messages will be langified. Usage
$ i d=1 2 ; $ d a t a=a r r a y ( ' f i r s t _ n a m e '= >' B e n ' , ' l a s t _ n a m e '= >' E d m u n d s ' , ) ; i f( $ t h i s > i o n _ a u t h > u p d a t e _ u s e r ( $ i d ,$ d a t a ) ) {
get_users_groups()
Get all groups a user is part of. Parameters 1. 'Id' - integer OPTIONAL. If a user id is not passed the id of the currently logged in user will be used. Return
s t d C l a s sO b j e c t( [ i d ]= >1 [ n a m e ]= >a d m i n s [ d e s c r i p t i o n ]= >A d m i n i s t r a t o r )
Usage
$ u s e r _ g r o u p s=$ t h i s > i o n _ a u t h > g e t _ u s e r s _ g r o u p s ( $ u s e r > i d ) > r e s u l t ( ) ;
remove_from_group()
Remove user from group(s) Parameters 1. 'User_id' - integer REQUIRED. Return boolean. TRUE if the user was removed from group(s) FALSE if the user is not removed from group(s). Usage
/ /p a s sa na r r a yo fg r o u pI D ' sa n du s e rI D $ t h i s > i o n _ a u t h > r e m o v e _ f r o m _ g r o u p ( a r r a y ( ' 1 ' ,' 3 ' ,' 6 ' ) ,$ u s e r _ i d ) ;
/ /p a s sN U L Lt or e m o v eu s e rf r o ma l lg r o u p s $ t h i s > i o n _ a u t h > r e m o v e _ f r o m _ g r o u p ( N U L L ,$ u s e r _ i d ) ;
create_group()
Create a group Parameters 1. 'group_name' - string REQUIRED. 2. 'group_description' - string. Return brand new group_id if the group was created, FALSE if the group creation failed. Usage
/ /p a s st h er i g h ta r g u m e n t sa n di t ' sd o n e
update_group()
Update details of a group
Parameters 1. 'group_id' - int REQUIRED. 2. 'group_name' - string REQUIRED. 3. 'group_description' - string. Return boolean. TRUE if the group was updated, FALSE if the update failed. Usage
/ /s o u r c et h e s et h i n g sf r o ma n y w h e r ey o ul i k e( e g . ,af o r m ) $ g r o u p _ i d=2 ; $ g r o u p _ n a m e=' t e s t _ g r o u p _ c h a n g e d _ n a m e ' ; $ g r o u p _ d e s c r i p t i o n=' Ic h a n g e dt h en a m ey a y ' ;
/ /p a s st h er i g h ta r g u m e n t sa n di t ' sd o n e
delete_group()
Remove a group. Removes the group details from the configured 'groups' table. Users belonging to the group are stripped of this status (references to this group are removed from users_groups), but user data itself remains untouched. Parameters 1. 'group_id' - int REQUIRED. Return boolean. TRUE if the group was deleted, FALSE if the delete failed. Usage
/ /s o u r c et h i sf r o ma n y w h e r ey o ul i k e( e g . ,af o r m ) $ g r o u p _ i d=2 ;
set_message_delimiters()
Set the message delimiters.
Parameters 1. 'Start Delimiter' - string REQUIRED. 2. 'End Delimiter' - string REQUIRED. Usage
$ i d=1 2 ; $ d a t a=a r r a y ( ' f i r s t _ n a m e '= >' B e n ' , ' l a s t _ n a m e '= >' E d m u n d s ' , ) ; i f( $ t h i s > i o n _ a u t h > u p d a t e _ u s e r ( $ i d ,$ d a t a ) ) {
$ t h i s > i o n _ a u t h > s e t _ m e s s a g e _ d e l i m i t e r s ( ' < p > < s t r o n g > ' , ' < / s t r o n g > < / p > ' ) ; $ m e s s a g e s=$ t h i s > i o n _ a u t h > m e s s a g e s ( ) ; e c h o$ m e s s a g e s ; } e l s e { $ t h i s > i o n _ a u t h > s e t _ e r r o r _ d e l i m i t e r s ( ' < p > < s t r o n g > ' , ' < / s t r o n g > < / p > ' ) ; $ e r r o r s=$ t h i s > i o n _ a u t h > e r r o r s ( ) ; e c h o$ e r r o r s ; }
errors()
Get the errors. Return string
Usage
$ i d=1 2 ; $ d a t a=a r r a y ( ' f i r s t _ n a m e '= >' B e n ' , ' l a s t _ n a m e '= >' E d m u n d s ' , ) ; i f( $ t h i s > i o n _ a u t h > u p d a t e _ u s e r ( $ i d ,$ d a t a ) ) { $ m e s s a g e s=$ t h i s > i o n _ a u t h > m e s s a g e s ( ) ; e c h o$ m e s s a g e s ; } e l s e { $ e r r o r s=$ t h i s > i o n _ a u t h > e r r o r s ( ) ; e c h o$ e r r o r s ; }
errors_array()
Get error messages as an array. Return array Parameters 1. 'Langify' - boolean OPTIONAL. TRUE means that the error messages will be langified. Usage
$ i d=1 2 ; $ d a t a=a r r a y ( ' f i r s t _ n a m e '= >' B e n ' , ' l a s t _ n a m e '= >' E d m u n d s ' , ) ; i f( $ t h i s > i o n _ a u t h > u p d a t e _ u s e r ( $ i d ,$ d a t a ) ) { $ m e s s a g e s=$ t h i s > i o n _ a u t h > m e s s a g e s _ a r r a y ( ) ; f o r e a c h( $ m e s s a g e sa s$ m e s s a g e ) { e c h o$ m e s s a g e ; } } e l s e { $ e r r o r s=$ t h i s > i o n _ a u t h > e r r o r s _ a r r a y ( ) ; f o r e a c h( $ e r r o r sa s$ e r r o r ) { e c h o$ e r r o r ; } }
set_error_delimiters()
Set the error delimiters. Parameters 1. 'Start Delimiter' - string REQUIRED. 2. 'End Delimiter' - string REQUIRED.
Usage
$ i d=1 2 ; $ d a t a=a r r a y ( ' f i r s t _ n a m e '= >' B e n ' , ' l a s t _ n a m e '= >' E d m u n d s ' , ) ; i f( $ t h i s > i o n _ a u t h > u p d a t e _ u s e r ( $ i d ,$ d a t a ) ) {
$ t h i s > i o n _ a u t h > s e t _ m e s s a g e _ d e l i m i t e r s ( ' < p > < s t r o n g > ' , ' < / s t r o n g > < / p > ' ) ; $ m e s s a g e s=$ t h i s > i o n _ a u t h > m e s s a g e s ( ) ; e c h o$ m e s s a g e s ; } e l s e { $ t h i s > i o n _ a u t h > s e t _ e r r o r _ d e l i m i t e r s ( ' < p > < s t r o n g > ' , ' < / s t r o n g > < / p > ' ) ; $ e r r o r s=$ t h i s > i o n _ a u t h > e r r o r s ( ) ; e c h o$ e r r o r s ; }
set_hook()
Set a single or multiple functions to be called when trigged by trigger_events(). See an example here: http://gist.github.com/657de89b26decda2b2fa Parameters 1. 'Event' - string REQUIRED. 2. 'Name' - string REQUIRED. 3. 'Class' - string REQUIRED. 4. 'Method' - string REQUIRED.
p u b l i cf u n c t i o n_ _ c o n s t r u c t ( ) { p a r e n t : : _ _ c o n s t r u c t ( ) ;
$ n a m e=' a c t i v a t e _ s e n d m a i l ' ; $ m e t h o d=' e m a i l ' ; $ t h i s > i o n _ a u t h > s e t _ h o o k ( $ e v e n t ,$ n a m e ,$ c l a s s ,$ m e t h o d ,$ a r g s ) ; $ n a m e=' c a l l _ T w i t t e r ' ; $ m e t h o d=' t w i t t e r ' ; $ t h i s > i o n _ a u t h > s e t _ h o o k ( $ e v e n t ,$ n a m e ,$ c l a s s ,$ m e t h o d ,$ a r g s ) ; $ n a m e=' c a l l _ M a i l C h i m p _ A P I ' ; $ m e t h o d=' m a i l c h i m p ' ; $ t h i s > i o n _ a u t h > s e t _ h o o k ( $ e v e n t ,$ n a m e ,$ c l a s s ,$ m e t h o d ,$ a r g s ) ; $ n a m e=' c a l l _ F a c e b o o k _ A P I ' ; $ m e t h o d=' f a c e b o o k ' ; $ t h i s > i o n _ a u t h > s e t _ h o o k ( $ e v e n t ,$ n a m e ,$ c l a s s ,$ m e t h o d ,$ a r g s ) ; $ n a m e=' c a l l _ g P l u s _ A P I ' ; $ m e t h o d=' g p l u s ' ; $ t h i s > i o n _ a u t h > s e t _ h o o k ( $ e v e n t ,$ n a m e ,$ c l a s s ,$ m e t h o d ,$ a r g s ) ; }
trigger_events()
Call Additional functions to run that were registered with set_hook().
Top of Page
Architecting awesome software by day, hacking on interesting ideas by night. PHP Town Hall podcast co-host. PDX PHP co-