Prev |  | Next

#### 2.3.5.2. Storing data for messages

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"
        )
    );

### Important

because the meta data is stored as serialized data in the database, it is not possible to handle the data you store in there through 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: hooks that get an editable message array as their argument and hooks that don't.

##### 2.3.5.2.1. From hooks that get an editable message array as their argument

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;
    }

##### 2.3.5.2.2. From other hooks

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.

Prev | Up | Next
| Home |