4. Developing plugins

SquirrelMail is built with an ingenious and powerful system that allows add-ons known as plugins to extend its feature set in almost infinite directions. This is one of the main reasons cited when users and administrators explain SquirrelMail as their webmail of choice, and the technology behind it has also been borrowed for other projects.

It is also thanks to the many plugin authors that have contributed large amounts of code and a wide array of functionality ideas that SquirrelMail is as popular as it is. The SquirrelMail team would like to encourage authors to contribute in the best way possible, which is what the following information will enable them to do. If you are considering adding a feature to SquirrelMail, this is the best place to start.

4.1 Before embarking

One of the most enjoyable parts of programming is seeing an idea turn into a working product - the transition from "what if SquirrelMail could do..." to "SquirrelMail can do..." The SquirrelMail team can appreciate and relate to that kind of enthusiasm, but we also don't want to see it go to waste. Therefore, the first thing to be done before considering the development of a new plugin (for public consumption at least) is to ask the SquirrelMail team if anyone has already attempted to implement the idea. It is also extremely helpful to announce your intentions in public so that the SquirrelMail community can provide feedback and help refine the idea before it is implemented.

Additionally, in keeping with the SquirrelMail theme of providing a product that is simple to install and maintain, the team's philosophy regarding plugins is to avoid the "Firefox Syndrome", wherein it can take hours for an administrator to find the right plugin to suit a single need. Plugins that contain similar feature sets should be merged and authors should work collaboratively instead of duplicating each others' efforts. If there is a plugin on the SquirrelMail web site that almost does what you want to do, please inquire with its author and/or the SquirrelMail team about enhancing it with your ideas.

4.2 The plugin architecture

The plugin architecture of SquirrelMail is designed to make it possible to add new features without having to patch SquirrelMail itself. Functionality like changing user passwords, displaying ads or calendars, and managing spam settings should be possible to add as plugins. In this scheme, either package (SquirrelMail or a plugin) may be upgraded independently without risk of one breaking the other.

The idea

The idea is to be able to run plugin code at given places in the SquirrelMail core. The plugin code should then be able to do whatever is needed to enhance the functionality of SquirrelMail. The places where plugin code can be executed are called "hooks".

There are some limitations with what these hooks can do. It is difficult to use them to change the layout and to change some functionalities that are hard-coded in SquirrelMail.

The implementation

The plugin start point in the main SquirrelMail code is in the file functions/plugin.php. In places where hooks are made available, they are executed by calling one of the hook functions. The hook function then traverses the array $squirrelmail_plugin_hooks['hookname'] and executes all the functions that are named in that array. Those functions are placed there when plugins register themselves with SquirrelMail as discussed below. A plugin may add its own internal functions to this array under any hook name provided by the SquirrelMail developers.

A plugin must reside in a subdirectory of the plugins/ directory. The name of the subdirectory is considered to be the name of the plugin. Note that the plugin will not function correctly if this is not the case.

A plugin is registered with SquirrelMail by using the configuration utility or by manually editing the SquirrelMail configuration file. When adding a plugin manually, its name (its directory name) must be added to the $plugins array in config.php like this:

$plugins[] = 'plugin_name';

When a plugin is registered, the file plugins/plugin_name/setup.php is loaded and the function squirrelmail_plugin_init_<plugin name>() is called with no parameters. That function is where the plugin may register itself against any hooks it wishes to take advantage of.

As of SquirrelMail 1.5.2, the plugins/plugin_name/setup.php file is parsed at configuration time instead of at run time as a performance enhancement. The resultant $squirrelmail_plugin_hooks['hookname'] array is then stored statically in the SquirrelMail config directory in a file called plugin_hooks.php. Plugin authors should keep in mind that when making changes to the hook structure of their plugins, they will need to re-run the SquirrelMail configuraion utility or manually edit plugin_hooks.php before the changes will take effect.

TODO: Add a description on how to manually create the file plugin_hooks.php, i.e. without using the Perl script. Perl is not a requisite.

4.3 The starting point

Plugin initialization

All plugins must contain a file called setup.php and must include a function called squirrelmail_plugin_init_<plugin name>() therein. Since including numerous plugins can slow SquirrelMail's performance considerably, the setup.php file should contain little else. Any functions that are registered against plugin hooks should do little more than call another function in a different file. No other files should be included in the global scope of setup.php, as this defeats the purpose of keeping it streamlined.

Any other files used by the plugin should also be placed in the plugin directory (or a subdirectory thereof) and should contain the bulk of the plugin logic.

The function squirrelmail_plugin_init_<plugin name>() is called to initalize a plugin as explained above. This function could look something like this (if the plugin was named "demo" and resided in the directory plugins/demo/):

/**
 * Register this plugin with SquirrelMail
 */
function squirrelmail_plugin_init_demo() {
    global $squirrelmail_plugin_hooks;

    $squirrelmail_plugin_hooks['optpage_register_block']['demo']
        = 'plugin_demo_options_stub';
    $squirrelmail_plugin_hooks['login_cookie']['demo']
        = 'plugin_demo_login_stub';
}

Again, please note that as of SquirrelMail 1.5.2, this function is no longer called at run time and is instead called (actually, it is only parsed, never executed) only once at configuration time. Thus, the inclusion of any dynamic code (anything except hook registration) here is strongly discouraged.

Adding functionality

In the example above, the "demo" plugin should also have two other functions in its setup.php file called plugin_demo_options_stub() and plugin_demo_login_stub(). The first of these might look something like this:

/**
 * Add link to the Demo options page on the SquirrelMail
 * main options page listing
 */
function plugin_demo_options_stub() {
    include_once(SM_PATH . 'plugins/demo/functions.php');
    plugin_demo_options();
}

The function called plugin_demo_options() in the file plugins/demo/functions.php contains the plugin's core logic for the optpage_register_block hook. Aside from plugin_demo_options_stub() and plugin_demo_login_stub() and the version reporting information explained below, there should be little-to-nothing else in setup.php.

4.4 Hooks

In the example above, the "demo" plugin uses two "hooks" called "optpage_register_block" and "login_cookie". Which hooks a plugin uses depends on what kind of functionality is being implemented - where in the SquirrelMail source code does the plugin need to execute its own code?

Hooks themselves are functions executed by the SquirrelMail core using one of just a few hook types which in turn pass execution to the plugins that have registered themselves against the current hook as explained above.

When executed, hooks are called with differing parameters and may or may not take return values, all depending on the type of hook being called and the context in which it is being used. On the source side (where the hook call originates), all hooks have at least one parameter, which is the name of the hook. After that, things (sometimes) get complicated.

Hook types, parameters and return values

The design of each of the hook types has changed somewhat starting with SquirrelMail version 1.5.2, so we provide a description of the hook types for both the 1.4 release series and versions starting with 1.5.2. Despite the differences noted here, in most cases, plugins will run on the same hook without the need for version-specific code in either environment (however, there are other differences that do require version-specific code, which are explained elsewhere).

SquirrelMail 1.5.2+ uses three hook functions: do_hook(), concat_hook_function(), and boolean_hook_function().

The do_hook() function is the most common do-all hook in the SquirrelMail core. It provides all plugins a single parameter which is passed through the hook by reference, so, if a plugin also accepts it by reference, it can be changed as needed (and it is often an array of multiple values of interest to plugins using a particular hook: take a look in the core - the second argument to the do_hook call is what is passed along to the plugins). There is a second parameter given to plugins, but it is not normally used: it is the current value of the ultimate hook return value. All plugins are responsible for sharing the creation/modification of whatever do_hook returns. The ultimate return value is whatever the last plugin returns from its hook implementation, but if it does return something, it should be sure to check if there was already a return value created by other plugins, which is what is given as the second parameter to the plugin. As with all hooks, the usage of the hook parameters and/or its return value are determined based on the context in which the hook is used - you have to look at it in the SquirrelMail core. Please remember NEVER to output any HTML directly during hook execution.

Read more about the do_hook() function in the 1.5 API documentation.

The concat_hook_function() is used in places where the SquirrelMail core needs to aggregate return data from all plugins on the same hook. Plugins are provided with the same (modifiable) parameter as with do_hook. In some places, the core will expect all plugins to return strings, which will be concatenated together and returned to the SquirrelMail core. In other cases, arbitrary values are used by the core, which will be placed into an array of return values. What kind of return value is expected is best determined by inspecting the core where the hook is called. Please remember NEVER to output any HTML directly during hook execution.

Read more about the concat_hook_function() function in the 1.5 API documentation.

The boolean_hook_function() allows plugins to vote for a specified action. What that action is is entirely dependent on how the hook is used in the SquirrelMail core (look for yourself). Plugins make their vote by returning a boolean TRUE or FALSE value. This hook may be configured to tally votes in one of three ways. This configuration is done with the third parameter in the hook call in the core:

• > 0 -- At least one TRUE will override all FALSE.
• < 0 -- At least one FALSE will override all TRUE.
• = 0 -- Majority wins. Any ties are broken with the last parameter in the hook call.

Plugins using boolean_hook_function are provided with the same (modifiable) parameter as with do_hook. Please remember NEVER to output any HTML directly during hook execution.

Read more about the boolean_hook_function() function in the 1.5 API documentation.

SquirrelMail 1.4 uses four hook functions: do_hook(), do_hook_function(), concat_hook_function(), and boolean_hook_function().

The do_hook() function is a simple function that allows injecting of custom output or override of default interface data. It doesn't pass any data and doesn't ask for anything back. A limited number of do_hook() calls do pass some extra parameters, in which case your plugin may modify the given data if you do so by reference. It is not necessary to return anything from your function in such a case; modifying the parameter data by reference is what does the job (although the hook call itself (in the SquirrelMail core) must grab the return value for this to work). Note that in this case, the one and only parameter to your hook function will be an array, the first element simply being the hook name, followed by any other parameters that may have been included in the actual hook call in the core. Modify parameters with care!

Read more about the do_hook() function in the 1.4 API documentation

The do_hook_function() was intended to be the main hook type used when the source needs to get something back from your plugin. It is somewhat limited in that it will only use the value returned from the last plugin registered against the hook. The SquirrelMail core might use the return value for this hook type for internal purposes, or might expect you to provide text or HTML to be sent to the client browser (you'll have to look at its use in context to understand how you should return values here). The parameters that your hook function gets will be anything you see after the hook name in the actual hook call in the source. These cannot be changed in the same way that the do_hook() parameters can be.

Read more about the do_hook_function() function in the 1.4 API documentation

The concat_hook_function() fixes some shortcomings of the do_hook_function() in that it uses the return values of all plugins registered against the hook. In order to do so, the return value is assumed to be a string, which is just piled (concatenated) on top of whatever it got from the other plugins working on the same hook. Again, you'll have to inspect the source code to see how such data is put to use, but most of the time, it is used to create a string of HTML to be inserted into the output page. The parameters that your hook function will get are the same as for the do_hook_function; they are anything after the hook name in the actual hook call in the source.

Read more about the concat_hook_function() function in the 1.4 API documentation

The boolean_hook_function() allows plugins to vote for a specified action. What that action is is entirely dependent on how the hook is used in the SquirrelMail core (look for yourself). Plugins make their vote by returning a boolean TRUE or FALSE value. This hook may be configured to tally votes in one of three ways. This configuration is done with the third parameter in the hook call in the core:

• > 0 -- At least one TRUE will override all FALSE.
• < 0 -- At least one FALSE will override all TRUE.
• = 0 -- Majority wins. Any ties are broken with the last parameter in the hook call.

Each plugin registered on such a hook will receive the second paramter in the hook call in the core as its one and only parameter (this might be an array if multiple values need to be passed).

Read more about the boolean_hook_function() function in the 1.4 API documentation

List of hooks

This is a list of all hooks currently available in SquirrelMail, ordered by file.

TODO: Update this list. (especially in 1.5.2, we are removing a great number of hooks to be replaced with the template_construct_<template> hook)

TODO: For 1.5.2, the template_construct_<template> hook deserves special attention (explanation) below - briefly, plugins can add output in templates by hooking into the template_construct_<template file> hook -- the "template file" is the template file name that is to be modified by the plugin, and the plugin points of modification in that file are found by looking for "plugin_output" in the template code - e.g.: php if (!empty($plugin_output['menuline'])) echo $plugin_output['menuline']; ? The plugin can then add its output at the desired array index by returning it from the hook in a one-element array with the key being the desired "plugin_output" index in the template file and the value being the output: return array('menuline' => $output);

TODO: Reduce list of hooks by grouping them into separate chapters.

TODO: List is very out-of-synch with newest 1.5.2 and all its changes, as is the rest of the plugin documentation... much needs to be re-written

TODO: Even for 1.4.x, this list may no longer accurate

TODO: The hook explanations below this list are also out of date! Need to update!

% = This hook is used in multiple places in the given file
O = Optional hook provided by a particular plugin

& = See "Identity hooks" below
^ = See "Attachment hooks" below
* = See "Options" below
! = See "Compose form hook" below

The address book hooks

SquirrelMail 1.4.5 and 1.5.1 introduced two hooks that allow custom address book backends. These hooks are placed in functions/addressbook.php file. The abook_add_class hook is a simple hook designed to load custom address book classes before any other code is loaded. The abook_init hook allows to modify the $abook object that represents the configured address books. The hook is executed after the initiation of the local address book backends (file and DB based ones) and before the remote (LDAP) backend init. The second abook_init argument stores the address book object, and the third argument stores the return value of the $abook->add_backend() method.

The attachment hooks

When a message has attachments, this hook is called for each attachment according to its MIME type. For instance, a ZIP file will trigger a hook call to a hook named attachment application/x-zip. A plugin registered on such a hook typically will show a link to do a specific action, such as "Verify" or "View" for a ZIP file. Thus, to register your plugin for ZIP attachments, you'd do this in setup.php (assuming your plugin is called "demo"):

$squirrelmail_plugin_hooks['attachment application/x-zip']['demo'] =
    'demo_handle_zip_attachment';

This is a breakdown of the data passed in the array to the hook that is called:

[0] = An array of links for actions (see below) (alterable).
[1] = The message index of the first message on the message list page within
      which the current message is found (startMessage). Can be used herein
      for building URLs that point to the correct message list page.
[2] = The ID of the current message (id). Can be used herein to build URLs
      that point to the correct message.
[3] = The mailbox name, encoded with urlencode() (urlMailbox). Can be used
      herein to build URLs that point to the correct message list page.
[4] = The entity ID of the attachment inside the mail message (ent). Can
      be used herein to build URLs that point to the correct attachment.
[5] = The default URL to go to when the filename is clicked upon (alterable,
      but only one URL is allowed, thus, the last plugin to execute for
      the current attachment wins out - usually it's better to just add a
      new action to array element 1 above).
[6] = The filename that is displayed for the attachment.
[7] = The "where" criteria that was used to find the current message (where)
      (only applicable when the message was in fact found using a search).
      Can be used herein to build URLs that point to the correct message list
      page.
[8] = The "what" criteria that was used to find the current message (what)
      (only applicable when the message was in fact found using a search).
      Can be used herein to build URLs that point to the correct message list
      page.

To set up links for actions, add them to the array data passed in to the hook like this:

$args[0]['<plugin name>']['href'] = 'link URL';
$args[0]['<plugin name>']['text'] = _("Text to display");
$args[0]['<plugin name>']['extra'] =
    'extra stuff, such as an <img ...> tag (will be part of the clickable link)';

Note: The syntax of _("Text to display") is explained in the section about internationalization.

You can leave the text empty and put an image tag in extra to show an image-only link for the attachment, or do the opposite (leave extra empty) to display a text-only link.

It's also possible to specify a hook as "attachment type0/*", for example "attachment text/*". This hook will be executed whenever there's no more specific rule available for that type.

There is also an "attachment */*" hook for plugins that want to handle any and all attachments, regardless of their mime types. Please use conservatively.

Putting all this together, the demo_handle_zip_attachment() function should look like this (note how the argument is being passed):

function demo_handle_zip_attachment(&$args) {
    include_once(SM_PATH . 'plugins/demo/functions.php');
    demo_handle_zip_attachment_do($args);
}

And the demo_handle_zip_attachment_do() function in the plugins/demo/functions.php file would typically (but not necessarily) display a custom link:

function demo_handle_zip_attachment_do(&$args) {
    bindtextdomain('demo', SM_PATH . 'locale');
    textdomain('demo');

    $args[0]['demo']['href'] = sqm_baseuri() . 'plugins/demo/zip_handler.php?' .
        'passed_id=' . $args[2] . '&mailbox=' . $args[3] .
        '&passed_ent_id=' . $args[4];
    $args[0]['demo']['text'] = _("Show zip contents");

    bindtextdomain('squirrelmail', sqm_baseuri() . 'locale');
    textdomain('squirrelmail');
}

Note that the text domain has to be changed to properly translate the link text.

The file plugins/demo/zip_handler.php can now do whatever it needs with the attachment (note that the link will hand information about how to retrieve the source message from the IMAP server as GET varibles).

The compose form hook

The compose_form hook allows plugins to insert their own code into the form tag for the main message composition HTML form. Usually plugins will want to insert some kind of code in an onsubmit event handler. In order to allow more than one plugin to do so, all plugins using this hook to add some onsubmit code need to add that code (without the enclosing attribute name and quotes) as a new array entry to the global $compose_onsubmit array. The code should use "return false" if the plugin has found a reason to stop form submission, otherwise it should do nothing (that is, please do not use "return true", as that will prevent other plugins from using the onsubmit handler). SquirrelMail itself will insert a final "return true". All onsubmit code will be enclosed in double quotes by SquirrelMail, so plugins need to quote accordingly if needed. For example:

global $compose_onsubmit;
$compose_onsubmit[] = ' if (somevar == \'no\') return false; ';

Note the escaped single quotes. If you use double quotes, they would have to be escaped as such:

global $compose_onsubmit;
$compose_onsubmit[] = ' if (somevar == \'no\') { alert(\\"Sorry\\"); return false; }';

Any other form tag additions by a plugin (beside onsubmit event code) can currently be echoed directly to the browser.

The configuration testing hook

SquirrelMail has a script called configtest.php which can be used to test the SquirrelMail configuration. Since SquirrelMail 1.5.2, the configtest script includes the configtest hook. The hook uses the boolean hook function call. Plugins that are attached to this hook should return a boolean TRUE if they detect any errors in the plugin's configuration. Verbose messages can be printed with a do_err('error message', FALSE) function call or with any standard PHP inline output function.

The configtest script is executed in an anonymous, unauthenticated environment, so username and password information isn't available as it would be in all other SquirrelMail scripts. Only a limited set of functions are loaded. The do_err() function is a special configtest script function, which is used to print error messages. If a plugin uses the do_err() function, it is recommended to set the second function argument to FALSE even on fatal errors. The configuration testing will stop on a fatal error, that is, if the hook call returns a boolean TRUE, and it's best to let the script continue checking for other system configuration problems.

The identity hooks

This set of hooks allows plugins to add options to the SquirrelMail identity preferences.

This set of hooks is passed special information in the array of arguments:

options_identities_process

This hook is called at the top of the "Identities" page, which is most useful when the user has changed any identity settings. This is where you'll want to save any custom information you are keeping for each identity or catch any custom submit buttons that you may have added to the identities page. In SquirrelMail 1.4.4 or older, and in 1.5.0, the arguments to this hook are:

[0] = hook name (always "options_identities_process")
[1] = should I run the <tt/SaveUpdateFunction()/ (alterable)

By default, SaveUpdateFunction() isn't called. If you want to trigger it, you have to set the second array element to 1 or TRUE.

Since SquirrelMail 1.4.6 and 1.5.1, the arguments to this hook are:

[0] = hook name (always "options_identities_process")
[1] = action (hook is used only in 'update' action and any custom
      action added to form with option_identities_table and
      option_identities_buttons hooks)
[2] = processed identity number

This hook isn't available in SquirrelMail 1.4.5.

options_identities_renumber

This hook is called when one of the identities is being renumbered. If a user has three identities and deletes the second, this hook would be called with an array that looks like this: ('options_identities_renumber', 2, 1). The arguments to this hook are:

[0] = hook name (always "options_identities_renumber")
[1] = being renumbered from ('default' or 1 through (# idents) - 1)
[2] = being renumbered to ('default' or 1 through (# idents) - 1)

This hook isn't available in SquirrelMail 1.4.5, and the renumbering order differs since 1.4.5 and 1.5.1.

options_identities_table

This hook allows you to insert additional rows into the table that holds each identity. The arguments to this hook are:

[0] = additional HTML attributes applied to table row.
      use it like this in your plugin:
         <tr "<?php echo $args[0]; ?>">
[1] = is this an empty section (the one at the end of the list)?
[2] = what is the 'post' value? (ident # or empty string if default)

You need to return any HTML you would like to add to the table. You could add a table row with code similar to this:

function demo_identities_table(&$args) {
    return '<tr><td>&nbsp;</td><td>' .
        'YOUR CODE HERE' . '</td></tr>' . "\n";
}

The first hook argument was modified in 1.4.5 and 1.5.1. In SquirrelMail 1.4.1--1.4.4 and 1.5.0, the argument only contains the background color. You should use <tr> in these SquirrelMail versions.

options_identities_buttons

This hook allows you to add a button (or other HTML) to the row of buttons under each identity. The arguments to this hook are:

[0] = is this an empty section (the one at the end of the list)?
[1] = what is the 'post' value? (ident # or empty string if default)

You need to return any HTML you would like to add here. You could add a button with code similar to this:

function demo_identities_button(&$args) {
    return '<input type="submit" name="demo_button_' . $args[1] .
        '" value="Press Me" />';
}

Since SquirrelMail 1.4.6 and 1.5.1, the input element should use a smaction[action_name][identity_no] value in the name attribute if you want to process your button actions in the options_identity_process hook.

See sample implementation of identity hooks in the SquirrelMail demo plugin.

svn co https://squirrelmail.svn.sourceforge.net/svnroot/squirrelmail/trunk/squirrel