If your module needs to store data along with a Phorum message,
the easiest way is to make use of the meta information array that
is attached to each message array
($message["meta"]).
This array is a regular PHP array, which is stored in the
database as serialized data (see PHP's serialize manual).
Because Phorum and other modules make use of this meta data as
well, you should never squash it, neither access the meta data
in the database directly. Instead use the methods described in
this section.
To prevent name space collissions with other modules or Phorum,
it is good practice to create only one key in the meta data
array named mod_<yourmodule> (in our
example: mod_foo). If your module needs to
store only one single value, then put it directly under this key:
$message["meta"]["mod_foo"] = "the single value";
If multiple values need to be stored, then put an array under the key. This array can be as complicated as you like:
$message["meta"]["mod_foo"] = array(
"key1" => "value1",
"key2" => "value2",
"complex" => array(
0 => "what",
1 => "a",
2 => "cool",
3 => "module"
)
);
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: hooks that get an editable message array as their argument and hooks that don't.
If you see ??? below at the places where you are supposed to see hook docs, then it is because the hook docs for "before_post" and "before_edit" have not yet been written. There are some hooks that send a full message structure to the hook functions. These can change the message structure before returning it to Phorum. Examples are the hooks "hook.before_post" and "before_edit". For these kind of hooks, you can update the meta information in the message structure and be done with it. Here's an example of what this could look like in your hook function:
function phorum_mod_foo_before_post ($message)
{
// Make sure that we have an array for mod_foo in the meta data.
if (!isset($message["meta"]["mod_foo"]) ||
!is_array($message["meta"]["mod_foo"])) {
$message["meta"]["mod_foo"]["foodata"] = array();
}
// Add some fields to the mod_foo data.
$message["meta"]["mod_foo"]["foodata"] = "Some data";
$message["meta"]["mod_foo"]["bardata"] = "Some more data";
// Return the updated message. Phorum will take care of
// storing the "mod_foo" array in the database.
return $message;
}
For other hooks, the proper way to store information in the meta
data is to first retrieve the current message data (including the
current meta data) using the
phorum_db_get_message() function.
After this, merge the information for your module with the
existing meta data and store the updated data in the database
using the phorum_db_update_message() function.
Here is an example of what this could look like 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 hook parameter.
$message_id = $data["message_id"];
// Retrieve the message from the database.
$message = phorum_db_get_message ($message_id);
// Extract the current meta data.
$meta = $message['meta'];
// Make sure that we have an array for mod_foo in the meta data.
if (!isset($meta["mod_foo"]) || !is_array($meta["mod_foo"])) {
$meta["mod_foo"]["foodata"] = array();
}
// Add some fields to the mod_foo data.
$meta["mod_foo"]["foodata"] = "Some data";
$meta["mod_foo"]["bardata"] = "Some more data";
// Store the updated meta data in the database.
phorum_db_update_message($message_id, array("meta" => $meta));
// Return the data that we got as input for this hook function.
return $data;
} Changing meta data for a message this way will ensure that the existing meta data is kept intact.