User Information plugin for SquirrelMail
========================================
Ver 1.0, 2009/01/01


Copyright (c) 2008-2009 Paul Lesniewski <paul@squirrelmail.org>



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

This plugin provides an extensible set of data about the
current user such as IP address, browser type and version,
possibly their country, etc., mainly for use by other plugins.



License
=======

This plugin is released under the GNU General Public
License (see 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
============

 * SquirrelMail 1.4.0 or above



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

This plugin is primarily intended for use by other plugins as
a central location for access to data describing the user's
environment, location, etc.  The API for this plugin consists
of a single entry point, which returns a list of attributes
that are known about the current user.  It is typically
accessed as such:

   if (file_exists(SM_PATH . 'plugins/user_info/functions.php'))
   {
      include_once(SM_PATH . 'plugins/user_info/functions.php');
      $user_info = get_user_info();

      // do something with user information attributes here...

      // $user_info is a typical key-value array with keys
      // named "ip_address", "username", "browser_type",
      // "browser_version", and possibly other things
      // depending on what modules you may have added
      // to the User Information plugin (for example, the
      // example in the "contrib" directory will add
      // "country_code" and "country_name" to that list)

   }

Adding modules to this plugin to augment the user information
is accomplished by defining a module in the $user_info_modules
setting in the configuration file.  A module is defined by
telling this plugin where to find a callback function for your
module (the full file path of a file to include and the name
of a PHP function to call):

$user_info_modules = array(
   'ip-to-country' => array(
      'file' => '/usr/share/ip_address_lookups/lookup_country_by_ip_address.php',
      'function' => 'lookup_country_by_ip_addr',
   ),
);

The callback function will be given the current user information
array as explained above.  That function can then use the data
therein if needed to retreive new data about the user.  That data
should then be returned in the same format, ready to be appended
to the user information array.

For an exmple, see the lookup_country_by_ip_address.php file in
the "contrib" directory herein.  It uses a Pear DB database
lookup to try to determine what country the user is located in.
It has a few simple configuration settings you can change to use
it in your environment.  If you decide to use that file, you
should move it to somewhere more appropriate (especially because
when you upgrade this plugin in the future, any changes you make
to that file will be lost).



Troubleshooting
===============

  * If changes to the configuration file don't seem to be showing
    in the user interface, ensure that you are editing the correct
    configuration file.  If one is located in the main SquirrelMail
    config directory (named "config_user_info.php"), it will always
    be used.  Otherwise, "config.php" in the user_info plugin
    directory will be used.

  * When attempting to debug problems with this plugin, especially
    with new modules you are adding, it can be helpful to activate
    this plugin in the SquirrelMail configuration and run the
    SquirrelMail configuration check:
       http://example.org/squirrelmail/src/configtest.php



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.



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

  v1.0  2009/01/01  Paul Lesniewski <paul@squirrelmail.org>
   * Initial version

