Compatibility plugin for SquirrelMail ===================================== Ver 2.0.14, 2009/01/01 Copyright (c) 2004-2009 Paul Lesniewski <paul@squirrelmail.org> 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). Donations ========= If you or your company make regular use of this software, please consider supporting Open Source development by donating to the authors or inquire about hiring them to consult on other projects. Donation/ wish list links for the author(s) are as follows: Paul Lesniewski: https://sourceforge.net/donate/index.php?user_id=508228 Requirements ============ * None Troubleshooting =============== * If you experience errors that look similar to the following: Fatal error: Call to undefined function php_self() in .../compatibility/includes/1.5.0/global.php on line 25 You have a plugin installed that requires version 1.x of the Compatibility plugin. There is a list of plugins that have this requirement here: http://www.squirrelmail.org/wiki/CompatibilityDependencies Note that you generally cannot use plugins that require Compatibility 1.x with ones that require Compatibility 2.x. The best approach to solving this problem is to contact the plugin author of the outdated plugin and work with them to update that code. Help Requests ============= Before looking for help elsewhere, please try to help yourself: * Read the Troubleshooting section herein. * Look to see if others have already asked about the same issue. There are tips and links for the best places to do this in the SquirrelMail mailing list posting guidelines: http://squirrelmail.org/wiki/MailingListPostingGuidelines You should also try Google or some other search engine. * If you cannot find any information about your issue, please first mail your help request to the squirrelmail-plugins mailing list. Information about it can be found here: http://lists.sourceforge.net/mailman/listinfo/squirrelmail-plugins You MUST read the mailing list posting guidelines (see above) and include as much information about your issue (and your system) as possible. Including configtest output, any debug output, the plugin configuration settings you've made and anything else you can think of to make it easier to diagnose your problem will get you the most useful responses. Inquiries that do not comply with the posting guidelines are liable to be ignored. * If you don't get any replies on the mailing list, you are welcome to send a help request to the authors' personal address(es), but please be patient with the mailing list. 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 pages (such as option pages) provided by a plugin should always start with the following code: // set up SquirrelMail environment // 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'); } // make sure plugin is activated! // global $plugins; if (!in_array('plugin_name', $plugins)) exit; 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 applied 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.4.10 and above and 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.4.10 and 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. A function called check_file_contents() is also available for plugins that would like to check if the SquirrelMail source code has been properly patched if needed by that plugin. See that function's documentation in the functions.php file for more information if needed. 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.14 2009/01/01 Paul Lesniewski <paul@squirrelmail.org> * Added is_ssl_secured_connection() * Added sq_is_writable() * Added sq_create_tempfile() * Added get_process_owner_info() * Update with changes in sqsetcookie() and that it was added to 1.4.16 v2.0.13 2008/07/26 Paul Lesniewski <paul@squirrelmail.org> * Synchronized sq_send_mail() and sqauth_save_password() with changes in SquirrelMail * Synchronized get_plugin_requirement() with changes in SquirrelMail v2.0.12 2008/05/21 Paul Lesniewski <paul@squirrelmail.org> * Added set_uri_vars() * Added check_file_contents() * Added $load_only_one to load_config() * Added include directories for 1.4.15 and 1.4.16 * Added lame-duck stand-in for ngettext() when needed under SquirrelMail versions less than 1.5.1 that are not running at least PHP 4.2.0 with the gettext extension v2.0.11 2008/02/29 Paul Lesniewski <paul@squirrelmail.org> * Moved sq_send_mail(), since it was added to SM core * Added debug constants from 1.5.2 v2.0.10 2008/01/12 Paul Lesniewski <paul@squirrelmail.org> * Note that SquirrelMail 1.4.13+ (as well as 1.5.1+) no longer requires a source patch. * Added sq_call_function_suppress_errors() * Added get_secured_config_value() * Added get_smtp_user() * Added sq_send_mail() v2.0.9 2007/07/12 Paul Lesniewski <paul@squirrelmail.org> * Synchronize with addition of sqauth_read_password() to SM 1.4.11 * Improve get_current_hook_name() function in SM 1.5.1+ (no need to upgrade except for use with SM 1.5.1+) * Removed sq_popen() and family v2.0.8 2007/04/17 * Fix mistyped function call, which should not have shown up unless using old or broken setups. Thanks to Yoshinori Mamoto. * Fixed sqm_baseuri() location change that creates bug for versions 1.4.5 and below * Added sq_popen() and family * Added list_files() v2.0.7 2007/04/05 * Added sqauth_save_password() and sqauth_read_password() from 1.5.1 to compatibility library * Added documentation note that plugin authors should not use checkForJavascript() under 1.4.x * Added get_plugin_version(), updated check_plugin_version() * Added sq_htmlspecialchars() * Added sq_change_text_domain() * Added get_plugin_requirement() * Added get_plugin_dependencies(), check_plugin_dependencies() * Changed internal legacy inclusion mechanism for better organization and easier maintenance * Adjusted for new SM_VERSION constant in SM 1.5.2 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 Lesniewski <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 Lesniewski <paul@squirrelmail.org> * Fix for theme problem with plugins under SM 1.4 1.1 - Paul Lesniewski <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 Lesniewski <paul@squirrelmail.org> * Initial release