PHP Classes

File: twzAuth.doc.txt

Recommend this page to a friend!
  Classes of Tony   twzAuth   twzAuth.doc.txt   Download  
File: twzAuth.doc.txt
Role: Documentation
Content type: text/plain
Description: Documentation
Class: twzAuth
Authenticate users using HTTP Basic authentication
Author: By
Last change: tweak
Date: 9 years ago
Size: 9,865 bytes
 

Contents

Class file image Download
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.