completed rewrite of email preferences handling to schema based control mode

This commit is contained in:
angles 2001-12-17 18:37:59 +00:00
parent ee4ddf400f
commit 05c1889974

View File

@ -38,6 +38,12 @@
var $data = array();
/*! @var db */
var $db;
/*! @var debug_init_prefs */
var $debug_init_prefs = 0;
//var $debug_init_prefs = 1;
//var $debug_init_prefs = 2;
//var $debug_init_prefs = 3;
/**************************************************************************\
* Standard constructor for setting $this->account_id *
@ -297,18 +303,28 @@
unset($preferences_update);
}
}
/**************************************************************************\
* Email Preferences and Private Support Functions *
\**************************************************************************/
/*!
@function get_mailsvr_port
@abstract get_mailsvr_port
@function sub_get_mailsvr_port
@abstract Helper function for create_email_preferences, gets mail server port number.
@discussion This will generate the appropriate port number to access a
mail server of type pop3, pop3s, imap, imaps users value from
$phpgw_info['user']['preferences']['email']['mail_port'].
if that value is not set, it generates a default port for the given
$server_type
@param $prefs - any user preferences
mail server of type pop3, pop3s, imap, imaps users value from
$phpgw_info['user']['preferences']['email']['mail_port'].
if that value is not set, it generates a default port for the given $server_type.
Someday, this *MAY* be
(a) a se4rver wide admin setting, or
(b)user custom preference
Until then, simply set the port number based on the mail_server_type, thereof
ONLY call this function AFTER ['email']['mail_server_type'] has been set.
@param $prefs - user preferences array based on element ['email'][]
@author Angles
@access Private
*/
function get_mailsvr_port($prefs)
function sub_get_mailsvr_port($prefs)
{
/*// UNCOMMENT WHEN mail_port IS A REAL, USER SET OPTION
// first we try the port number supplied in preferences
@ -349,33 +365,66 @@
//}
return $port_number;
}
/*!
@function sub_default_userid
@abstract Helper function for create_email_preferences, gets default userid for email
@discussion This will generate the appropriate userid for accessing an email server.
In the absence of a custom ['email']['userid'], this function should be used to set it.
@param $accountid - as determined in and/or passed to "create_email_preferences"
@access Private
*/
function sub_default_userid($account_id='')
{
if ($GLOBALS['phpgw_info']['server']['mail_login_type'] == 'vmailmgr')
{
$prefs_email_userid = $GLOBALS['phpgw']->accounts->id2name($account_id)
. '@' . $GLOBALS['phpgw_info']['server']['mail_suffix'];
}
else
{
$prefs_email_userid = $GLOBALS['phpgw']->accounts->id2name($account_id);
}
return $prefs_email_userid;
}
/*!
@function sub_default_address
@abstract Helper function for create_email_preferences, gets default "From:" email address
@discussion This will generate the appropriate email address used as the "From:"
email address when the user sends email, the localpert@domain part. The "personal"
part is generated elsewhere.
In the absence of a custom ['email']['address'], this function should be used to set it.
@param $accountid - as determined in and/or passed to "create_email_preferences"
@access Private
*/
function sub_default_address($account_id='')
{
$prefs_email_address = $GLOBALS['phpgw']->accounts->id2name($account_id)
. '@' . $GLOBALS['phpgw_info']['server']['mail_suffix'];
return $prefs_email_address;
}
/*!
@function create_email_preferences
@abstract create email preferences
@param $account_id -optional defaults to : phpgw_info['user']['account_id']
@discussion
(old) This fills the global $phpgw_info array with the required email preferences for this user
(old was changed: new) fills a local copy of ['email'][] prefs array which is then returned to the calling
proc, which the calling proc generally tacks onto the global $phpgw_info array as such:
@param $account_id -optional defaults to : get_account_id()
@discussion fills a local copy of ['email'][] prefs array which is then returned to the calling
function, which the calling function generally tacks onto the $GLOBALS['phpgw_info'] array as such:
$GLOBALS['phpgw_info']['user']['preferences'] = $GLOBALS['phpgw']->preferences->create_email_preferences();
which fills an array based at:
$GLOBALS['phpgw_info']['user']['preferences']['email']
Most times, this function used the existence, or lack thereof, of certain custom preferences read from the
repository as an indication of whether to use server defaults or that specified user custom preference.
This means that generally there is not a "pref not set" value, instead an unspecified preference generally
does not exist in the repository. This can be an issue when, for example, a new user first uses then email
app, if that user never went to the prefs page and specifically set "use sent folder" then, perhaps unknown
to that user, the users sent mail is NOT being sent to a "sent" folder.
ISSUE: unset = no preference. However, when reading the preferences for the FIRST time ever for a user,
and a preference "use sent folder" does not exist (is not set), we do not know if (a) the user purposely does NOT
want to use the sent folder, or (b) the user has never actually been to the preferences page, and does not know
that "use sent folder" is an option that is not enabled.
$GLOBALS['phpgw_info']['user']['preferences']['email'][prefs_are_elements_here]
Reading the raw preference DB data and comparing to the email preference schema defined in
/email/class.bopreferences.inc.php (see discussion there and below) to create default preference values
for the in the ['email'][] pref data array in cases where the user has not supplied
a preference value for any particular preference item available to the user.
@access Public
*/
function create_email_preferences($accountid='')
{
$default_trash_folder = 'Trash';
$default_sent_folder = 'Sent';
if ($this->debug_init_prefs > 0) { echo 'class.preferences: create_email_preferences: ENTERING<br>'; }
// we may need function "html_quotes_decode" from the mail_msg class
$email_base = CreateObject("email.mail_msg");
$account_id = get_account_id($accountid);
// If the current user is not the request user, grab the preferences
@ -401,51 +450,295 @@
{
$prefs = $this->data;
}
if ($this->debug_init_prefs > 0) { echo 'class.preferences: create_email_preferences: raw $this->data dump<pre>'; print_r($this->data); echo '</pre>'; }
// Add default preferences info
if (!isset($prefs['email']['userid']))
{
if ($GLOBALS['phpgw_info']['server']['mail_login_type'] == 'vmailmgr')
{
$prefs['email']['userid'] = $GLOBALS['phpgw']->accounts->id2name($account_id)
. '@' . $GLOBALS['phpgw_info']['server']['mail_suffix'];
}
else
{
$prefs['email']['userid'] = $GLOBALS['phpgw']->accounts->id2name($account_id);
}
}
// Set Server Mail Type if not defined
// = = = = NOT-SIMPLE PREFS = = = =
// Default Preferences info that is:
// (a) not controlled by email prefs itself (mostly api and/or server level stuff)
// (b) too complicated to be described in the email prefs data array instructions
// --- [server][mail_server_type] ---
// Set API Level Server Mail Type if not defined
// if for some reason the API didnot have a mail server type set during initialization
if (empty($GLOBALS['phpgw_info']['server']['mail_server_type']))
{
$GLOBALS['phpgw_info']['server']['mail_server_type'] = 'imap';
}
if (!isset($prefs['email']['address']))
{
$prefs['email']['address'] = $GLOBALS['phpgw']->accounts->id2name($account_id)
. '@' . $GLOBALS['phpgw_info']['server']['mail_suffix'];
}
if (!isset($prefs['email']['mail_server']))
{
$prefs['email']['mail_server'] = $GLOBALS['phpgw_info']['server']['mail_server'];
}
if (!isset($prefs['email']['mail_server_type']))
{
$prefs['email']['mail_server_type'] = $GLOBALS['phpgw_info']['server']['mail_server_type'];
}
if (!isset($prefs['email']['imap_server_type']))
{
$prefs['email']['imap_server_type'] = $GLOBALS['phpgw_info']['server']['imap_server_type'];
}
// --- [server][mail_folder] ---
// ==== UWash Mail Folder Location used to be "mail", now it's changeable, but keep the
// ==== default to "mail" so upgrades happen transparently
// --- TEMP MAKE DEFAULT UWASH MAIL FOLDER ~/mail (a.k.a. $HOME/mail)
$GLOBALS['phpgw_info']['server']['mail_folder'] = 'mail';
// --- DELETE THE ABOVE WHEN THIS OPTION GETS INTO THE SYSTEM SETUP
// pick up custom "mail_folder" if it exists (used for UWash and UWash Maildor servers)
// pick up custom "mail_folder" if it exists (used for UWash and UWash Maildir servers)
// else use the system default (which we temporarily hard coded to "mail" just above here)
//--- [email][newsmode] ---
// == Orphan == currently NOT USED
// This is going to be used to switch to the nntp class
if ((isset($GLOBALS['phpgw_info']['flags']['newsmode'])
&& $GLOBALS['phpgw_info']['flags']['newsmode']))
{
$prefs['email']['mail_server_type'] = 'nntp';
}
//--- [email][mail_port] ---
// These sets the mail_port server variable
// someday (not currently) this may be a site-wide property set during site setup
// additionally, someday (not currently) the user may be able to override this with
// a custom email preference. Currently, we simply use standard port numbers
// for the service in question.
$prefs['email']['mail_port'] = $this->sub_get_mailsvr_port($prefs);
// = = = = SIMPLER PREFS = = = =
// Default Preferences info that is articulated in the email prefs schema array itself
// such email prefs schema array is described and established in /email/class.bopreferences
// by function "init_available_prefs", see the discussion there.
// --- create the objectified /email/class.bopreferences.inc.php ---
$bo_mail_prefs = CreateObject('email.bopreferences');
// --- bo_mail_prefs->init_available_prefs() ---
// this fills object_email_bopreferences->std_prefs and ->cust_prefs
// we will initialize the users preferences according to the rules and instructions
// embodied in those prefs arrays, applying those rules to the unprocessed
// data read from the preferences DB. By taking the raw data and applying those rules,
// we will construct valid and known email preference data for this user.
$bo_mail_prefs->init_available_prefs();
// --- combine the two array (std and cust) for 1 pass handling ---
// when this preference DB was submitted and saved, it was hopefully so well structured
// that we can simply combine the two arrays, std_prefs and cust_prefs, and do a one
// pass analysis and preparation of this users preferences.
$avail_pref_array = $bo_mail_prefs->std_prefs;
$c_cust_prefs = count($bo_mail_prefs->cust_prefs);
for($i=0;$i<$c_cust_prefs;$i++)
{
// add each custom prefs to the std prefs array
$next_idx = count($avail_pref_array);
$avail_pref_array[$next_idx] = $bo_mail_prefs->cust_prefs[$i];
}
if ($this->debug_init_prefs > 1) { echo 'class.preferences: create_email_preferences: std AND cust arrays combined:<pre>'; print_r($avail_pref_array); echo '</pre>'; }
// --- make the schema-based pref data for this user ---
// user defined values and/or user specified custom email prefs are read from the
// prefs DB with mininal manipulation of the data. Currently the only change to
// users raw data is related to reversing the encoding of "database un-friendly" chars
// which itself may become unnecessary if and when the database handlers can reliably
// take care of this for us. Of course, password data requires special decoding,
// but the password in the array [email][paswd] should be left in encrypted form
// and only decrypted seperately when used to login in to an email server.
// --- generating a default value if necessary ---
// in the absence of a user defined custom email preference for a particular item, we can
// determine the desired default value for that pref as such:
// $this_avail_pref['init_default'] is a comma seperated seperated string which should
// be exploded into an array containing 2 elements that are:
// exploded[0] : an description of how to handle the next string element to get a default value.
// Possible "instructional tokens" for exploded[0] (called $set_proc[0] below) are:
// string
// set_or_not
// function
// init_no_fill
// varEVAL
// tells you how to handle the string in exploded[1] (called $set_proc[1] below) to get a valid
// default value for a particular preference if one is needed (i.e. if no user custom
// email preference exists that should override that default value, in which case we
// do not even need to obtain such a default value as described in ['init_default'] anyway).
// --- loop thru $avail_pref_array and process each pref item ---
$c_prefs = count($avail_pref_array);
for($i=0;$i<$c_prefs;$i++)
{
$this_avail_pref = $avail_pref_array[$i];
if ($this->debug_init_prefs > 1) { echo 'class.preferences: create_email_preferences: value from DB for $prefs[email]['.$this_avail_pref['id'].'] = ['.$prefs['email'][$this_avail_pref['id']].']<br>'; }
if ($this->debug_init_prefs > 2) { echo 'class.preferences: create_email_preferences: std/cust_prefs $this_avail_pref['.$i.'] dump:<pre>'; print_r($this_avail_pref); echo "</pre>\r\n"; }
// --- is there a value in the DB for this preference item ---
// if the prefs DB has no value for this defined available preference, we must make one.
// This occurs if (a) this is user's first login, or (b) this is a custom pref which the user
// has not overriden, do a default (non-custom) value is needed.
if (!isset($prefs['email'][$this_avail_pref['id']]))
{
// now we are analizing an individual pref that is available to the user
// AND the user had no existing value in the prefs DB for this.
// --- get instructions on how to generate a default value ---
$set_proc = explode(',', $this_avail_pref['init_default']);
if ($this->debug_init_prefs > 1) { echo ' * set_proc=['.serialize($set_proc).']<br>'; }
// --- use "instructional token" in $set_proc[0] to take appropriate action ---
// STRING
if ($set_proc[0] == 'string')
{
// means this pref item's value type is string
// which defined string default value is in $set_proc[1]
if ($this->debug_init_prefs > 2) { echo ' * handle "string" set_proc: '.serialize($set_proc).'<br>'; }
if (trim($set_proc[1]) == '')
{
// this happens when $this_avail_pref['init_default'] = "string, "
$this_string = '';
}
else
{
$this_string = $set_proc[1];
}
$prefs['email'][$this_avail_pref['id']] = $this_string;
}
// SET_OR_NOT
elseif ($set_proc[0] == 'set_or_not')
{
// typical with boolean options, True = "set/exists" and False = unset
if ($this->debug_init_prefs > 2) { echo ' * handle "set_or_not" set_proc: '.serialize($set_proc).'<br>'; }
if ($set_proc[1] == 'not_set')
{
// leave it NOT SET
}
else
{
// opposite of boolean not_set = string "True" which simply sets a
// value it exists in the users session [email][] preference array
$prefs['email'][$this_avail_pref['id']] = 'True';
}
}
// FUNCTION
elseif ($set_proc[0] == 'function')
{
// string in $set_proc[1] should be "eval"uated as code, calling a function
// which will give us a default value to put in users session [email][] prefs array
if ($this->debug_init_prefs > 2) { echo ' * handle "function" set_proc: '.serialize($set_proc).'<br>'; }
$evaled = '';
//eval('$evaled = $this->'.$set_proc[1].'('.$account_id.');');
$code = '$evaled = $this->'.$set_proc[1].'('.$account_id.');';
if ($this->debug_init_prefs > 2) { echo ' * $code: '.$code.'<br>'; }
eval($code);
//$code = '$evaled = '.$set_proc[1];
//if ($this->debug_init_prefs > 1) { echo ' * $code: '.$code.'<br>'; }
//eval($code);
if ($this->debug_init_prefs > 2) { echo ' * $evaled: '.$evaled.'<br>'; }
$prefs['email'][$this_avail_pref['id']] = $evaled;
}
// INIT_NO_FILL
elseif ($set_proc[0] == 'init_no_fill')
{
// we have an available preference item that we may NOT fill with a default
// value. Only the user may supply a value for this pref item.
if ($this->debug_init_prefs > 1) { echo ' * handle "init_no_fill" set_proc: '.serialize($set_proc).'<br>'; }
// we are FORBADE from filling this at this time!
}
// varEVAL
elseif ($set_proc[0] == 'varEVAL')
{
// similar to "function" but used for array references, the string in $set_proc[1]
// represents code which typically is an array referencing a system/api property
if ($this->debug_init_prefs > 2) { echo ' * handle "GLOBALS" set_proc: '.serialize($set_proc).'<br>'; }
$evaled = '';
$code = '$evaled = '.$set_proc[1];
if ($this->debug_init_prefs > 2) { echo ' * $code: '.$code.'<br>'; }
eval($code);
if ($this->debug_init_prefs > 2) { echo ' * $evaled: '.$evaled.'<br>'; }
$prefs['email'][$this_avail_pref['id']] = $evaled;
}
else
{
// error, no instructions on how to handle this element's default value creation
echo 'class.preferences: create_email_preferences: set_proc ERROR: '.serialize($set_proc).'<br>';
}
}
else
{
// we have a value in the database, do we need to prepare it in any way?
// (the following discussion is unconfirmed:)
// DO NOT ALTER the data in the prefs array!!!! or the next time we call
// save_repository withOUT undoing what we might do here, the
// prefs will permenantly LOOSE the very thing(s) we are un-doing
/// here until the next OFFICIAL submit email prefs function, where it
// will again get this preparation before being written to the database.
// NOTE: if database de-fanging is eventually handled deeper in the
// preferences class, then the following code would become depreciated
// and should be removed in that case.
if (($this_avail_pref['type'] == 'user_string')
&& (stristr($this_avail_pref['write_props'], 'no_db_defang') == False))
{
// this value was "de-fanged" before putting it in the database
// undo that defanging now
$db_unfriendly = $email_base->html_quotes_decode($prefs['email'][$this_avail_pref['id']]);
$prefs['email'][$this_avail_pref['id']] = $db_unfriendly;
}
}
}
// users preferences are now established to known structured values...
// SANITY CHECK
// --- [email][use_trash_folder] ---
// --- [email][use_sent_folder] ---
// is it possible to use Trash and Sent folders - i.e. using IMAP server
// if not - force settings to false
if (stristr($prefs['email']['mail_server_type'], 'imap') == False)
{
if (isset($prefs['email']['use_trash_folder']))
{
unset($prefs['email']['use_trash_folder']);
}
if (isset($prefs['email']['use_sent_folder']))
{
unset($prefs['email']['use_sent_folder']);
}
}
// DEBUG : force some settings to test stuff
//$prefs['email']['p_persistent'] = 'True';
if ($this->debug_init_prefs > 1) { echo 'class.preferences: create_email_preferences: $prefs[email]<pre>'; print_r($prefs['email']) ; echo '</pre>'; }
if ($this->debug_init_prefs > 0) { echo 'class.preferences: create_email_preferences: LEAVING<br>'; }
return $prefs;
}
/*
// ==== DEPRECIATED - ARCHIVAL CODE ====
// used to be part of function this->create_email_preferences()
// = = = = SIMPLER PREFS = = = =
// Default Preferences info that is:
// described in the email prefs array itself
$default_trash_folder = 'Trash';
$default_sent_folder = 'Sent';
// --- userid ---
if (!isset($prefs['email']['userid']))
{
$prefs['email']['userid'] = $this->sub_default_userid($accountid);
}
// --- address ---
if (!isset($prefs['email']['address']))
{
$prefs['email']['address'] = $this->sub_default_address($accountid);
}
// --- mail_server ---
if (!isset($prefs['email']['mail_server']))
{
$prefs['email']['mail_server'] = $GLOBALS['phpgw_info']['server']['mail_server'];
}
// --- mail_server_type ---
if (!isset($prefs['email']['mail_server_type']))
{
$prefs['email']['mail_server_type'] = $GLOBALS['phpgw_info']['server']['mail_server_type'];
}
// --- imap_server_type ---
if (!isset($prefs['email']['imap_server_type']))
{
$prefs['email']['imap_server_type'] = $GLOBALS['phpgw_info']['server']['imap_server_type'];
}
// --- mail_folder ---
// because of the way this option works, an empty string IS ACTUALLY a valid value
// which represents the $HOME/* as the UWash mail files location
// THERFOR we must check the "Use_custom_setting" option to help us figure out what to do
@ -474,17 +767,9 @@
$prefs['email']['mail_folder'] = '';
}
}
// This is going to be used to switch to the nntp class
if ((isset($GLOBALS['phpgw_info']['flags']['newsmode'])
&& $GLOBALS['phpgw_info']['flags']['newsmode']))
{
$prefs['email']['mail_server_type'] = 'nntp';
}
// These sets the mail_port server variable
$prefs['email']['mail_port'] = $this->get_mailsvr_port($prefs);
// --- use_trash_folder ---
// --- trash_folder_name ---
// if the option to use the Trash folder is ON, make sure a proper name is specified
if (isset($prefs['email']['use_trash_folder']))
{
@ -494,7 +779,9 @@
$prefs['email']['trash_folder_name'] = $default_trash_folder;
}
}
// --- use_sent_folder ---
// --- sent_folder_name ---
// if the option to use the sent folder is ON, make sure a proper name is specified
if (isset($prefs['email']['use_sent_folder']))
{
@ -505,36 +792,51 @@
}
}
// SANITY CHECK - is it possible to use Trash and Sent folders - i.e. using IMAP server
// if not - force settings to false
if (($prefs['email']['mail_server_type'] != 'imap')
&& ($prefs['email']['mail_server_type'] != 'imaps'))
{
if (isset($prefs['email']['use_sent_folder']))
{
unset($prefs['email']['use_sent_folder']);
}
if (isset($prefs['email']['use_trash_folder']))
{
unset($prefs['email']['use_trash_folder']);
}
}
// --- layout ---
// Layout Template Preference
// layout 1 = default ; others are prefs
if (!isset($prefs['email']['layout']))
{
$prefs['email']['layout'] = 1;
}
// force seeting here to test stuff
//// --- font_size_offset ---
//// Email Index Page Font Size Preference
//// layout 1 = default ; others are prefs
//if (!isset($prefs['email']['font_size_offset']))
//{
// $prefs['email']['font_size_offset'] = 'normal';
//}
// SANITY CHECK
// --- use_trash_folder ---
// --- use_sent_folder ---
// is it possible to use Trash and Sent folders - i.e. using IMAP server
// if not - force settings to false
if (stristr($prefs['email']['mail_server_type'], 'imap') == False)
{
if (isset($prefs['email']['use_trash_folder']))
{
unset($prefs['email']['use_trash_folder']);
}
if (isset($prefs['email']['use_sent_folder']))
{
unset($prefs['email']['use_sent_folder']);
}
}
// DEBUG : force some settings to test stuff
//$prefs['email']['layout'] = 1;
//$prefs['email']['layout'] = 2;
//$prefs['email']['font_size_offset'] = (-1);
// DEBUG
//echo "<br>prefs['email']: <br>"
// .'<pre>'.serialize($prefs['email']) .'</pre><br>';
return $prefs;
}
*/
} /* end of preferences class */
?>