Compatibility plugin for SquirrelMail
=====================================
Ver 2.0.6, 2007/01/17

Original author: Paul Lesneiwski <paul@squirrelmail.org>
Original idea: Bruce Richardson <itsbruce@uklinux.net>



Description
===========

This plugin allows any other plugin access to the functions
and special variables needed to make it backward (and forward) 
compatible with most versions of SM in wide use.  This eliminates 
the need for duplication of certain functions throughout many plugins.

It also provides functionality that helps check that plugins 
have been installed and set up correctly.



License
=======

This plugin is released under the GNU General Public 
License (see the file COPYING for details).



Requirements
============

  * None



Help Requests
============= 
      
Help requests are welcome at my personal email address, but I
request that you first post to the SquirrelMail Plugins mailing
list, where you'll get faster help from more people and other
people with the same problem will be able to see how your issue
was resolved.  If you don't get good answers that way, you may
try emailing me directly.

Info about the SquirrelMail Plugins mailing list can be found
on the SquirrelMail web site.  It is currently located at:

http://lists.sourceforge.net/mailman/listinfo/squirrelmail-plugins
squirrelmail-plugins@lists.sourceforge.net



Usage (Plugin Authors' Guide)
=============================

As of version 2.0 of this plugin, no special action is required
on the part of plugin developers to make their plugin backward
compatible via the Compatibility Plugin.  However, any custom option
pages provided by a plugin should always start with the following
code:


   if (file_exists('../../include/init.php')) 
      include_once('../../include/init.php');
   else if (file_exists('../../include/validate.php')) 
   {
      define('SM_PATH', '../../');
      include_once(SM_PATH . 'include/validate.php');
   } 
   else 
   {
      chdir('..');
      define('SM_PATH', '../');
      include_once(SM_PATH . 'src/validate.php');
   }


Otherwise, developers should just use the most up-to-date SquirrelMail 
API and expect that their plugins will in most cases work with most
versions of SquirrelMail as long as users of older versions have 
downloaded this plugin and added its patch if necessary.  If a 
function is found that a certain plugin uses that is not included 
in the Compatibility Plugin, please ask to have it added.  

Authors who want to avoid getting support requests for simple setup
problems (such as when the person installing the plugin neglects to 
create a configuration file) can use one of these functionalities:

   load_config('my_plugin', array('config.php'));

   check_plugin_setup('my_plugin', array('config.php'));

The first of these functions will load (include) any and all 
configuration files given (in the order given) and will trigger an 
error (that is a bit more helpful for novice administrators who can't 
find or understand PHP errors) if none of them are found.

The second function checks for the existence of any configuration 
files you specify (it does not load (include) them, however - this
function is only intended as a configuration test.  It can be handy
in combination with the "configtest" hook which is available in 
SquirrelMail 1.5.2 and above.

The first parameter for both of these functions is the name of the 
plugin as it is known to SquirrelMail (the plugin's directory name).  
The second parameter is an array of any number of files, relative to 
the plugin's directory (or a full path, if it starts with a forward
slash, such as "/var/lib/squirrelmail/config/myplugin.conf").  Any 
number of files may be named here.  Another example for each: 

   load_config('my_plugin', array('data/config-default.php', 'data/config.php'));

   check_plugin_setup('my_plugin', array('data/config.php', 'data/admins.php'));

Note that load_config() is designed to allow you to do things such
as include a default configuration in case the administrator did
not create her own configuration file, or to include a full set of
default configuration settings, and another file that contains just
a sub-set thereof, etc.  Keep in mind that files are loaded/included
in the order given.

Note that check_plugin_setup() is best placed somewhere where it will 
not run frequently, since it is only really needed once (thus, in 
SquirrelMail versions 1.5.2 and above, use it with the "configtest" 
hook).  You may turn off that function by changing the 
$disable_config_check at the top of the functions.php file in the 
Compatibility Plugin.

There are also some advanced utility functions for use by plugins needing
to add, remove or re-order other plugins (or themselves) called add_plugin(),
remove_plugin(), get_current_hook_name() and reposition_plugin_on_hook().
Plugin authors needing to use these should read the function documentation
in the functions.php file in the Compatibility plugin directory.



TODO
====

  * sqsetcookie probably will break some plugins, since I'm not sure
    where the flush is happening in 1.5.1 and if it's being backported
    correctly.  should fix this or make sure it's not a problem
    (hrmph, seems to work fine for multilogin, sooo....)

  * Add broader functionality to help plugins diagnose 
    other setup/install issues?  such as what?  checking
    certain variables in the config files?...

  * Add functionality to auto-define SM_PATH?  I have
    run into real sticky issues with this and prefer to
    leave it out of this plugin... too many variables...
    but would be nice to remove this responsibilty from
    plugin authors
    Possible algorightm: 
       - globalize and check if $compatibility_sm_path is already available
       - if so, use it, define SM_PATH with it if not done already
       - iterate through getcwd contents, taking off chunks until one
         of the known SM directories is found (plugins, src, functions, include, 
         class, etc)
       - define SM_PATH and $compatibility_sm_path
       - chdir to plugins or SM_PATH dir??? (see below)
    Come to think of it, why doesn't validate.php just take 
    care of this?  Not sure it is appropriate there, but 
    maybe a plugin config file would be good (that's almost
    what this is becoming... which is handy but not sure if
    all the extra work and abstraction is worth it, at least
    from a performance angle - all we gain is allowing plugin
    authors to be dumber.  and are they that dumb?!?  ;>

  * Add functionality to auto-chdir if needed?  we are
    trying to avoid this altogether (and in fact in SM
    1.3 and up we have, unless a plugin is really whacked)
    so this is only useful for 1.2... hmmm... thing is 
    that I ran into some weird situations with plugins
    clashing with one another (address_add was one 
    very problematic one) unless some chdir'ing was done.
    again, it'd be nice to pull all this out of plugin
    author hands so it'll actually work, but it could be
    a little messy, and might need to be version dependent
    code (esp 1.2?)
    The address_add thing is a good example of how messy
    things can be... it is called by code executing somewhere
    in the src directory, so chdir'ing at that time can be
    disasterous

  * Checking for config files and whatnot should be
    moved to the configuration-time code in new SquirrelMail
    versions; it is pointless to do this every time the
    plugin is used



Change Log
==========

  v2.0.6 2007/01/17
    * Fixed issues from the last release: eval code return bug 
      that showed only under 1.5.1 and PHP notice issue when 
      used with the Multilogin plugin under 1.4.x.

  v2.0.5 2007/01/14
    * Revamped legacy mechanism; cleaned up include files and
      included functions (as mentioned in the README, if plugin
      authors find functions they need for better compatibility,
      please get in touch)
    * Added missing include in the case of errors in load_config
    * Added get_current_hook_name(), add_plugin(), remove_plugin()
      and reposition_plugin_on_hook() functions
    * Remove use of SM_PATH in functions file in case it is not
      available
    * load_config() and check_plugin_setup() can now also return 
      after an error to allow the caller to handle the error
    * Added patches through SquirrelMail version 1.4.9 and 1.5.0
      (Compatibility plugin is natively loaded in 1.5.1 and up)

  v2.0.4 2005/11/11
    * Sorry, folks.  Changed the location of the compatibility patch
      again.  When upgrading to this version, you *MUST* remove the
      patch from version 2.0.3 (to do so, just re-run the patch for
      that version *BEFORE* you unpack and install this version).
      As with before, patches from version 2.0.2 or previous will do
      no harm if left in place.  If you are using version 2.0.3,
      upgrade is especially recommended.

  v2.0.3 2005/10/24
    * Changed the location of the compatibility patch.  Everyone
      upgrading to this version will need to re-run the patch!
      The old compatibility patch becomes obsolete, but it does
      not hurt anything to be left in place.

  v2.0.2 2005/10/19
    * Added load_config function for use by other plugins
    * Added new sqsetcookie and sqsession_start functions to includes
    * Added new checkForJavascript function to includes

  v2.0.1 2005/07/14
    * Documentation change (plugins *never* need to include
      Compatibility directly)
    * Added 1.4.6 includes directory
    * Added is_plugin_enabled() up to 1.4.5 and 1.5.0

  v2.0 2005/06/16
    * Reorganized code so that plugin authors do not need
      to specifically use "compatibility_" functions.
    * Changed compatibility_check_plugin_setup() to check_plugin_setup()
 
  1.3 - Paul Lesneiwski <paul@squirrelmail.org>
   * Added compatibility_check_plugin_setup() that helps verify that
     a plugin has been installed and set up correctly
   * Added new $compatibility_sm_path variable for easier plugin coding...
   * Updated for compatibility (!) with new version reporting API

  1.2 - Paul Lesneiwski <paul@squirrelmail.org>
   * Fix for theme problem with plugins under SM 1.4

  1.1 - Paul Lesneiwski <paul@squirrelmail.org>
   * Some applications of this plugin were experiencing
     unusual include order, so added includes of the
     global.php and strings.php files to be safe.
   * Even though older versions of SquirrelMail have
     some of the functions that this plugin duplicates,
     because they have session issues, the compatibility
     version of those functions now takes precedence over
     older SquirrelMail core code.

  1.0 - Paul Lesneiwski <paul@squirrelmail.org>
   * Initial release
