twzAuth.doc.txt
twzAuth.class v0.1.1 2015-03-22
-----------------------------------------------------------------------------
I N T R O D U C T I O N
==========================================
twzAuth is an ultra-simple user "login" script using basic
HTTP authentication, and allowing easy user management.
Similar functionality is provided by Apache using .htaccess/.htpasswds,
and available via cPanel as "Password protect directories".
While twzAuth is similar to the Apache HTTP auth, IT IS NOT THE SAME.
In particular, Apache HTTP auth protects every file in a directory,
while twzAuth only protects specific php pages that include the
$auth->validate() call.
twzAuth is intended as a quick solution for a small number of users.
If you have more than 10 or 20 users, you probably should consider a
more robust database solution.
I N S T A L L A T I O N
==========================================
Before uploading to your server, make sure to edit the include file/s
with your preferred settings. The requirements are slightly different
for simple mode vs extended mode (modes are explained below).
For simple mode: change the $ValidUsers array to set the usernames and
passwords you want to use.
For extended mode: change the datastore pathname (default './users.db')
to your preferred location, and change the setAdmin() to your preferred
admin username and password.
R U N T I M E M O D E S
==========================================
twzAuth runs in one of two modes:
SIMPLE MODE:
The class is instantiated with a plain text array of Usernames and
passwords. Users and passwords can be changed by editing the php
script. The only public method applicable in simple mode is validate().
All users are equal in simple mode; there is no concept of 'admin user'.
EXTENDED MODE:
The class is instantiated with a datastore pathname (string). Usernames
and passwords are stored in that file. Some users may be Admin users
who can add, edit, and delete users, and change passwords via a protected
web page. Additional custom fields are also supported (eg First name,
Last name).
SIMPLE MODE:
------------------------------------------
For example, protecting a single php page with twzAuth in 'simple mode' is as
easy as adding these lines at the top of the file:
require 'twzAuth.class.php';
$auth=new twzAuth( array('admini'=>'stR8_Er$') );
$Username = $auth->validate();
As you can see, the username and password is hard-coded in the script, so you
can easily change the password or add more users by editing the script and
re-uploading it. The variable $Username will contain the username that has
been authenticated (in this case it will always be 'admini' because that's
the only valid user). To protect multiple php pages, move these lines into
a separate include script, and include it in each page.
EXTENDED MODE:
------------------------------------------
Extended mode offers more features and possibilities, and is just as easy to implement:
require 'twzAuth.class.php';
$auth=new twzAuth( '../../users.db' ); // TIP: datastore is safer above the web root
$auth->setAdmin('tony', 'e#tAg683%eWs.-(');
$Username = $auth->validate();
In this case you specify a file where user information will be stored, and by
calling setAdmin() with a username and password, you ensure there is an initial
user so you can log in. You can add, update or delete users from a special
web page designed for this (see included example admin.php). You can change your
own password this way too; setAdmin() won't do anything if the user alreay exists.
P U B L I C M E T H O D S
==========================================
As mentioned above, 'simple mode' only supports one method: validate().
There are additional methods available in extended mode, some of which can
only be called by an admin user.
__construct($Users, $Realm=false, $FailHtml=false, $CustomFields=false)
_____________________________________________________________________________
The twzAuth class is instantiated with at least one parameter ($Users);
the other parameters are optional, and if missing or 'false', will be
set to default values.
$Users
1. For simple mode, an array of passwords indexed by Username.
eg array( 'stacie'=>'Wd$5gHf^4', 'danny'=>'5r4RF$4eD%', 'threesocks'=>'R323&*(j4fd' )
2. For extended mode, a string specifying the pathname of the datastore.
eg '../../myUsers.db'
The specified directory must exist (preferably above the web root), and
the file must be writable by PHP.
$Realm
A string presented to the user, akin to a name for the protected page/s.
If missing or false, defaults to 'Restricted area'.
$FailHtml
A string containing HTML that will be sent to the browser if user
authentication fails (ie if the user cancels the dialog box).
If missing or false, defaults to '<h2>401 Unauthorized</h2>'.
$CustomFields
(extended mode only) a string of comma-separated custom field names.
For example if you want to record each user's name and date of birth,
this parameter could be the string 'First name, Last name, dob'.
If missing or false, no custom fields will be used.
If you use custom fields the addUser(), editUser() and getUserInfo()
methods will accept or return the custom field values, but it's up to
you to manage how they are used or interpreted.
If you have a custom field which is entered via a textarea input
(eg 'Comment'), then it may contain newline or tab characters.
These will be encoded for storage purposes, and you will need to
decode them for display. For example:
echo str_replace(array('\r', '\n', '\t'), array("\r", "\n", "\t"), $User['Comment']);
validate($AdminOnly=false)
_____________________________________________________________________________
This is the principal method of the twzAuth class. It attempts to validate
the user against the current list of usernames and passwords. Username may
be entered by the user with any mix of upper/lower case.
On success, it returns the validated username (with upper/lower case as entered
by the user). On error, the method doesn't return at all; instead it sends
'401 Unauthorized' headers to the browser, and displays the HTML specified in
$FailHtml (__construct parameter).
If the $AdminOnly parameter is set to true, success will only occur if the
validated user is an admin user (extended mode only). An alternative to this
is to call validate() without the parameter, then check isAdmin() and take
appropriate action.
addUser($Username, $Fields)
_____________________________________________________________________________
Adds a new user to the system. This method can only be run by an admin user.
$Username
Username of the new user
$Fields
If you just want to set the user's password, this parameter can be a string.
To set any custom fields, it will be an array of field names and values.
eg array( 'First name'=>'Kris', 'Password'=>'xXx345+eWq' )
If a password is specified as an empty string, a random password will be
generated, which can be discovered by calling newPassword() immediately
following this method.
deleteUser($Username)
_____________________________________________________________________________
Deletes the user with the specified Username. This method can only be run
by an admin user.
editUser($Username, $Fields)
_____________________________________________________________________________
Updates information for an existing user. This method can only be run
by an admin user.
$Username
Username of the user to update
$Fields
Password string, or array of field names and values - refer to the
addUser() method for a full explanation.
getUserInfo($Username=false)
_____________________________________________________________________________
Returns an array of information for the specified user, or the current
user if $Username not specified. Only an admin user can specify $Username.
getUsernames()
_____________________________________________________________________________
Returns a simple array of all usernames. This method can only be run
by an admin user.
getUsers()
_____________________________________________________________________________
Returns an array containing all information held for all users.
This method can only be run by an admin user.
isAdmin()
_____________________________________________________________________________
Returns true if the current user is an admin user, false if not.
lastError()
_____________________________________________________________________________
Returns a string containing the last error, or false if none.
newPassword()
_____________________________________________________________________________
Returns the last password saved by addUser() or editUser(),
or false if none.
setAdmin($Username, $Password)
_____________________________________________________________________________
If user $Username doesn't exist, this method adds it as an admin user.
This is mainly for adding the initial user in extended mode.
|
Download
