Subversion Repositories Applications.papyrus

Creating Modules for Phorum5

============================

This document describes the Phorum5 module system. It is targeted at

developers who want to do customization and extend the functionality

of Phorum5. Modules are the preferred way to archieve this in

Phorum5.

For much of this document, we will be talking about an example module

"foo". Of course you will not name your module "foo", but something much

more appropriate. If you're not familiar with the terms "foo" and "bar",

you can visit http://en.wikipedia.org/wiki/Metasyntactic_variable

Be sure to read at least the **CAUTIONS AND SECURITY ISSUES** section,

before making your own modules.

Table of contents:

1. Introduction

   1.1 Modules

   1.2 Hacks

   1.3 Hooks

2. Creating your own modules

   2.1 What modules are built of

       2.1.1 Hook functions

       2.1.2 Module information

       2.1.3 Other "stuff"

   2.2 Module structure

       2.2.1 Single file modules

       2.2.2 Multiple file modules

   2.3 Supporting multiple languages

   2.4 Storing message data

       2.4.1 From hooks that are run before saving a message to the database

       2.4.2 From other hooks

   2.5 Storing user data

   2.6 Creating custom URLs

   2.7 Implementing settings for your module

   2.8 Changing the template

   2.9 Example modules

3. **CAUTIONS AND SECURITY ISSUES**

   3.1 Make modules, not hacks

   3.2 Reload your module if you change the module information

   3.3 How to access the $PHORUM array from your hook functions

   3.4 How to access additional files in your multi file module

   3.5 Secure your PHP files agains hackers

   3.6 Secure your pages from XSS

   3.7 Prevent namespace collisions

       3.7.1 (Hook) functions

       3.7.2 Data stored in $PHORUM

       3.7.3 Language strings stored in $PHORUM

       3.7.4 Data stored in messages, users and settings

4. Overview of available Phorum hooks

   4.1 Code hooks

   4.2 Template hooks

5. Support

1. Introduction

-------------------------------------------------------------------------------

 1.1 Modules

 -----------

   Modules are self contained pieces of software, that can be added to

   Phorum to change or extend its functionality. Modules can do this

   without having to change anything in the standard Phorum distribution

   files or database structure. So installing a module means: drop in

   the code, go to the admin "Modules" page, enable the module and it

   works.

 1.2 Hacks

 ---------

   The moment it is neccessary to make changes to the standard Phorum

   distribution files or database structure to implement some kind of

   functionality, we're talking about a hack (even if the changes

   that have to be made are accompanied by a drop in module).

   Although there is nothing wrong with writing hacks, the Phorum team

   wants to urge you to try if you can write a module before resorting

   to a hack. Modules are the preferred way of modifying Phorum

   functionality, because that will make both upgrading your distribution

   and having your modification adopted by others easier.

 1.3 Hooks

 ---------

   Phorum uses hooks to run its modules. Hooks are points in the

   application where Phorum stops and runs its data through the modules

   that are configured to handle the hook. The modules can act upon and

   change this data.

   The following image visualizes what happens when Phorum reaches

   a hook point in the application, for which two modules ("foo" and

   "bar") have been configured.

     Phorum

   Application

       (1)                                (1) Phorum is running.

        |                                 (2) Phorum reaches the

        |                                     hook named "some_hook".

        v           Phorum                (3) Phorum sends data to

    some_hook >----- data ------+             the module system.

       (2)            (3)       |         (4) The module "foo" is run.

                                v         (5) The module "bar" is run.

                       (4) module "foo"   (6) The Phorum data (which

                                |             might be modified by the

                                v             modules) is sent back

                       (5) module "bar"       to Phorum.

                                |         (7) Phorum continues running

     Phorum        Modified     |             with the modified data.

   Application <---- data ------+

       (7)            (6)

        |

        |

        v

2. Creating your own modules

-------------------------------------------------------------------------------

 2.1 What modules are built of

 -----------------------------

  2.1.1 Hook functions

  --------------------

   A module contains one or more PHP functions that act as hook

   functions. Hook functions will receive some data in a variable

   from Phorum and have to return the (possibly modified) data, which

   will then go either back to Phorum or to the input of another module

   which also handles the same hook (see 1.3). So the most basic (and

   useless :-) hook function you could write would look somewhat like this

   (see 3.7 for an explanation of the naming of the function):

      function phorum_mod_foo_some_hook ($data) {

          return $data;

      }

   The exact nature of the data that is sent to the hook functions

   depends solely on the hook that is run. In chapter 4 of this document

   you will find a description of all supported hooks, including a

   specification of the type of data that is sent.

  2.1.2 Module information

  ------------------------

   For each hook that you want to handle in your module, you will have

   to point the module system to the function in your module that will

   handle the hook. Together with some other information, used for

   describing the module, this is stored in the module information.

   The module information acts as the glue between Phorum and your

   module.

   Module information is formatted using lines of plain text. Each line

   contains a bit of information about the module. The general format

   of the lines in the module information is:

      <type>: <data>

   Here is a list of the types that can be used:

   +--------+-----------------------------------------------------------+

   | <type> | <data>                                                    |

   +--------+-----------------------------------------------------------+

   | title  | This is the title for the module that is displayed in the |

   |        | "Modules" page of the admin interface.                    |

   +--------+-----------------------------------------------------------+

   | desc   | This is the description that is displayed along with the  |

   |        | title in the admin interface, to give a little more       |

   |        | information about the module. Using HTML in the <data>    |

   |        | part is allowed.                                          |

   +--------+-----------------------------------------------------------+

   | hook   | This describes which hook functions are called for which  |

   |        | Phorum hooks. The data consists of two fields, separated  |

   |        | by a pipe "|" symbol. The first field contains the name   |

   |        | of the hook that this module is hooking into. The second  |

   |        | field contains the name of the hook function that will be |

   |        | called for the hook.                                      |

   +--------+-----------------------------------------------------------+

   It is allowed to use multiple hook lines in your module information,

   so your module can hook into multiple hooks. When doing this, it

   is also allowed to use the same hook function for handling different

   hooks in your module (asuming the hooks are compatible).

   Here's an example of what the module information for our example

   module "foo" might look like:

      title: Foo example module

      desc: This is the Foo module for Phorum. Nothing exciting...

      hook: some_hook|phorum_mod_foo_some_hook

      hook: some_other_hook|phorum_mod_foo_some_other_hook

      hook: yet_another_hook|phorum_mod_foo_some_other_hook

   So what this module info for example does, is telling Phorum that

   when it gets to "some_other_hook", it will have to call the function

   phorum_mod_foo_some_other_hook() in your module. It also tells

   that for "yet_another_hook" the same function has to be called.

  2.1.3 Other "stuff"

  -------------------

   Hook functions and the module information are all the parts needed

   for creating a working module. However, your module might need

   extra stuff like template, language and image files. You can

   store these files along with your module when using the multiple

   file module structure (see 2.2.2 below).

   If you do not need to store any other stuff with your module, you

   can also choose to use the single file (see 2.2.1 below) module

   structure.

 2.2 Module structure

 --------------------

  2.2.1 Single file modules

  -------------------------

   Single file modules are useful in case case no additional files have

   to be distributed with your module. Because the module consist of

   only one single file, it is very easy to distribute. Beware that the

   moment you want to support for example a settings screen, multiple

   languages or custom images, you will have to switch to the multiple

   file module structure.

   Single file modules consist of one single PHP file, which contains

   both the module information and the hook functions. For storing the

   module informaton, a special PHP comment is used. This comment must

   look like the following:

      /* phorum module info

      <module information lines go here>

      */

   Using the example module info from 2.1.2, the complete single

   file module would look like this (see 3.5 why we use the

   check on PHORUM at the start of this file):

      <?php

      if(!defined("PHORUM")) return;

      /* phorum module info

      title: Foo example module

      desc: This is the Foo module for Phorum. Nothing exciting...

      hook: some_hook|phorum_mod_foo_some_hook

      hook: some_other_hook|phorum_mod_foo_some_other_hook

      hook: yet_another_hook|phorum_mod_foo_some_other_hook

      */

      function phorum_mod_foo_some_hook ($data) {

          // Do stuff for "some_hook".

          return $data;

      }

      function phorum_mod_foo_some_other_hook ($data) {

          // Do stuff for "some_other_hook" and "yet_another_hook".

          return $data;

      }

      ?>

   Installation of a single file module is done by putting the PHP

   file (e.g. foo.php) directly in the directory {phorum dir}/mods/

   and activating the module from the "Modules" screen in your

   admin interface.

  2.2.2 Multiple file modules

  ---------------------------

   Multiple file modules are useful in case you need additional files

   to be stored with your module, for example a settings screen,

   language files or custom images.

   Multiple file modules are stored in their own subdirectory below

   the directory {phorum dir}/mods/. So if you have a module named

   "foo", you will have to create a directory {phorum dir}/mods/foo/ for

   storing all module files.

   Inside this subdirectory, you will have to create a least two files.

   The first is a file called "info.txt". This file contains the

   module information for your module (see 2.1.2). The second file

   is the PHP file which contains the hook functions for your module.

   The basename of this file should be the same as the name of the

   module subdirectory. So for our example module "foo", you will have

   to create a file named "foo.php".

   Using the example module info from 2.1.2, the complete multiple

   file module would look like this (see 3.5 why we use the

   check on PHORUM at the start of the PHP file):

   info.txt:

      title: Foo example module

      desc: This is the Foo module for Phorum. Nothing exciting...

      hook: some_hook|phorum_mod_foo_some_hook

      hook: some_other_hook|phorum_mod_foo_some_other_hook

      hook: yet_another_hook|phorum_mod_foo_some_other_hook

   foo.php:

      <?php

      if(!defined("PHORUM")) return;

      function phorum_mod_foo_some_hook ($data) {

          // Do stuff for "some_hook".

          return $data;

      }

      function phorum_mod_foo_some_other_hook ($data) {

          // Do stuff for "some_other_hook" and "yet_another_hook".

          return $data;

      }

      ?>

   So far, the module has exactly same functionality as the single

   file module from 2.2.1. From here on, the functionality can be

   extended. Some of the possibilities are:

   - Using custom files for your module (images, classes, libs, etc.);

   - Letting your module support multiple languages;

   - Creating a settings screen for your module;

 2.3 Supporting multiple languages

 ---------------------------------

   (this feature is only available for the multiple file module structure)

   If your module includes text that will be displayed to end users,

   you should strongly consider making it support multiple languages.

   This will allow Phorum installations using another language to display

   output of your module in the same language, instead of the language

   you have written the module in.

   For supporting multiple languages, the first thing to do is add the

   following to your module information file (info.txt):

      hook: lang|

   There is no hook function configured here, because the "lang" hook

   is only used as a marker for Phorum. This only tells Phorum that your

   module supports multiple languages.

   Next, you must provide at least one language file with your module.

   Language files are stored in a subdirectory name "lang" inside your

   module directory. So in our sample module, the full directory would be

   {phorum dir}/foo/lang/. The language files must be named identical

   to the main language files that Phorum uses. So, to include both

   English and French, your module would have the following file

   structure below the Phorum's mods directory:

      foo/info.txt

      foo/foo.php

      foo/lang/english.php

      foo/lang/french.php

   The structure of your language files will be almost identical to that

   of the main Phorum language files. However, for your own language files

   it is advisable to add an extra level in the language variables, to

   avoid conflicts with other modules or Phorum itself. Here is an

   example of how you would do that:

      <?php

      $PHORUM["DATA"]["LANG"]["mod_foo"]["Hello"] = "Hello!";

      ?>

   Here, the extra inserted level is ["mod_foo"]. You can add as many

   lines as you need for your module. To access the above language string,

   from your module code you would use:

      $PHORUM["DATA"]["LANG"]["mod_foo"]["Hello"]

   From a template file, you would use:

      {LANG->mod_foo->Hello}

   In case a Phorum installation is using a language that your module

   does not support, Phorum will automatically attempt to fallback to

   English. So it is highly recommend that you include an english.php

   language file in all your modules. If both the current language and

   english.php are not found, Phorum will be unable to load a language

   for your module and will display empty space instead of language

   strings.

   Try to reuse strings that are already in the main Phorum language

   files itself. Only create custom strings when there is no alternative

   available. Having more text to translate is more work for everybody,

   especially the Phorum translators.

 2.4 Storing message data

 ------------------------

   If your module needs to store data along with a Phorum message,

   you can make use of the meta information array that is attached

   to each message ($message["meta"]). This array is a regular PHP

   array, which is stored in the database as serialized data

   (see http://www.php.net/serialize). Because Phorum and other modules

   make use of this meta data as well, you should not squash it,

   neither access the meta data in the database directly. Instead

   use the methods described in this section.

   Remark: because the meta data is stored as serialized data in the

   database, it is not possible to include data you store in there

   in SQL queries.

   When storing information in the meta data from a hook function, you

   can encounter two different situations, which both need a different

   way of handling.

  2.4.1 From hooks that are run before saving a message to the database

  ---------------------------------------------------------------------

   There are some hooks that send a full message structure to the

   hook functions, so these can change the message data before storing

   the message in the database. Examples are the hooks "pre_post"

   and "pre_edit". In this case you can simply update the meta

   information directly. Here's an example of how this would look

   in your hook function:

      function phorum_mod_foo_pre_post ($message) {

          $message["meta"]["mod_foo"]["foodata"] = "Some data";

          $message["meta"]["mod_foo"]["bardata"] = "Some more data";

          return $message;

      }

   Phorum will take care of storing the updated meta data in the database.

  2.4.2 From other hooks

  ----------------------

   For other hooks, the proper way to store information in the meta

   data is to retrieve the current meta data using phorum_db_get_message(),

   copy the meta data to a new message structure, make changes as needed

   and use phorum_db_update_message() to update the message in the

   database. Here is an example of how this could look in your hook

   function:

      function phorum_mod_foo_some_hook ($data) {

          // Somehow you get the id for the message. Here we asume

          // that it is stored in the $data parameter.

          $message_id = $data["message_id"];

          // Retrieve the current message data.

          $message = phorum_db_get_message ($message_id);

          // Create updated meta data.

          $new_message = array("meta" => $message["meta"]);

          $new_message["meta"]["mod_foo"]["foodata"] = "Some data";

          $new_message["meta"]["mod_foo"]["bardata"] = "Some more data";

          // Store the updated data in the database.

          phorum_db_update_message($message_id, $new_message);

          return $data;

      }

   Changing meta data for a message this way will ensure that the

   existing meta data is kept intact.

 2.5 Storing user data

 ---------------------

   If your module needs to store data along with a Phorum user,

   you can make use of custom profile fields. In the admin interface,

   under "Custom Profiles", you can add your own profile fields

   (see also docs/creating_custom_userfields.txt).

   The custom profile fields will be accessible from within the user

   data. E.g. if you have created a custom profile field named "foobar",

   the value of that field will be stored in $user["foobar"].

   When using a custom profile field for storing module information,

   you can use a separate field for each piece of data you want to

   store. But instead, you can also create a single field for storing

   a complete array of information. Phorum will automatically take care

   of storing this information (serialized) in the database. You only

   should make sure that the custom profile field is large enough to

   store all the data. When your module needs to store multiple fields,

   this is the preferred way.

   For storing data in the custom profile field, you can make use of the

   phorum_user_save() function. Below are two pieces of code which show

   how our example module might store data for a user (asuming $user_id

   is the id of the user that must be changed).

   When using multiple fields "mod_foo_foodata" and "mod_foo_bardata":

      $user = phorum_user_get($user_id);

      $user["mod_foo_foodata"] = "Some user data";

      $user["mod_foo_bardata"] = "Some more user data";

      phorum_user_save($user);

   When using a single custom field "mod_foo" for this module:

      $user = phorum_user_get($user_id);

      $user["mod_foo"] = array (

        "foodata" => "Some user data",

        "bardata" => "Some more user data"

      );

      phorum_user_save($user);

 2.6 Creating custom URLs

 -------------------------

   Phorum uses the function phorum_get_url() to consistenly build URLs

   that point to parts of Phorum. It is recommended that you use this

   function as well when creating links yourself, so special features

   and future changes will automatically be incorporated in the links

   you use.

   Here's an example of building an URL, which will open the profile

   for the user with user_id = 17:

      $url = phorum_get_url(PHORUM_PROFILE_URL, 17);

   The argument list that this function takes, depends on the first

   argument which tells Phorum what kind of URL has to be built.

   So when building other URLs, other arguments will probably

   be used.

   If you need to build a custom URL to link to your own module, you

   can use phorum_get_url() as well. The way to go is simple. You

   need to use PHORUM_CUSTOM_URL as the first argument and add all

   URL building parameters to it.

   The first parameter needs to be the filename of the file to link

   to, without the (.php) extension. The second parameter needs to

   be 0 or 1. If it is 1, the current forum_id is added to the URL.

   All other parameters are added comma separated to the URL.

   Here's an example of building a custom URL which links to the

   file "myfile.php". The URL has to have the forum_id in it and

   needs to contain the additional parameter "foo=bar":

      $url = phorum_get_url(PHORUM_CUSTOM_URL, "myfile", 1, "foo=bar");

 2.7 Implementing settings for your module

 -----------------------------------------

   (this feature is only available for the multiple file module structure)

   Some modules that you write might need to store settings for later

   use. For those, you can create a settings page which will be used

   from within the admin interface.

   The settings page must be put in your modules's directory by the

   name of "settings.php". So for our example module "foo" the file

   would go in {phorum dir}/mods/foo/settings.php. In the admin

   interface under the option "Modules", a link to the settings.php

   page will automatically be added if the settings.php file is

   available for your module.

   Although you can do anything you want from your settings.php script,

   it is recommended that you use the tools that are handed to you

   by Phorum for building pages and storing settings.

   One of those tools is a PHP object "PhorumInputForm" which

   can be used to create standard input forms and table displays in

   the admin interface. The best example here is to look at one of the

   modules that come with Phorum like "bbcode" or "replace".

   Another tool is the function phorum_db_update_settings() which can

   be used for storing settings in the database. To store settings using

   this function you do something like the following:

      $foo_settings["foodata"] = "Some setting data";

      $foo_settings["bardata"] = "Some more setting data";

      phorum_db_update_settings(array("mod_foo" => $foo_settings));

   $foo_settings can be anything you like: an array, object, string, etc.

   The first request after you have stored your settings, the setting

   data for this example will be available in $PHORUM["mod_foo"].

   To ensure that your settings file is only loaded from the admin

   interface, place this line at the top of your settings.php file

   (see also 3.5):

      if(!defined("PHORUM_ADMIN")) return;

 2.8 Changing the templates using template hooks

 -----------------------------------------------

  2.8.1 When to use a template hook

  ---------------------------------

   Changing the templates should be avoided as much as possible when

   writing a module. This will basically turn your mod into a hack,

   because files have to be edited for it. Inexperienced users might

   find it hard to install your module if they have to modify files

   to get it to work.

   If you cannot avoid changing the template, then consider to use

   template hooks for this. You can use these if your template change

   involves adding extra code to a template. The advantage is that

   there's only little code that has to be added to the templates,

   which makes things less confusing to users that want to install the

   module.

  2.8.2 How to use a template hook

  --------------------------------

   To create a template hook, you do the following:

   * Add "{HOOK tpl_some_hook}" to the template at an appropriate spot;

   * Put "hook: tpl_some_hook|phorum_mod_foo_tpl_some_hook" in your

     module info;

   * Create the hook function phorum_mod_foo_tpl_some_hook() that

     prints out the code that has to be placed at the position of

     the "{HOOK tpl_some_hook}" code the the template.

   If you want to pass on the data from template variables to

   the hook function, you can simply add the variables to the hook

   definition in the template. Example:

      {HOOK tpl_some_hook DATA1 DATA2}

   The hook function will get the contents of these variables passed in

   a single array. This can for example be useful if your template hook

   needs access to loop data. Example:

      {LOOP MESSAGES}

         ...

         {HOOK tpl_some_hook MESSAGES}

         ...

      {/LOOP MESSAGES}

  2.8.3 Preventing collisions in hook names

  -----------------------------------------

   You can use any name for "tpl_some_hook", but beware that your

   name does not collide with an already existing hook name.

   The easiest way to do this is use the techniques from section 3.7.

   As a rule of thumb, you can use the following format:

      tpl_mod_<modulename>_<identifier>

   Example: If a buttonbar is added in one of the templates for a module

   named "foo", the name for the hook could be "tpl_mod_foo_buttonbar".

 2.9 Example modules

 -------------------

   The best way of learning how to write modules is probably looking

   at existing module code. In your Phorum distribution's docs directory,

   you will find the directory example_mods. This directory contains a

   couple of example modules, demonstrating the features described in this

   document. The modules have no real functional purpose, but they might

   be easier to read than the real Phorum modules.

3. **CAUTIONS AND SECURITY ISSUES**

-------------------------------------------------------------------------------

 3.1 Make modules, not hacks

 ---------------------------

   Making modules that require database changes are discouraged and may

   not be accepted as an approved module. We want modules to be as

   transparent as possible for upgrades. Please attempt to store your

   data in the proper place. See chapter 2 for more information on that.

 3.2 Reload your module if you change the module information

 -----------------------------------------------------------

   If you are changing the module info for a module that is already

   activated in your Phorum installation, you must deactivate and

   reactivate it to have Phorum reload the changed information. For

   performance reasons the module information is only read when the

   module is activated.

   If you have added a new hook function to your module and it seems

   not to be run, it probably is because you did not do this.

 3.3 How to access the $PHORUM array from your hook functions

 ------------------------------------------------------------

   The $PHORUM array is in the global scope. From inside a function,

   you can not directly access this array. So you will have to import

   the $PHORUM array into your function scope. The Phorum team

   recommends the following method for doing this (check out the

   faq.txt to see why we do not use the "global" keyword):

      function phorum_mod_foo_some_hook ($data) {

          $PHORUM = $GLOBALS["PHORUM"];

          // Do stuff for "some_hook".

          return $data;

      }

 3.4 How to access additional files in your multi file module

 ------------------------------------------------------------

   All standard Phorum pages are run from the Phorum installation

   directory. The hook functions that you write also work from

   the same directory. So if you want to access files in your module

   directory, you will have to specify the relative path to those

   files. This path looks like:

      ./mods/<module>/<filename>

   So let's say that our module "foo" has a subdirectory "images"

   which contains "bar.gif", then we could display that image

   using the HTML code:

      <img src="./mods/foo/images/bar.gif" />

   Another example: let's say that there is a function library

   named "my_module_functions.php" in the module, which must be

   included from then module code, then this is done using:

      include("./mods/foo/my_module_functions.php");

 3.5 Secure your PHP files agains hackers

 ----------------------------------------

   To prevent hackers from loading your PHP module files directly, you

   should add the following to the start of your PHP files:

      if(!defined("PHORUM")) return;

   This will make sure that the file will only work when loaded from

   the Phorum application. If you are writing pages that are loaded

   from the admin interface (like a settings screen for your module),

   then use the following line instead:

      if(!defined("PHORUM_ADMIN")) return;

   This will make sure that the file will only work when loaded from

   the Phorum admin interface.

 3.6 Secure your pages from XSS

 ------------------------------

   XSS stands for cross site scripting. This means that hackers

   can feed HTML data to your application, which is displayed on

   screen without stripping or escaping the HTML data. This way

   it can be possible for hackers to feed malicous javascript

   code into the browser of users on the forum, causing a security

   risk. If you want to learn more about XSS, please visit

   http://en.wikipedia.org/wiki/XSS

   To prevent XSS security holes, you must take care that all

   user input is properly sanitized before displaying it on screen.

   Sanitizing can be done by either stripping all HTML from

   the data (e.g. using http://www.php.net/strip_tags) or by escaping

   all html characters (using http://www.php.net/htmlspecialchars).

   Example:

   If your module needs to display the username for a user on

   screen, it must not simply do:

       print $user["username"];

   Instead you must use:

       print htmlspecialchars($user["username"]);

   It's not only for security that you have to sanitize data before

   displaying it. You must use htmlspecialchars() to prevent some other

   possible problems as well. Imagine you have a user with the username

   "<b>ob". Without htmlspecialchars() the username would be interpreted

   as HTML code, possibly making the full page bold from the username on.

 3.7 Prevent namespace collisions

 --------------------------------

   When creating modules, you must always be aware that you are

   working in the same namespace as other modules and Phorum itself.

   This means that there is a risk of duplicate use of function

   and variable names. By following a couple of simple rules, you

   can greatly reduce this risk.

  3.7.1 (Hook) functions

  ----------------------

   Always construct names for your module functions like this:

      phorum_mod_<module name>_<identifier>

   So if you are writing functions for a module named "foo", all

   function names will look like:

      phorum_mod_foo_<identifier>

   You can use whatever you like for the <identifier> part. When writing

   a hook function, it is recommended to use the name of the hook for

   which you are writing the function (this will make clear what the

   function does, without having to check the module info). So in case

   you are writing a hook function for the hook "some_hook", the full

   function name would be:

      phorum_mod_foo_some_hook

   If your hook function handles multiple hooks at once, then

   simply use one of the hook's names as the <identifier> or make up

   something yourself.

  3.7.2 Data stored in $PHORUM

  ----------------------------

   When storing data in $PHORUM, always prepend the array key name

   with mod_<module name>. If your module is named "foo", do not use:

      $PHORUM["mydata"]

   but instead:

      $PHORUM["mod_foo_mydata"]

  3.7.3 Language strings stored in $PHORUM

  ----------------------------------------

   When storing your custom language strings, do not put them directly

   in $PHORUM["DATA"]["LANG"] like Phorum does, because that might

   result in conflicting language strings. Instead add an extra data level,

   which makes sure that your module keeps all language strings to itself.

   If your module is named "foo", you should store language strings in:

      $PHORUM["DATA"]["LANG"]["mod_foo"]

   See also section 2.3.

  3.7.4 Data stored in messages, users and settings

  -------------------------------------------------

   When using the Phorum provided ways of storing data in messages,

   users and settings, always prepend the data key with

   mod_<module name>. SO if your module is named "foo", do not use

   things like:

      $new_message["meta"]["foodata"] = "Some data";

      $user["foodata"] = "Some data";

      phorum_db_update_settings(array("settings" => $foo_settings));

   but instead:

      $new_message["meta"]["mod_foo_foodata"] = "Some data";

      $user["mod_foo_foodata"] = "Some data";

      phorum_db_update_settings(array("mod_foo" => $foo_settings));

   See also sections 2.4 (message data), 2.5 (user data) and 2.7 (settings).

4. Overview of available Phorum hooks

-------------------------------------------------------------------------------

   In this chapter you will find an overview of all available Phorum

   hooks and a description of what they do.

   Remarks:

   * Input is what your module function should expect as parameters.

   * Return is what your module function should return. Most hooks

     expect the same data structure as was sent. For those items,

     the Return is listed simply as "Same as Input".

   * Normally, hook functions are allowed to modify the data that was

     sent as input. If this is not allowed, the input data will be

     flagged as read-only.

   * In most cases the hook description will provide only one or more

     of the possible uses for the hook. The full leverage of each hook

     is only limited by the imagination of the module writer (it's

     as much a cliche as it is true).

   * It may be that you need to hook into a spot where there is

     currently no hook available. If that is the case, let the dev

     team know by posting a message in the development forum

     on phorum.org, explaining where and why you need an extra hook.

     Hooks will be added as neccessary, especially while Phorum 5

     is young.

 4.1 Code hooks

 --------------

   Code hooks are hooks that are called from within the Phorum core

   code. These hooks are typically used for modifying Phorum's internal

   datastructures.

   ----------------------------------------------------------------------------

   admin_general

   Where  : admin interface

   When   : Right before the PhorumInputForm object is shown.

   Input  : The PhorumInputForm object.

   Return : Same as Input

   This hook can be used for adding items to the form on the

   "General Settings" page of the admin interface.

   ----------------------------------------------------------------------------

   admin_file_purge

   Where  : admin interface, option "Purge Stale Files"

   When   : Right before stale files are deleted from the database.

   Input  : An array, containing a description of all stale files.

   Return : Same as Input

   The primary use of this hook would be to cleanup stale files, created

   by an alternate storage system for attachments (see after_attach and

   after_detach as well). The array that is passed on to the hook function

   contains arrays, which contain the following fields:

   file_id      : Internal id to reference the file.

   filename     : Name of the file.

   filesize     : Filesize in KB.

   add_datetime : Epoch timestamp for the time the file was created.

   reason       : A description why this file is considered to be stale.

   ----------------------------------------------------------------------------

   after_attach

   Where  : include/posting/action_attachments.php

   When   : Just after a file attachment is saved in the database

   Input  : Two part array where the first element is the message array and

            the second element is a file array that contains the name, size,

            and file_id of the newly saved file.

   Return : Same as Input

   The primary use of this hook would be for creating an alternate storage

   system for attachments. You would need to use the before_attach hook to

   remove the file data and in this hook it could be saved properly. You will

   need to use the file hook to retreive the file data later.

   ----------------------------------------------------------------------------

   after_detach

   Where  : include/posting/action_attachments.php

   When   : Just after a file attachment is deleted from the database

   Input  : Two part array where the first element is the message array and

            the second element is a file array that contains the name, size,

            and file_id of the deleted file.

   Return : Same as Input

   The primary use of this hook would be for creating an alternate storage

   system for attachments. Using this hook, you can delete the file from

   your alternate storage.

   ----------------------------------------------------------------------------

   after_header

   Where  : Every page, except for the admin interface pages

   When   : Right after the header is displayed.

   Input  : none

   Return : none

   This hook can be used for creating content at the end of the header,

   just before the main content is displayed.

   ----------------------------------------------------------------------------

   after_login

   Where  : login.php

   When   : After a successful login, just before redirecting the

            user to a Phorum page.

   Input  : The redirection URL.

   Return : Same as Input

   This hook can be used for performing tasks after a successful user

   login and for changing the page to which the user will be redirected

   (by returning a different redirection URL). If you need to access the

   user data, then you can do this through the global $PHORUM variable.

   The user data will be in $PHORUM["user"].

   ----------------------------------------------------------------------------

   after_logout

   Where  : login.php

   When   : After a logout, just before redirecting the user to

            a Phorum page.

   Input  : The redirection URL.