util.php File Reference

Misc. utility functions. More...

Go to the source code of this file.

Functions
	check_input ($user_input, $validation_info, $strict_mode=TRUE)
	check input data against a set of rules (regular expressions)
	do_template ($smarty, $template, $kw, $remember_me=FALSE)
	Display a Smarty template.
	get_html_options ($tables, $db, $key="id", $value="description", $order_by="description", $default=array())
	get_item_owner ($item, $id, $db)
	determine the "owner" of an item
	send_email ($smarty, $template, $kw, $email_to)
	Send an email, using a Smarty template as the body text.
	get_new_expiry_date ()
	Suggest an expiry date.
	check_acl ($acl_list, $item, $id, $db)
	Evaluate an ACL (access control list).
	set_random_pw ($uid, $dblink)
	Set a random password for a user account.
	smarty_init ()
	initialize the Smarty template engine
	guess_mime_type ($fn)
	guess a mime type from a file name

---

Detailed Description

Misc. utility functions.

Definition in file util.php.

---

Function Documentation

check_acl	(	$	acl_list,
		$	item,
		$	id,
		$	db
	)

Evaluate an ACL (access control list).

Check whether the user has access to an object, according to specfications in an access control list (ACL).

This function's purpose is to decide whether or not access to a specific item is granted. This function is used in action.php to decide whether or not to allow specific actions (e.g. 'delete') on an item. The decision is based on an access control list ($acl_list) that contains rules for access.

Parameters:

	$item	- item type (e.g. "book")
	$id	- id number of the item
	$db	- database handle
	$acl_list	- access control list (ACL)

$acl_list is an associative array, where the key is the item type, and the value is a string, containing a comma-separated list of statemensts.

Recognized statements in ACLs include:

• [statement1],...,[statementN] -- [statement1] OR ... OR [statementN]
• ![statement] -- NOT [statement]
• user=foo -- current user is "foo"
• role=bar -- current user's role is "bar" (e.g. administrator, staff, ...)
• owner -- current user is owner of the object, as determined by get_item_owner()
• any -- anybody (even anonymous users)

Example for an ACL list:

     $acl_list = array (
   		"any" => 	"owner" 
   		"book" => 	"owner,role=admin" 
   		"url" =>  	"any" 
   		"article" =>  	"user=admin" 
     )
    

In this (fictional) example,

• access is granted if the item type is "book" and the user is the book's owner, or if his role is that of an administrator.
• if the item is an URL, access is granted to anybody, even anonymous users (e.g. students)
• access is granted if the item is an article and the user is "admin"
• For all other items, the default rule $acl_list['any'] applies, i.e. access is granted if the user is the item's owner.

A statement's meaning can be negated by prepending an exclamation mark, e.g. "!owner" will allow access to anybody but the owner.

Ownership is decided based upon the result of the get_item_owner() function.

Definition at line 387 of file util.php.

References get_item_owner().

Referenced by do_action().

                                               {
        global $_SESSION;

        if (isset($acl_list[$item])) {
                $acl = $acl_list[$item];
        } else if (isset($acl_list['any'])) {
                $acl = $acl_list['any'];
        } else {
                return FALSE;
        }

        foreach (split(',', $acl) as $a) {

                list($k, $v) = split('=', $a);

                $inverse = false;

                switch($k) {
                case "!owner":
                        $inverse = TRUE;
                case "owner":

                        if ($id != "") {
                                $u = $_SESSION['user'];
                                $o = get_item_owner($item, $id, $db); 
                                $ok = ($u['id'] == $o['id']);
                        }

                        break;

                case "!role":
                        $inverse = TRUE;
                case "role":
                        $u = $_SESSION['user'];
                        $ok = ($u['role_name'] == $v);
                        break;

                case "!any":
                        $inverse = TRUE;
                case "any":
                        $ok = TRUE;
                        break;
                default:
                        user_error("acl syntax error: $k" , 
                        E_USER_ERROR); 
                }

                if ($inverse) {
                        $ok = (!$ok);
                }

                if ($ok) {
                        break;
                }       
        }

        return $ok;
}

Here is the call graph for this function:

check_input	(	$	user_input,
		$	validation_info,
		$	strict_mode = TRUE
	)

check input data against a set of rules (regular expressions)

Parameters:

	$user_input	-- an associative array with input data, e.g. $_GET, $_POST, etc.
	$validation_info	-- an associative array that contains keys and regular expressions.
	$user_input	-- input data to be checked for validity
	$strict_mode	-- request stricter checking (see below).

Note:

$user_input is considered valid input data if the string $user_input[$k] matches the regular expression $validation_info[$k].

If there is a key $k in $user_input[], but $validation_info[$k] does not exist, it depends on the value of $strict_mode whether the validation fails.

Definition at line 31 of file util.php.

References $validation_info.

Referenced by del_item(), do_action(), do_login(), edit_item(), setpw(), show_collection(), show_index(), and view_email().

                                                                           {

        global $debug_level;

        $err_info = array();

        foreach ($validation_info as $k => $dummy) {
                if (!isset($user_input[$k])) {
                        $user_input[$k] = ""; 
                }
        }


        if ($debug_level > 20) {
                print "<hr><pre>";
                print "check_input():\n\n";
        }

        foreach ($user_input as $k => $v) {

                $type = gettype($v);

                switch($type) {

                case "string":

                        if (isset($validation_info[$k])) {
                                $ok = preg_match($validation_info[$k], $v);
                        } else {
                                $ok = ($strict_mode) ? FALSE : TRUE;
                        }
                        break;

                case "array":
                        $ok = TRUE;
                        break;

                default:
                        $ok = FALSE;
                }
        

                if ($debug_level > 20) {
                        print "key: $k\n" ;
                        print "value: $v\n" ;
                        print "regexp: " . $validation_info[$k]. "\n"; 
                        print "ok: " ;
                        print (($ok) ? "yes" : "no" ) . "\n\n"; 
                }


                if (!$ok) { 
                        $err_info[] = $k; 
                }
        }

        if ($debug_level > 20) {
                print "</pre></hr>";
        }

        return $err_info;
}

do_template	(	$	smarty,
		$	template,
		$	kw,
		$	remember_me = FALSE
	)

Display a Smarty template.

This is a wrapper for the Smarty display() method, and is used throughout this program to handle things like standard headers and footers, debugging, etc.

Parameters:

	$smarty	-- a handle for the Smarty template engine
	$template	-- the file name for a template to be displayed
	$kw	-- an associative array. It's contents will be passed as Smarty variables.
	$remember_me	-- If $remember_me is true, the current URL will be stored in the PHP session variable $_SESSION['last_page'] for future reference. This can be used to implement a "go back" functionality, and is used in action.php.

Definition at line 111 of file util.php.

Referenced by del_item(), do_login(), edit_item(), send_reminder(), set_item_state(), setpw(), show_collection(), show_index(), show_users(), upload(), view_email(), and view_item().

                                                                     {

        global $_SESSION, $_SERVER, $debug_level;
        
        $smarty->compile_check = TRUE;

        # turn on debugging if so requested

        if ($debug_level > 5) {
                $smarty->debugging = true;
        }

        # assign smarty variables

        foreach ($kw as $k => $v)  {
                $smarty->assign($k, $v);
        }

        # add a header and a footer

        $smarty->display('header.tpl');
        $smarty->display($template);
        $smarty->display('footer.tpl');

        # clean up

        foreach ($kw as $k => $v)  {
                $smarty->clear_assign($k, $v);
        }

        # remember current page

        if ($remember_me) {
                $_SESSION['last_page'] = $_SERVER['REQUEST_URI'];
        }
}

get_item_owner	(	$	item,
		$	id,
		$	db
	)

determine the "owner" of an item

Parameters:

	$item	-- item type (e.g. "book")
	$id	-- item id
	$db	-- database handle

Returns:

an associative array that contains information about o the item's owner

Definition at line 190 of file util.php.

References sql_query().

Referenced by check_acl(), edit_item(), send_reminder(), and set_item_state().

                                          {

        switch($item) {

                case "user":
                        $p = array ( tables => "user,degree", 
                        columns => "user.*,degree.description AS degree_description",
                        cond => "user.id = $id AND degree.id = user.degree_id");
                        $ans = sql_query('select',$p, $db);

                        if (empty($ans)) {
                                user_error("database query failed" , 
                                E_USER_ERROR); 
                        }

                        $user = $ans[0];
                        
                        break;

                case "collection":

                        $p = array (tables => "collection",cond => "id = $id");
                        $ans = sql_query('select',$p, $db);

                        if (empty($ans)) {
                                user_error("database query failed" , 
                                E_USER_ERROR); 
                        }

                        $user = get_item_owner("user", $ans[0]['user_id'], $db);
                        break;

                case "email":

                        $p = array (tables => "email", cond => "id = $id");
                        $ans = sql_query('select',$p, $db);

                        $user = get_item_owner("document", 
                                        $ans[0]['document_id'], $db);
                        break;

                default:
                        $p = array (tables => "document",cond => "id = $id");
                        $ans = sql_query('select', $p, $db);

                        if (empty($ans)) {
                                user_error("database query failed" , 
                                E_USER_ERROR); 
                        }

                        $user = get_item_owner("collection", 
                                $ans[0]['collection_id'], $db);
                        break;
        }

        return $user;
}

Here is the call graph for this function:

get_new_expiry_date

(

)

Suggest an expiry date.

This function suggests a date in the future for expiry of a document collection (usually the end of next term).

Returns:

the suggested expiry date, in the format "YYYYMMDD"

Warning:

This function contains hard-coded dates. At our site, summer term ends in September, and winter term ends in March. Your mileage may vary.

Definition at line 298 of file util.php.

Referenced by edit_item(), extend_loan(), and set_item_state().

                               {

        # At TU Braunschweig, the semester ends on March and September, so 
        # we choose the beginning of the next semester as an expiration date.

        $t = getdate();

        $t['mday'] = 1; 

        if ($t['mon'] <= 2) { 
                $t['mon'] = 4; 
        } else if ($t['mon'] <= 7) { 
                $t['mon'] = 10; 
        } else {
                $t['mon'] = 4; 
                $t['year']++; 
        }

        $ans = sprintf("%04d%02d%02d", $t['year'] , $t['mon'] , $t['mday']);
        
        return $ans;

}

guess_mime_type

(

$

fn

)

guess a mime type from a file name

Parameters:

$fn

-- file name

Returns:

mime type

This function uses the $mime_types[] table defined in const.php.

Definition at line 506 of file util.php.

References $mime_types.

Referenced by view_item().

                              {
        global $mime_types;

        #normalize filename

        $fn = strtolower(basename(strtolower($fn)));

        $mime_type='application/octet-stream'; # catch-all

        foreach ($mime_types as $preg => $value ) {
                if (preg_match($preg, $fn) > 0) {
                        $mime_type = $value;
                        break;
                } 
        }
        
        return $mime_type;
}

send_email	(	$	smarty,
		$	template,
		$	kw,
		$	email_to
	)

Send an email, using a Smarty template as the body text.

Parameters:

	$smarty	-- a handle for the Smarty template engine
	$template	-- the file name for a template to be used as the email body
	$kw	-- an associative array. It's contents will be passed to the e-mail template via Smarty variables.
	$email_to	-- the recipient's email address

Definition at line 258 of file util.php.

Referenced by edit_item(), report(), send_reminder(), and set_item_state().

                                                         {

        global $_SESSION, $default_email_from, $default_email_subject;

        $email_from = $default_email_from;

        if (isset($_SESSION['user'])) {

                $u = $_SESSION['user'];
                $email_from =   $u['forename'] . " " . $u['surname'] .  
                                " <" . $u['email'] . ">";

        }

        foreach ($kw as $k => $v)  {
                $smarty->assign($k, $v);
        }

        $email_txt = $smarty->fetch($template); 


        foreach ($kw as $k => $v)  {
                $smarty->clear_assign($k, $v);
        }

        $headers = "From: $email_from\r\n\r\n";
        mail(  $email_to, $default_email_subject, $email_txt, $headers);
}

set_random_pw	(	$	uid,
		$	dblink
	)

Set a random password for a user account.

Parameters:

	$uid	-- user id that needs a new password
	$dblin	-- database handle

Returns:

the new password

The password consists of six random lower-case letters and digits.

Definition at line 454 of file util.php.

References sql_query().

Referenced by send_reminder(), and set_item_state().

                                      {
 
        $keychars = "abcdefghijklmnopqrstuvwxyz0123456789";
        $length = 6;

        $passwd = "";
        $max=strlen($keychars)-1;

        for ($i=0 ; $i<=$length ; $i++) {
                $passwd .= substr($keychars, rand(0, $max), 1);
        }

        $pw_crypt = "{SHA1}" . sha1($passwd);

        # set login / password

        $param = array (
                "tables" => "user" ,
                "data" => array ( "password" => $pw_crypt ), 
                 cond => "id = " . $uid,
        );


        sql_query('update', $param, $dblink);

        return $passwd;
}

Here is the call graph for this function:

smarty_init

(

)

initialize the Smarty template engine

Returns:

a Smarty handle

Definition at line 485 of file util.php.

Referenced by do_action(), do_login(), error_handler(), logout(), redirect(), show_collection(), show_help(), show_index(), and show_users().

                       {
        global $templates_compile_dir;

        $smarty =& new Smarty;
        $smarty->compile_check = true;
        #$smarty->debugging = true;

        # set paths
        $smarty->template_dir = "../templates";
        $smarty->compile_dir = $templates_compile_dir;
        $smarty->config_dir = "../configs";

        return $smarty;
}

---