From 37b11ab04d0a07b8c1c846a6494442aad7a43330 Mon Sep 17 00:00:00 2001 From: pdontthink Date: Sat, 5 Jan 2008 06:05:40 +0000 Subject: [PATCH] Clean up variable naming and function docs. git-svn-id: https://svn.code.sf.net/p/squirrelmail/code/trunk/squirrelmail@12851 7612ce4b-ef26-0410-bec9-ea0150e637f0 --- functions/db_prefs.php | 71 +++++++++++++++++++++---------- functions/file_prefs.php | 91 ++++++++++++++++++++++++++-------------- 2 files changed, 108 insertions(+), 54 deletions(-) diff --git a/functions/db_prefs.php b/functions/db_prefs.php index f11d49fe..9756fc88 100644 --- a/functions/db_prefs.php +++ b/functions/db_prefs.php @@ -84,9 +84,11 @@ function cachePrefValues($username) { /** * Class used to handle connections to prefs database and operations with preferences + * * @package squirrelmail * @subpackage prefs * @since 1.1.3 + * */ class dbPrefs { /** @@ -94,16 +96,19 @@ class dbPrefs { * @var string */ var $table = 'userprefs'; + /** * Field used to store owner of preference * @var string */ var $user_field = 'user'; + /** * Field used to store preference name * @var string */ var $key_field = 'prefkey'; + /** * Field used to store preference value * @var string @@ -115,11 +120,13 @@ class dbPrefs { * @var object */ var $dbh = NULL; + /** * Error messages * @var string */ var $error = NULL; + /** * Database type (SMDB_* constants) * Is used in setKey(). @@ -140,12 +147,14 @@ class dbPrefs { * @since 1.5.1 */ var $user_size = 128; + /** * Preference key field size * @var integer * @since 1.5.1 */ var $key_size = 64; + /** * Preference value field size * @var integer @@ -153,9 +162,13 @@ class dbPrefs { */ var $val_size = 65536; + + /** * initialize DB connection object + * * @return boolean true, if object is initialized + * */ function open() { global $prefs_dsn, $prefs_table; @@ -216,7 +229,9 @@ class dbPrefs { /** * Function used to handle database connection errors + * * @param object PEAR Error object + * */ function failQuery($res = NULL) { if($res == NULL) { @@ -231,10 +246,13 @@ class dbPrefs { /** * Get user's prefs setting + * * @param string $user user name * @param string $key preference name * @param mixed $default (since 1.2.5) default value + * * @return mixed preference value + * */ function getKey($user, $key, $default = '') { global $prefs_cache; @@ -254,9 +272,12 @@ class dbPrefs { /** * Delete user's prefs setting + * * @param string $user user name - * @param string $key preference name + * @param string $key preference name + * * @return boolean + * */ function deleteKey($user, $key) { global $prefs_cache; @@ -283,10 +304,13 @@ class dbPrefs { /** * Set user's preference - * @param string $user user name - * @param string $key preference name - * @param mixed $value preference value + * + * @param string $user user name + * @param string $key preference name + * @param mixed $value preference value + * * @return boolean + * */ function setKey($user, $key, $value) { if (!$this->open()) { @@ -407,8 +431,11 @@ class dbPrefs { /** * Fill preference cache array + * * @param string $user user name + * * @since 1.2.3 + * */ function fillPrefsCache($user) { global $prefs_cache; @@ -439,10 +466,10 @@ class dbPrefs { /** - * returns the value for the pref $string + * Returns the value for the requested preference * @ignore */ -function getPref($data_dir, $username, $string, $default = '') { +function getPref($data_dir, $username, $pref_name, $default = '') { $db = new dbPrefs; if(isset($db->error)) { printf( _("Preference database error (%s). Exiting abnormally"), @@ -450,24 +477,24 @@ function getPref($data_dir, $username, $string, $default = '') { exit; } - return $db->getKey($username, $string, $default); + return $db->getKey($username, $pref_name, $default); } /** - * Remove the pref $string + * Remove the desired preference setting ($pref_name) * @ignore */ -function removePref($data_dir, $username, $string) { +function removePref($data_dir, $username, $pref_name) { global $prefs_cache; $db = new dbPrefs; if(isset($db->error)) { $db->failQuery(); } - $db->deleteKey($username, $string); + $db->deleteKey($username, $pref_name); - if (isset($prefs_cache[$string])) { - unset($prefs_cache[$string]); + if (isset($prefs_cache[$pref_name])) { + unset($prefs_cache[$pref_name]); } sqsession_register($prefs_cache , 'prefs_cache'); @@ -475,18 +502,18 @@ function removePref($data_dir, $username, $string) { } /** - * sets the pref, $string, to $set_to + * Sets the desired preference setting ($pref_name) to whatever is in $value * @ignore */ -function setPref($data_dir, $username, $string, $set_to) { +function setPref($data_dir, $username, $pref_name, $value) { global $prefs_cache; - if (isset($prefs_cache[$string]) && ($prefs_cache[$string] == $set_to)) { + if (isset($prefs_cache[$pref_name]) && ($prefs_cache[$pref_name] == $value)) { return; } - if ($set_to === '') { - removePref($data_dir, $username, $string); + if ($value === '') { + removePref($data_dir, $username, $pref_name); return; } @@ -495,11 +522,11 @@ function setPref($data_dir, $username, $string, $set_to) { $db->failQuery(); } - $db->setKey($username, $string, $set_to); - $prefs_cache[$string] = $set_to; + $db->setKey($username, $pref_name, $value); + $prefs_cache[$pref_name] = $value; assert_options(ASSERT_ACTIVE, 1); assert_options(ASSERT_BAIL, 1); - assert ('$set_to == $prefs_cache[$string]'); + assert ('$value == $prefs_cache[$pref_name]'); sqsession_register($prefs_cache , 'prefs_cache'); return; } @@ -519,13 +546,13 @@ function checkForPrefs($data_dir, $username) { * Writes the Signature * @ignore */ -function setSig($data_dir, $username, $number, $string) { +function setSig($data_dir, $username, $number, $value) { if ($number == "g") { $key = '___signature___'; } else { $key = sprintf('___sig%s___', $number); } - setPref($data_dir, $username, $key, $string); + setPref($data_dir, $username, $key, $value); return; } diff --git a/functions/file_prefs.php b/functions/file_prefs.php index 028541f2..fb4f706d 100644 --- a/functions/file_prefs.php +++ b/functions/file_prefs.php @@ -16,9 +16,12 @@ /** * Check the preferences into the session cache. + * * @param string $data_dir * @param string $username + * * @since 1.1.3 + * */ function cachePrefValues($data_dir, $username) { global $prefs_are_cached, $prefs_cache; @@ -70,12 +73,15 @@ function cachePrefValues($data_dir, $username) { if ($equalsAt > 0) { $key = substr($pref, 0, $equalsAt); $value = substr($pref, $equalsAt + 1); + +//FIXME: this code is not in db_prefs.php that I can see /* this is to 'rescue' old-style highlighting rules. */ if (substr($key, 0, 9) == 'highlight') { $key = 'highlight' . $highlight_num; $highlight_num ++; } +//FIXME: this code is not in db_prefs.php that I can see if ($value != '') { $prefs_cache[$key] = $value; } @@ -90,23 +96,26 @@ function cachePrefValues($data_dir, $username) { } /** - * Return the value for the preference given by $string. - * @param string $data_dir data directory - * @param string $username user name - * @param string $string preference name - * @param string $default (since 1.2.0) default preference value + * Return the value for the desired preference. + * + * @param string $data_dir data directory + * @param string $username user name + * @param string $pref_name preference name + * @param string $default (since 1.2.0) default preference value + * * @return mixed + * */ -function getPref($data_dir, $username, $string, $default = '') { +function getPref($data_dir, $username, $pref_name, $default = '') { global $prefs_cache; - $result = do_hook('get_pref_override', $temp=array(&$username, &$string)); + $result = do_hook('get_pref_override', $temp=array(&$username, &$pref_name)); if (!$result) { cachePrefValues($data_dir, $username); - if (isset($prefs_cache[$string])) { - $result = $prefs_cache[$string]; + if (isset($prefs_cache[$pref_name])) { + $result = $prefs_cache[$pref_name]; } else { - $result = do_hook('get_pref', $temp=array(&$username, &$string)); + $result = do_hook('get_pref', $temp=array(&$username, &$pref_name)); if (!$result) { $result = $default; } @@ -117,9 +126,12 @@ function getPref($data_dir, $username, $string, $default = '') { /** * Save the preferences for this user. + * * @param string $data_dir data directory * @param string $username user name + * * @since 1.1.3 + * */ function savePrefValues($data_dir, $username) { global $prefs_cache; @@ -152,52 +164,61 @@ function savePrefValues($data_dir, $username) { /** * Remove a preference for the current user. - * @param string $data_dir data directory - * @param string $username user name - * @param string $string preference name + * + * @param string $data_dir data directory + * @param string $username user name + * @param string $pref_name preference name + * */ -function removePref($data_dir, $username, $string) { +function removePref($data_dir, $username, $pref_name) { global $prefs_cache; cachePrefValues($data_dir, $username); - if (isset($prefs_cache[$string])) { - unset($prefs_cache[$string]); + if (isset($prefs_cache[$pref_name])) { + unset($prefs_cache[$pref_name]); } savePrefValues($data_dir, $username); } /** - * Set a there preference $string to $value. - * @param string $data_dir data directory - * @param string $username user name - * @param string $string preference name - * @param mixed $value preference value + * Set the desired preference setting ($pref_name) + * to whatever is in $value. + * + * @param string $data_dir data directory + * @param string $username user name + * @param string $pref_name preference name + * @param mixed $value preference value + * */ -function setPref($data_dir, $username, $string, $value) { +function setPref($data_dir, $username, $pref_name, $value) { global $prefs_cache; cachePrefValues($data_dir, $username); - if (isset($prefs_cache[$string]) && ($prefs_cache[$string] == $value)) { + if (isset($prefs_cache[$pref_name]) && ($prefs_cache[$pref_name] == $value)) { return; } if ($value === '') { - removePref($data_dir, $username, $string); + removePref($data_dir, $username, $pref_name); return; } - $prefs_cache[$string] = $value; + $prefs_cache[$pref_name] = $value; savePrefValues($data_dir, $username); } /** * Check for a preferences file. If one can not be found, create it. + * * @param string $data_dir data directory * @param string $username user name * @param string $filename (since 1.2.0) preference file name. - * detects file name, if set to empty string. + * (OPTIONAL; default is an empty string, + * in which case the file name is + * automatically detected) + * */ function checkForPrefs($data_dir, $username, $filename = '') { /* First, make sure we have the filename. */ @@ -251,11 +272,14 @@ function checkForPrefs($data_dir, $username, $filename = '') { /** * Write the User Signature. + * * @param string $data_dir data directory * @param string $username user name - * @param integer $number (since 1.2.5) identity number. - * parameter was used for signature text before 1.2.5. - * @param string $value (since 1.2.5) signature text + * @param integer $number (since 1.2.5) identity number. + * (before 1.2.5., this parameter + * was used for the signature value) + * @param string $value (since 1.2.5) signature value + * */ function setSig($data_dir, $username, $number, $value) { // Limit signature size to 64KB (database BLOB limit) @@ -285,10 +309,13 @@ function setSig($data_dir, $username, $number, $value) { /** * Get the signature. - * @param string $data_dir data directory - * @param string $username user name - * @param integer $number (since 1.2.5) identity number + * + * @param string $data_dir data directory + * @param string $username user name + * @param integer $number (since 1.2.5) identity number + * * @return string signature + * */ function getSig($data_dir, $username, $number) { $filename = getHashedFile($username, $data_dir, "$username.si$number"); -- 2.25.1