Compatibility plugin for SquirrelMail
=====================================
Ver 1.3, 09/15/03

Original author: Paul Lesneiwski <pdontthink@angrynerds.com>
Original idea: Bruce Richardson <itsbruce@uklinux.net>



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

This plugin allows any other plugin access to the functions
and special variables (SM_PATH) 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.



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

Currently, some of the functions that may or may not be available 
to you when coding a plugin targeted at as wide a SquirrelMail 
user base as possible include:

   check_sm_version();
   check_php_version();
   sqsession_register();
   sqsession_unregister();
   sqsession_is_registered();
   sqsession_is_active();
   sqgetGlobalVar();  (previously known as sqextractGlobalVar();)

This plugin provides backups for those functions, so you may
always assume that they are available.  In order to make use
of them, you must change you function calls as such:

   compatibility_check_sm_version();
   compatibility_check_php_version();
   compatibility_sqsession_register();
   compatibility_sqsession_unregister();
   compatibility_sqsession_is_registered();
   compatibility_sqsession_is_active();
   compatibility_sqextractGlobalVar();)

You must also make sure to include this plugin's functions.php
file as below:

   <?php

      // include compatibility plugin
      //
      if (defined('SM_PATH'))
         include_once(SM_PATH . 'plugins/compatibility/functions.php');
      else if (file_exists('../plugins/compatibility/functions.php'))
         include_once('../plugins/compatibility/functions.php');
      else if (file_exists('./plugins/compatibility/functions.php'))
         include_once('./plugins/compatibility/functions.php');


      function pluginname_compose_bottom_do()
      {


         // your code here


         // example of how to get a variable POSTed to this
         // last page request or retrieve a variable from
         // the current session
         // 
         global $myvar;
         compatibility_sqextractGlobalVar('myvar');


         // example of how to include another file
         //
         if (compatibility_check_sm_version(1, 3))
            include_once (SM_PATH . 'plugins/pluginname/config.php');
         else
            include_once ('../plugins/pluginname/config.php');


         // example of how to register a variable
         // in the current session 
         //
         $myothervar = 'some_value';
         compatibility_sqsession_register($myothervar, 'myothervar');


      }

   ?>



Also provided is a variable called $compatibilty_sm_path, which can
be used to prefix all file system paths in your code.  It will 
automatically be set to point to the main SquirrelMail directory,
so your includes and other file system references will be correct
no matter what SquirrelMail version is being used.  This is the same
as using SM_PATH in SquirrelMail versions 1.3 and greater, but will
also work against older versions as well.

Remember to global-ize it first, then you can use it as needed:

   global $compatibility_sm_path;

Example uses:

   include_once ($compatibility_sm_path . 'plugins/my_plugin/config.php');

   $cmd = $compatibility_sm_path . "plugins/my_plugin/myExecCommand $param1 $param2";
   exec($cmd, $output, $retVal);



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 this functionality:

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

This function checks for the existence of any files you tell it to.
The first parameter 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.  Any number of files
may be included here.  Another example: 

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

Note that this code is best placed somewhere where it will not run 
frequently, since it is only really needed once.  You may turn off this
function by changing the $disable_config_check at the top of the 
functions.php file in the Compatibility Plugin.  This functionality
is subject to (possibly radical) change in the future.



Although not directly related to this plugin, note that the 
advised format of a plugin's setup.php should be:

   <?php
          function squirrelmail_plugin_init_pluginname()
          {
             global $squirrelmail_plugin_hooks;

             $squirrelmail_plugin_hooks['compose_bottom']['pluginname']
                = 'pluginname_compose_bottom';
          }

          if (!defined('SM_PATH'))
             define('SM_PATH', '../');

          function pluginname_compose_bottom()
          {
             include_once(SM_PATH . 'plugins/pluginname/functions.php');
             pluginname_compose_bottom_do();
          }
   ?>

The goal is to keep setup.php as brief as possible.  This also
allows you to break up your code into logical chunks.  Please 
see doc/plugin.txt for more about plugin development and 
standardization.



TODO
====

  * 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
==========

  1.3 - Paul Lesneiwski <pdontthink@angrynersd.com>
   * 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 <pdontthink@angrynersd.com>
   * Fix for theme problem with plugins under SM 1.4

  1.1 - Paul Lesneiwski <pdontthink@angrynersd.com>
   * 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 <pdontthink@angrynersd.com>
   * Initial release
