PHP Class hn_htusers :: Short-Documentation

Source: http://hn273.users.phpclasses.org/hn_htusers
Version 1.0, 19. October 2009

Initializing the Class
Loading Data and automatical SetupCheck
The Manage Methods
Configuration Methods
Retrieve Information

^ Initializing the Class

First there have to be defined some Constants: HTPASSWDPATH and HTUSERFILE. HTPASSWDPATH is the fullpath (not url) to the directory where the htfiles are hosted. HTUSERFILE is the basename of the .htuser file, (also known as .htpassword). Optionally you may use a HTGROUPFILE and / or a HTINFOFILE.

# define HTPASSWDPATH and HTUSERFILE is mandatory,
# define (and use) HTGROUPFILE or HTINFOFILE is optional (both)

	define('HTPASSWDPATH',  dirname(__FILE__).'/');
	define('HTUSERFILE',   '.htuser');
	define('HTGROUPFILE',  '.htgroup');
	define('HTINFOFILE',   '.htinfo');

Reference: httpd.apache.org/docs/1.3/howto/auth.html

Calling the Class-Constructor and passing init data:

# initialize the class
	# param 1: URL of this script, needed for Redirections and Formactions
	# param 2: (optional) array with admin-userid/s
	# param 3: (optional) name of the admin group

	$ht = new hn_htusers($_SERVER['SCRIPT_NAME'], array('horst','admin'), 'admins');

The first param in most cases should be $_SERVER['SCRIPT_NAME']. The second and third param define which user(s) are admin(s). If as second param an array() with usernames is passed, these are the admin(s). Also if the third param is passed, it is ignored when an array is passed. If you need to define the admin-groupname, pass it as third param and NULL as second param. Then all users set as members to that group in .htgroup file are admin(s).

^ Loading Data and automatic SetupCheck

Because the constructor cannot send back e.g. a TRUE or FALSE, failures of the SetupCheck will stored in the classvar $errors. The second method called checks this and send back a boolean TRUE/FALSE, so this is used to check it:

# now we load the file(s)
# if there are any errors, it returns false, ...

	if(!$ht->load_files())
	{
		# ... and we should read the errors and exit
		echo $ht->errors;
		exit(1);
	}

When installing the script the first time on a machine, there is a CheckUp Routine that should be run once:

	$ht = new hn_htusers($_SERVER['SCRIPT_NAME'], NULL, 'admins');
	$ht->setup_test();

^ The Manage Methods

After initializing the class and loading the data, the main method, manage_users() is called. It presents a Table with all used data, which can be users, infos and groups. It allows changes to the data by calling the other management methods:

add_user()
delete_user()
add_group()
delete_group()
set_user2groups()
save_password($redirect=TRUE)
change_pwd_request($print_out_only_form=TRUE, $optional_change_info_too=FALSE)

Without the change_pwd_request() method, all of them process data, saves it, if valid, and redirect back to the manage_users() form.

Please look into the hn_htusers.manager.php file, which is shipped with the package.

^ Configuration Methods

$ht->set_validation_config('pass', 8,  50, '/[^a-zA-Z0-9\._@-]/', 'Password is not valid! Please use only a-z A-Z 0-9 ._-@');

The Class uses a default setup, that can be changed to suit your needs. Used for data validation is the set_validation_config() method. As first param, there is to pass a string containing one of [ user | pass | info | group ]. ('user' is the userid/username, 'pass' means data for passwords, 'group' means the groupnames and 'info' the (optional) extra infos.) Second and third params are integer and set the values for minimum and maximum data string length. Fourth param is a RegEx Pattern that defines all chars that are not allowed to use with this type of data, e.g. '/[^a-zA-Z0-9\._@-]/'. The fifth and last param is an errortext, which will be displayed to the user, if there were found not allowed chars in data.

$ht->set_fontsize($font_size='11px');

With set_fontsize() there can be passed one param, a string with a valid css font-size definition, like '12px', '0.9em', etc. These value nearly is used for all fontsizes in the Management-Forms, without the header.

$ht->set_user_mustbe_email(TRUE,
      array('from'=>'info@example.com',
            'subject'=>'Your Password has changed',
            'body'=>"Username: [_USER_]\nPassword: [_PASS_]"));

If one want to use E-mailadresses as userids/usernames, the set_user_mustbe_email() method can called with the first param as boolean TRUE. As second param, there can be passed an configuration array $sendmail_config - an Array with named keys 'from', 'subject', 'body'. The key 'body' should be contain 2 Placeholders: [_USER_] and [_PASS_]. This is used to notify the user via E-mail, when his password has changed.

^ Retrieve Information

$ht->getGetVar($name, $default);

getGetVar() is a generic routine to get a (sanitized) value from the $_GET variable.

$ht->getUserInfo($user)

If the getUserInfo($user) method is called without the optional param $user, it sets the $_SERVER['PHP_AUTH_USER'] to it. It returnes an array containing all available data, if the username is valid, otherwise a boolean FALSE.

'user' => 'username' (string)
'info' => 'optional extra info' (string)
'admin' => 'TRUE | FALSE' (boolean)
'groups' => array('editor','visitor'), an array containig the groupnames, the user is a member of, or an empty array, if the user not belongs to a group