Massive update to plugin system architecture. Please test! Not all core plugins are tested yet, please point out issues that need to be fixed. Please see http://marc.theaimsgroup.com/?t=116282394000001&r=1&w=2

class/error.class.php

@@ -177,7 +177,7 @@ class ErrorHandler {
                         }
                         if ($aError['category'] & SQM_ERROR_PLUGIN) {
                             $aErrorCategory[] = 'PLUGIN';
-                            do_hook_function('error_handler_plugin',$aError);
+                            do_hook('error_handler_plugin', $aError);
                             // plugin related error handling inside
                         }
                         //if ($aError['category'] & SQM_ERROR_X) {

class/template/Template.class.php

@@ -1337,7 +1337,7 @@ FIXME: We could make the incoming array more complex so it can
 
             $aPluginOutput = array();
             $aPluginOutput = concat_hook_function('template_construct_' . $file,
-                                                  array($aPluginOutput, $this));
+                                                  $temp=array(&$aPluginOutput, &$this));
             $this->assign('plugin_output', $aPluginOutput);
 
             //$output = $this->apply_template($template);
@@ -1349,7 +1349,7 @@ FIXME: We could make the incoming array more complex so it can
             // using this hook will probably be rejected by the
             // SquirrelMail team.
             //
-            $output = filter_hook_function('template_output', $output);
+            do_hook('template_output', $output);
 
             return $output;
 

functions/addressbook.php

@@ -125,10 +125,12 @@ function addressbook_init($showerr = true, $onlylocal = false) {
      * Since 1.5.2 hook sends third ($onlylocal) argument to address book
      * plugins in order to allow detection of local address book init.
      * @since 1.5.1 and 1.4.5
+     * Since 1.5.2, the plugin arguments are passed inside an array
+     * and by reference, so plugins hooking in here need to accept arguments
+     * in an array and change those values as needed instead of returning
+     * the changed values.
      */
-    $hookReturn = do_hook('abook_init', $abook, $r, $onlylocal);
-    $abook = $hookReturn[1];
-    $r = $hookReturn[2];
+    do_hook('abook_init', $temp=array(&$abook, &$r, &$onlylocal));
     if (!$r && $showerr) {
         if ($abook_init_error!='') $abook_init_error.="\n";
         $abook_init_error.=_("Error initializing other address books.") . "\n" . $abook->error;
@@ -441,7 +443,8 @@ class AddressBook {
               * NB: Because the backend files are included from within this function they DO NOT have access to
               * vars in the global scope. This function is the global scope for the included backend !!!
               */
-            $aBackend = do_hook('abook_add_class');
+            global $null;
+            $aBackend = do_hook('abook_add_class', $null);
             if (isset($aBackend) && is_array($aBackend) && isset($aBackend[$backend])) {
                 require_once($aBackend[$backend]);
             } else {

functions/attachment_common.php

@@ -125,23 +125,23 @@ function attachment_common_link_text(&$Args) {
     /* If there is a text attachment, we would like to create a "View" button
        that links to the text attachment viewer.
 
-       $Args[1] = the array of actions
+       $Args[0] = the array of actions
 
        Use the name of this file for adding an action
-       $Args[1]['attachment_common'] = Array for href and text
+       $Args[0]['attachment_common'] = Array for href and text
 
-       $Args[1]['attachment_common']['text'] = What is displayed
-       $Args[1]['attachment_common']['href'] = Where it links to */
+       $Args[0]['attachment_common']['text'] = What is displayed
+       $Args[0]['attachment_common']['href'] = Where it links to */
     sqgetGlobalVar('QUERY_STRING', $QUERY_STRING, SQ_SERVER);
 
     // if htmlspecialchars() breaks something - find other way to encode & in url.
-    $Args[1]['attachment_common']['href'] = $base_uri  . 'src/view_text.php?'. htmlspecialchars($QUERY_STRING);
-    $Args[1]['attachment_common']['href'] =
-          set_url_var($Args[1]['attachment_common']['href'],
-          'ent_id',$Args[5]);
+    $Args[0]['attachment_common']['href'] = $base_uri  . 'src/view_text.php?'. htmlspecialchars($QUERY_STRING);
+    $Args[0]['attachment_common']['href'] =
+          set_url_var($Args[0]['attachment_common']['href'],
+          'ent_id',$Args[4]);
 
     /* The link that we created needs a name. */
-    $Args[1]['attachment_common']['text'] = _("View");
+    $Args[0]['attachment_common']['text'] = _("View");
 
     /* Each attachment has a filename on the left, which is a link.
        Where that link points to can be changed.  Just in case the link above
@@ -151,7 +151,7 @@ function attachment_common_link_text(&$Args) {
        This is a lot better in the image links, since the defaultLink will just
        download the image, but the one that we set it to will format the page
        to have an image tag in the center (looking a lot like this text viewer) */
-    $Args[6] = $Args[1]['attachment_common']['href'];
+    $Args[5] = $Args[1]['attachment_common']['href'];
 }
 
 /**
@@ -161,13 +161,13 @@ function attachment_common_link_text(&$Args) {
  */
 function attachment_common_link_message(&$Args) {
     global $base_uri;
-    $Args[1]['attachment_common']['href'] = $base_uri  . 'src/read_body.php?startMessage=' .
-        $Args[2] . '&passed_id=' . $Args[3] . '&mailbox=' . $Args[4] .
-        '&passed_ent_id=' . $Args[5] . '&override_type0=message&override_type1=rfc822';
+    $Args[0]['attachment_common']['href'] = $base_uri  . 'src/read_body.php?startMessage=' .
+        $Args[1] . '&passed_id=' . $Args[2] . '&mailbox=' . $Args[3] .
+        '&passed_ent_id=' . $Args[4] . '&override_type0=message&override_type1=rfc822';
 
-    $Args[1]['attachment_common']['text'] = _("View");
+    $Args[0]['attachment_common']['text'] = _("View");
 
-    $Args[6] = $Args[1]['attachment_common']['href'];
+    $Args[5] = $Args[0]['attachment_common']['href'];
 }
 
 /**
@@ -179,17 +179,17 @@ function attachment_common_link_html(&$Args) {
     global $base_uri;
     sqgetGlobalVar('QUERY_STRING', $QUERY_STRING, SQ_SERVER);
 
-    $Args[1]['attachment_common']['href'] = $base_uri  . 'src/view_text.php?'. htmlspecialchars($QUERY_STRING).
+    $Args[0]['attachment_common']['href'] = $base_uri  . 'src/view_text.php?'. htmlspecialchars($QUERY_STRING).
         /* why use the overridetype? can this be removed */
         /* override_type might be needed only when we want view other type of messages as html */
        '&override_type0=text&override_type1=html';
-    $Args[1]['attachment_common']['href'] =
-          set_url_var($Args[1]['attachment_common']['href'],
-          'ent_id',$Args[5]);
+    $Args[0]['attachment_common']['href'] =
+          set_url_var($Args[0]['attachment_common']['href'],
+          'ent_id',$Args[4]);
 
-    $Args[1]['attachment_common']['text'] = _("View");
+    $Args[0]['attachment_common']['text'] = _("View");
 
-    $Args[6] = $Args[1]['attachment_common']['href'];
+    $Args[5] = $Args[0]['attachment_common']['href'];
 }
 
 /**
@@ -202,22 +202,22 @@ function attachment_common_link_image(&$Args) {
 
     sqgetGlobalVar('QUERY_STRING', $QUERY_STRING, SQ_SERVER);
 
-    $info['passed_id'] = $Args[3];
-    $info['mailbox'] = $Args[4];
-    $info['ent_id'] = $Args[5];
-    $info['name'] = $Args[7];
-    $info['download_href'] = isset($Args[1]['download link']) ? $Args[1]['download link']['href'] : '';
+    $info['passed_id'] = $Args[2];
+    $info['mailbox'] = $Args[3];
+    $info['ent_id'] = $Args[4];
+    $info['name'] = $Args[6];
+    $info['download_href'] = isset($Args[0]['download link']) ? $Args[0]['download link']['href'] : '';
     
     $attachment_common_show_images_list[] = $info;
 
-    $Args[1]['attachment_common']['href'] = $base_uri  . 'src/image.php?'. htmlspecialchars($QUERY_STRING);
-    $Args[1]['attachment_common']['href'] =
-          set_url_var($Args[1]['attachment_common']['href'],
-          'ent_id',$Args[5]);
+    $Args[0]['attachment_common']['href'] = $base_uri  . 'src/image.php?'. htmlspecialchars($QUERY_STRING);
+    $Args[0]['attachment_common']['href'] =
+          set_url_var($Args[0]['attachment_common']['href'],
+          'ent_id',$Args[4]);
 
-    $Args[1]['attachment_common']['text'] = _("View");
+    $Args[0]['attachment_common']['text'] = _("View");
 
-    $Args[6] = $Args[1]['attachment_common']['href'];
+    $Args[5] = $Args[0]['attachment_common']['href'];
 }
 
 /**
@@ -229,14 +229,14 @@ function attachment_common_link_vcard(&$Args) {
     global $base_uri;
     sqgetGlobalVar('QUERY_STRING', $QUERY_STRING, SQ_SERVER);
 
-    $Args[1]['attachment_common']['href'] = $base_uri  . 'src/vcard.php?'. htmlspecialchars($QUERY_STRING);
-    $Args[1]['attachment_common']['href'] =
-          set_url_var($Args[1]['attachment_common']['href'],
-          'ent_id',$Args[5]);
+    $Args[0]['attachment_common']['href'] = $base_uri  . 'src/vcard.php?'. htmlspecialchars($QUERY_STRING);
+    $Args[0]['attachment_common']['href'] =
+          set_url_var($Args[0]['attachment_common']['href'],
+          'ent_id',$Args[4]);
 
-    $Args[1]['attachment_common']['text'] = _("View Business Card");
+    $Args[0]['attachment_common']['text'] = _("View Business Card");
 
-    $Args[6] = $Args[1]['attachment_common']['href'];
+    $Args[5] = $Args[0]['attachment_common']['href'];
 }
 
 /**
@@ -246,22 +246,19 @@ function attachment_common_link_vcard(&$Args) {
  * @since 1.2.0
  */
 function attachment_common_octet_stream(&$Args) {
-    global $FileExtensionToMimeType;
+    global $FileExtensionToMimeType, $null;
 
-    do_hook('attachment_common-load_mime_types');
+    do_hook('attachment_common-load_mime_types', $null);
 
-    ereg('\\.([^\\.]+)$', $Args[7], $Regs);
+    ereg('\\.([^\\.]+)$', $Args[6], $Regs);
 
     $Ext = strtolower($Regs[1]);
 
     if ($Ext == '' || ! isset($FileExtensionToMimeType[$Ext]))
         return;
 
-    $Ret = do_hook('attachment ' . $FileExtensionToMimeType[$Ext],
-        $Args[1], $Args[2], $Args[3], $Args[4], $Args[5], $Args[6],
-        $Args[7], $Args[8], $Args[9]);
+    do_hook('attachment ' . $FileExtensionToMimeType[$Ext],
+        $temp=array(&$Args[0], &$Args[1], &$Args[2], &$Args[3], &$Args[4], &$Args[5],
+        &$Args[6], &$Args[7], &$Args[8]));
 
-    foreach ($Ret as $a => $b) {
-        $Args[$a] = $b;
-    }
 }

functions/display_messages.php

@@ -63,8 +63,9 @@ function logout_error( $errString, $errTitle = '' ) {
                             'FRAME' => $frame_top
                         );
                         
-    list($junk, $errString, $errTitle, $login_link) 
-        = do_hook('logout_error', $errString, $errTitle, $login_link);
+    /* As of 1.5.2, plugin parameters are combined into one array; 
+       plugins on this hook must be updated */
+    do_hook('logout_error', $temp=array(&$errString, &$errTitle, &$login_link));
 
     if ( $errTitle == '' ) {
         $errTitle = $errString;
@@ -114,31 +115,30 @@ function logout_error( $errString, $errTitle = '' ) {
  * 
  * Since 1.4.1 function checks if page header is already displayed.
  * 
- * Since 1.4.3 and 1.5.1 function contains error_box hook.
+ * Since 1.4.3 and 1.5.1, this function contains the error_box hook.
  * Use plain_error_message() and make sure that page header is created,
  * if you want compatibility with 1.4.0 and older.
  *
  * In 1.5.2 second function argument is changed. Older functions used it
  * for $color array, new function uses it for optional link data. Function 
  * will ignore color array and use standard colors instead.
+ *
  * @param string $string Error message to be displayed
  * @param array $link Optional array containing link details to be displayed.
  *  Array uses three keys. 'URL' key is required and should contain link URL.
  *  'TEXT' key is optional and should contain link name. 'FRAME' key is 
  *  optional and should contain link target attribute.
+ *
  * @since 1.3.2
  */
 function error_box($string, $link=NULL) {
     global $pageheader_sent, $oTemplate;
 
     $err = _("ERROR");
-    $ret = concat_hook_function('error_box', $string);
-    if($ret != '') {
-        $string = $ret;
-    }
+    do_hook('error_box', $string);
 
     /* check if the page header has been sent; if not, send it! */
-    if(!isset($pageheader_sent) && !$pageheader_sent) {
+    if (!isset($pageheader_sent) && !$pageheader_sent) {
         displayHtmlHeader('SquirrelMail: '.$err);
         $pageheader_sent = TRUE;
         echo "<body>\n\n";

functions/file_prefs.php

@@ -100,13 +100,13 @@ function cachePrefValues($data_dir, $username) {
 function getPref($data_dir, $username, $string, $default = '') {
     global $prefs_cache;
 
-    $result = do_hook_function('get_pref_override',array($username,$string));
+    $result = do_hook('get_pref_override', $temp=array(&$username, &$string));
     if (!$result) {
         cachePrefValues($data_dir, $username);
         if (isset($prefs_cache[$string])) {
             $result = $prefs_cache[$string];
         } else {
-            $result = do_hook_function('get_pref', array($username,$string));
+            $result = do_hook('get_pref', $temp=array(&$username, &$string));
             if (!$result) {
                 $result = $default;
             }

functions/identity.php

@@ -134,7 +134,7 @@ function sqfixidentities( $identities, $id, $action ) {
                     $fixed[0] = $ident;
 
                     // inform plugins about renumbering of ids
-                    do_hook('options_identities_renumber', $id, 'default');
+                    do_hook('options_identities_renumber', $temp=array(&$id, 'default'));
 
                     continue 2;
                 } else {
@@ -148,7 +148,7 @@ function sqfixidentities( $identities, $id, $action ) {
                     $tmp_hold = $ident;
 
                     // inform plugins about renumbering of ids
-                    do_hook('options_identities_renumber', $id , $id - 1);
+                    do_hook('options_identities_renumber', $temp=array(&$id , $id - 1));
 
                     continue 2;
                 } else {
@@ -165,7 +165,7 @@ function sqfixidentities( $identities, $id, $action ) {
 
                 if ($key == $id) {
                     // inform plugins about deleted id
-                    do_hook('options_identities_process', $action, $id);
+                    do_hook('options_identities_process', $temp=array(&$action, &$id));
 
                     continue 2;
                 } else {
@@ -181,7 +181,7 @@ function sqfixidentities( $identities, $id, $action ) {
                  * be used to detect modified hook. Older hook does not
                  * provide information that can be useful for plugins.
                  */
-                do_hook('options_identities_process', $action, $id);
+                do_hook('options_identities_process', $temp=array(&$action, &$id));
 
                 $fixed[$i] = $ident;
 

functions/imap_general.php

@@ -1279,7 +1279,7 @@ function sqimap_status_messages ($imap_stream, $mailbox,
     if (!empty($hook_status)) {
          $hook_status['MAILBOX']=$mailbox;
          $hook_status['CALLER']='sqimap_status_messages';
-         do_hook_function('folder_status',$hook_status);
+         do_hook('folder_status', $hook_status);
     }
     return $status;
 }

functions/imap_mailbox.php

@@ -233,7 +233,7 @@ function isSpecialMailbox($box,$include_subs=true) {
              isDraftMailbox($box,$include_subs) );
 
     if ( !$ret ) {
-        $ret = boolean_hook_function('special_mailbox',$box,1);
+        $ret = boolean_hook_function('special_mailbox', $box, 1);
     }
     return $ret;
 }
@@ -486,7 +486,7 @@ function sqimap_mailbox_delete ($imap_stream, $mailbox) {
             // subscribe again
             sqimap_subscribe ($imap_stream, $mailbox);
         } else {
-            do_hook_function('rename_or_delete_folder', $args = array($mailbox, 'delete', ''));
+            do_hook('rename_or_delete_folder', $temp=array(&$mailbox, 'delete', ''));
             removePref($data_dir, $username, "thread_$mailbox");
             removePref($data_dir, $username, "collapse_folder_$mailbox");
         }
@@ -541,7 +541,7 @@ function sqimap_mailbox_rename( $imap_stream, $old_name, $new_name ) {
         sqimap_subscribe($imap_stream, $new_name.$postfix);
         setPref($data_dir, $username, 'thread_'.$new_name.$postfix, $oldpref_thread);
         setPref($data_dir, $username, 'collapse_folder_'.$new_name.$postfix, $oldpref_collapse);
-        do_hook_function('rename_or_delete_folder',$args = array($old_name, 'rename', $new_name));
+        do_hook('rename_or_delete_folder', $temp=array(&$old_name, 'rename', &$new_name));
         $l = strlen( $old_name ) + 1;
         $p = 'unformatted';
 
@@ -567,8 +567,7 @@ function sqimap_mailbox_rename( $imap_stream, $old_name, $new_name ) {
                 }
                 setPref($data_dir, $username, 'thread_'.$new_sub, $oldpref_thread);
                 setPref($data_dir, $username, 'collapse_folder_'.$new_sub, $oldpref_collapse);
-                do_hook_function('rename_or_delete_folder',
-                                 $args = array($box[$p], 'rename', $new_sub));
+                do_hook('rename_or_delete_folder', $temp=array(&$box[$p], 'rename', &$new_sub));
             }
         }
     }
@@ -1381,7 +1380,7 @@ function sqimap_get_status_mbx_tree($imap_stream,&$mbx_tree) {
          {
               $hook_status['MAILBOX']=$oMbx->mailboxname_full;
               $hook_status['CALLER']='sqimap_get_status_mbx_tree'; // helps w/ debugging
-              do_hook_function('folder_status',$hook_status);
+              do_hook('folder_status', $hook_status);
          }
     }
 }

functions/mailbox_display.php

@@ -21,7 +21,9 @@
  * @param string   $mailbox mailbox to select and retrieve message headers from
  * @param array    $aConfig array with system config settings and incoming vars
  * @param array    $aProps mailbox specific properties
+ *
  * @return array   $aMailbox mailbox array with all relevant information
+ *
  * @since 1.5.1
  * @author Marc Groot Koerkamp
  */
@@ -604,7 +606,7 @@ function prepareMessageList(&$aMailbox, $aProps) {
                         // $onclick, $link_extra, $title, and so forth)
                         // plugins are responsible for sharing nicely (such as for
                         // setting the target, etc)
-                        do_hook('subject_link', array($iPageOffset, $sSearch, $aSearch));
+                        do_hook('subject_link', $temp=array(&$iPageOffset, &$sSearch, &$aSearch));
                     }
                     $value = (trim($value)) ? $value : _("(no subject)");
                     /* add thread indentation */
@@ -1304,7 +1306,7 @@ function handleMessageListForm($imapConnection,&$aMailbox,$sButton='',$aUid = ar
             break;
           default:
              // Hook for plugin buttons
-             do_hook_function('mailbox_display_button_action', $aUid);
+             do_hook('mailbox_display_button_action', $aUid);
              break;
         }
         /**

functions/mime.php

@@ -374,8 +374,9 @@ function formatBody($imap_stream, $message, $color, $wrap_at, $ent_num, $id, $ma
                 $body = call_user_func($languages[$squirrelmail_language]['XTRA_CODE'] . '_decode',$body);
             }
         }
-        $hookResults = do_hook("message_body", $body);
-        $body = $hookResults[1];
+
+        /* As of 1.5.2, $body is passed (and modified) by reference */
+        do_hook('message_body', $body);
 
         /* If there are other types that shouldn't be formatted, add
          * them here.
@@ -552,20 +553,32 @@ function buildAttachmentArray($message, $exclude_id, $mailbox, $id) {
          * for a more generic type. Finally, a hook for ALL attachment
          * types is run as well.
          */
-        $hookresults = do_hook("attachment $type0/$type1", $links,
-                $startMessage, $id, $urlMailbox, $ent, $defaultlink,
-                $display_filename, $where, $what);
-        if(count($hookresults[1]) <= 1) {
-            $hookresults = do_hook("attachment $type0/*", $links,
-                    $startMessage, $id, $urlMailbox, $ent, $defaultlink,
-                    $display_filename, $where, $what);
+        /* The API for this hook has changed as of 1.5.2 so that all plugin
+           arguments are passed in an array instead of each their own plugin
+           argument, and arguments are passed by reference, so instead of
+           returning any changes, changes should simply be made to the original
+           arguments themselves. */
+        do_hook("attachment $type0/$type1", $temp=array(&$links,
+                &$startMessage, &$id, &$urlMailbox, &$ent, &$defaultlink,
+                &$display_filename, &$where, &$what));
+        if(count($links) <= 1) {
+            /* The API for this hook has changed as of 1.5.2 so that all plugin
+               arguments are passed in an array instead of each their own plugin
+               argument, and arguments are passed by reference, so instead of
+               returning any changes, changes should simply be made to the original
+               arguments themselves. */
+            do_hook("attachment $type0/*", $temp=array(&$links,
+                    &$startMessage, &$id, &$urlMailbox, &$ent, &$defaultlink,
+                    &$display_filename, &$where, &$what));
         }
-        $hookresults = do_hook("attachment */*", $hookresults[1],
-            $startMessage, $id, $urlMailbox, $ent, $hookresults[6],
-            $display_filename, $where, $what);
-
-        $links = $hookresults[1];
-        $defaultlink = $hookresults[6];
+        /* The API for this hook has changed as of 1.5.2 so that all plugin
+           arguments are passed in an array instead of each their own plugin
+           argument, and arguments are passed by reference, so instead of
+           returning any changes, changes should simply be made to the original
+           arguments themselves. */
+        do_hook("attachment */*", $temp=array(&$links,
+                &$startMessage, &$id, &$urlMailbox, &$ent, &$defaultlink, 
+                &$display_filename, &$where, &$what));
 
         $this_attachment = array();
         $this_attachment['Name'] = decodeHeader($display_filename);
@@ -659,7 +672,7 @@ function decodeBody($body, $encoding) {
     $body = str_replace("\r\n", "\n", $body);
     $encoding = strtolower($encoding);
 
-    $encoding_handler = do_hook_function('decode_body', $encoding);
+    $encoding_handler = do_hook('decode_body', $encoding);
 
 
     // plugins get first shot at decoding the body

functions/page_header.php

@@ -108,7 +108,8 @@ function displayHtmlHeader( $title = 'SquirrelMail', $xtra = '', $do_hook = TRUE
     if ($do_hook) {
         // NOTE! plugins here must assign output to template 
         //       and NOT echo anything directly!!
-        do_hook('generic_header');
+        global $null;
+        do_hook('generic_header', $null);
     }
 
     $header_tags .= $xtra;
@@ -159,9 +160,7 @@ function makeInternalLink($path, $text, $target='') {
     // here just in case we find a good (non-visual?)
     // use for the internal_link hook.
     //
-    //$hooktext = do_hook_function('internal_link',$text);
-    //if ($hooktext != '')
-    //    $text = $hooktext;
+    //do_hook('internal_link', $text);
 
     return '<a href="'.$base_uri.$path.'"'.$target.'>'.$text.'</a>';
 }

functions/plugin.php

@@ -37,100 +37,64 @@ function use_plugin ($name) {
 }
 
 /**
- * This function executes a hook.
- * @param string $name Name of hook to fire
- * @return mixed $data
- */
-function do_hook ($name) {
-    global $squirrelmail_plugin_hooks, $currentHookName;
-    $data = func_get_args();
-    $currentHookName = $name;
-
-    if (isset($squirrelmail_plugin_hooks[$name])
-          && is_array($squirrelmail_plugin_hooks[$name])) {
-        foreach ($squirrelmail_plugin_hooks[$name] as $plugin_name => $function) {
-            use_plugin($plugin_name);
-            /* Add something to set correct gettext domain for plugin. */
-            if (function_exists($function)) {
-                $function($data);
-            }
-        }
-    }
-
-    $currentHookName = '';
-
-    /* Variable-length argument lists have a slight problem when */
-    /* passing values by reference. Pity. This is a workaround.  */
-    return $data;
-}
-
-/**
- * This function executes a hook and allows for parameters to be 
- * passed, wherein each plugin can modify the parameters before 
- * they are passed to the next funciton. Whether or not the 
- * parameters are modified, plugins on this hook should always
- * return the given parameters.
+ * This function executes a plugin hook.
  *
- * @param string name the name of the hook
- * @param mixed param the parameters to pass to the hook function
- * @return mixed the possibly modified hook parameters
- */
-function filter_hook_function($name,$parm=NULL) {
-    global $squirrelmail_plugin_hooks, $currentHookName;
-    $currentHookName = $name;
-
-    if (isset($squirrelmail_plugin_hooks[$name])
-          && is_array($squirrelmail_plugin_hooks[$name])) {
-        foreach ($squirrelmail_plugin_hooks[$name] as $plugin_name => $function) {
-            use_plugin($plugin_name);
-            /* Add something to set correct gettext domain for plugin. */
-            if (function_exists($function)) {
-                $parm = $function($parm);
-            }
-        }
-    }
-
-    $currentHookName = '';
-
-    /* Variable-length argument lists have a slight problem when */
-    /* passing values by reference. Pity. This is a workaround.  */
-    return $parm;
-}
-
-/**
- * This function executes a hook and allows for parameters to be passed.
+ * It includes an arbitrary return value that is managed by
+ * all plugins on the same hook and returned to the core hook
+ * location.
+ *
+ * The desired format of the return value should be defined 
+ * by the context in which the hook is called.
+ *
+ * Note that the master return value for this hook is passed
+ * to each plugin after the main argument(s) value/array as a 
+ * convenience only - to show what the current return value is
+ * even though it is liable to be changed by other plugins.
+ *
+ * If any plugin on this hook wants to modify the $args
+ * plugin parameter, it simply has to use call-by-reference
+ * syntax in the hook function that it has registered for the
+ * current hook.  Note that this is in addition to (entirely
+ * independent of) the return value for this hook.
+ *
+ * @param string $name Name of hook being executed
+ * @param mixed  $args A single value or an array of arguments 
+ *                     that are to be passed to all plugins 
+ *                     operating off the hook being called.  
+ *                     Note that this argument is passed by 
+ *                     reference thus it is liable to be 
+ *                     changed after the hook completes.
+ *
+ * @return mixed The return value that is managed by the plugins
+ *               on the current hook.
  *
- * @param string name the name of the hook
- * @param mixed param the parameters to pass to the hook function
- * @return mixed the return value of the hook function
  */
-function do_hook_function($name,$parm=NULL) {
+function do_hook($name, &$args) {
+
     global $squirrelmail_plugin_hooks, $currentHookName;
-    $ret = '';
     $currentHookName = $name;
+    $ret = NULL;
 
     if (isset($squirrelmail_plugin_hooks[$name])
           && is_array($squirrelmail_plugin_hooks[$name])) {
         foreach ($squirrelmail_plugin_hooks[$name] as $plugin_name => $function) {
             use_plugin($plugin_name);
-            /* Add something to set correct gettext domain for plugin. */
             if (function_exists($function)) {
-                $ret = $function($parm);
+                $ret = $function($args, $ret);
             }
         }
     }
 
     $currentHookName = '';
-
-    /* Variable-length argument lists have a slight problem when */
-    /* passing values by reference. Pity. This is a workaround.  */
     return $ret;
+
 }
 
 /**
- * This function executes a hook, allows for parameters to be passed,
- * and looks for an array returned from each plugin: each array is 
- * then merged into one and returned to the core hook location.
+ * This function executes a hook that allows for an arbitrary
+ * return value from each plugin that will be merged into one
+ * array (or one string if all return values are strings) and
+ * returned to the core hook location.
  *
  * Note that unlike PHP's array_merge function, matching array keys
  * will not overwrite each other, instead, values under such keys
@@ -142,25 +106,36 @@ function do_hook_function($name,$parm=NULL) {
  * unless ALL values returned are strings, in which case one string
  * with all returned strings concatenated together is returned.
  *
- * @param string name the name of the hook
- * @param mixed param the parameters to pass to the hook function
+ * If any plugin on this hook wants to modify the $args
+ * plugin parameter, it simply has to use call-by-reference
+ * syntax in the hook function that it has registered for the
+ * current hook.  Note that this is in addition to (entirely
+ * independent of) the return value for this hook.
+ *
+ * @param string $name Name of hook being executed
+ * @param mixed  $args A single value or an array of arguments 
+ *                     that are to be passed to all plugins 
+ *                     operating off the hook being called.  
+ *                     Note that this argument is passed by 
+ *                     reference thus it is liable to be 
+ *                     changed after the hook completes.
  *
  * @return mixed the merged return arrays or strings of each
- *               plugin on this hook
+ *               plugin on this hook.
  *
  */
-function concat_hook_function($name,$parm=NULL) {
+function concat_hook_function($name, &$args) {
+
     global $squirrelmail_plugin_hooks, $currentHookName;
-    $ret = '';
     $currentHookName = $name;
+    $ret = '';
 
     if (isset($squirrelmail_plugin_hooks[$name])
           && is_array($squirrelmail_plugin_hooks[$name])) {
         foreach ($squirrelmail_plugin_hooks[$name] as $plugin_name => $function) {
             use_plugin($plugin_name);
-            /* Add something to set correct gettext domain for plugin. */
             if (function_exists($function)) {
-                $plugin_ret = $function($parm);
+                $plugin_ret = $function($args);
                 if (!empty($plugin_ret)) {
                     $ret = sqm_array_merge($ret, $plugin_ret);
                 }
@@ -169,10 +144,8 @@ function concat_hook_function($name,$parm=NULL) {
     }
 
     $currentHookName = '';
-
-    /* Variable-length argument lists have a slight problem when */
-    /* passing values by reference. Pity. This is a workaround.  */
     return $ret;
+
 }
 
 /**
@@ -182,13 +155,27 @@ function concat_hook_function($name,$parm=NULL) {
  * override any trues.
  * Priority 0 means majority rules.  Ties will be broken with $tie
  *
- * @param string name the hook name
- * @param mixed parm the parameters for the hook function
- * @param int priority
- * @param bool tie
- * @return bool the result of the function
+ * If any plugin on this hook wants to modify the $args
+ * plugin parameter, it simply has to use call-by-reference
+ * syntax in the hook function that it has registered for the
+ * current hook.  Note that this is in addition to (entirely
+ * independent of) the return value for this hook.
+ *
+ * @param string  $name     The hook name
+ * @param mixed   $args     A single value or an array of arguments 
+ *                          that are to be passed to all plugins 
+ *                          operating off the hook being called.  
+ *                          Note that this argument is passed by 
+ *                          reference thus it is liable to be 
+ *                          changed after the hook completes.
+ * @param int     $priority See explanation above
+ * @param boolean $tie      See explanation above
+ *
+ * @return boolean The result of the function
+ *
  */
-function boolean_hook_function($name,$parm=NULL,$priority=0,$tie=false) {
+function boolean_hook_function($name, &$args, $priority=0, $tie=false) {
+
     global $squirrelmail_plugin_hooks, $currentHookName;
     $yea = 0;
     $nay = 0;
@@ -202,7 +189,7 @@ function boolean_hook_function($name,$parm=NULL,$priority=0,$tie=false) {
         foreach ($squirrelmail_plugin_hooks[$name] as $plugin_name => $function) {
             use_plugin($plugin_name);
             if (function_exists($function)) {
-                $ret = $function($parm);
+                $ret = $function($args);
                 if ($ret) {
                     $yea++;
                 } else {
@@ -228,6 +215,7 @@ function boolean_hook_function($name,$parm=NULL,$priority=0,$tie=false) {
     }
     // If the code gets here, there was a problem - no hooks, etc.
     return NULL;
+
 }
 
 /**

include/init.php

@@ -61,6 +61,13 @@ if ((bool) ini_get('register_globals') &&
     unset($GLOBALS['value']);
 }
 
+/**
+ * Used as a dummy value, e.g., for passing as an empty
+ * hook argument.
+ */
+global $null; 
+$null = NULL;
+
 /**
  * [#1518885] session.use_cookies = off breaks SquirrelMail
  *
@@ -264,7 +271,7 @@ if (!$disable_plugins && file_exists(SM_PATH . 'config/plugin_hooks.php')) {
  * allow plugins to override main configuration; hook is placed
  * here to allow plugins to use session information to do their work
  */
-do_hook('config_override');
+do_hook('config_override', $null);
 
 /**
  * DISABLED.
@@ -298,14 +305,6 @@ if (!isset($sInitLocation)) {
     $sInitLocation=NULL;
 }
 
-/**
- * Before 1.5.2 version hook was part of functions/constants.php.
- * After init layout changes, hook had to be moved because include/constants.php is
- * loaded before plugins are initialized.
- * @since 1.2.0
- */
-do_hook('loading_constants');
-
 switch ($sInitLocation) {
     case 'style': 
 
@@ -348,7 +347,7 @@ switch ($sInitLocation) {
         require(SM_PATH . 'functions/prefs.php');
         require(SM_PATH . 'functions/auth.php');
         /* hook loads custom prefs backend plugins */
-        $prefs_backend = do_hook_function('prefs_backend');
+        $prefs_backend = do_hook('prefs_backend', $null);
         if (isset($prefs_backend) && !empty($prefs_backend) && file_exists(SM_PATH . $prefs_backend)) {
             require(SM_PATH . $prefs_backend);
         } elseif (isset($prefs_dsn) && !empty($prefs_dsn)) {
@@ -460,7 +459,7 @@ switch ($sInitLocation) {
         /* see 'redirect' case */
         require(SM_PATH . 'functions/prefs.php');
 
-        $prefs_backend = do_hook_function('prefs_backend');
+        $prefs_backend = do_hook('prefs_backend', $null);
         if (isset($prefs_backend) && !empty($prefs_backend) && file_exists(SM_PATH . $prefs_backend)) {
             require(SM_PATH . $prefs_backend);
         } elseif (isset($prefs_dsn) && !empty($prefs_dsn)) {

include/load_prefs.php

@@ -424,4 +424,4 @@ if (! isset($use_smtp_tls)) {
     $use_smtp_tls = false;
 }
 
-do_hook('loading_prefs');
+do_hook('loading_prefs', $null);