Prev |  | Next

#### 2.3.5.3. Storing data for users

##### 2.3.5.3.1. Custom profile fields for users

If your module needs to store data along with a Phorum user, you can make use of custom profile fields. These fields will be accessible from within the user data. E.g. if you create a custom profile field named "foobar", the value of that field will be stored in $user["foobar"] (so right next to the standard fields like $user["username"] and $user["email"]).

Creating custom profile fields can be done from the admin interface, under "Custom Profiles". It is also possible to let your module create the custom profile field fully automatical, by using the Custom Profile Fields API. If you choose to let the user of your module create the field by hand, then please include a thorough description of what configuration the user has to do. A lot of problems with modules that require manual configuration come from using wrong options for a custom profile field.

Using a separate field for each piece of data

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. The advantage of doing this, is that you can then use the option "Disable HTML" for the fields that you will be sending to the user's browser. In fields with this option enabled, characters that have a special meaning in HTML will be escaped after loading the user from the database. This prevents the field from being vulnerable to XSS attacks. Recommended settings for storing a single value in a profile field are:

- Field Name:
  Name your field `mod_<module name>` if you only need to store one single value. If you need to store more values, then use the format `mod_<module name>_<field name>`. This prevents the risk of clashing with standard Phorum user fields or custom fields that are added for other modules. For example, the "foo" module could use the field names `mod_foo_size` and `mod_foo_name`.
- Field Length:
  If you want some field to contain a predefined maximum number of characters, then fill in that number of characters in this field. Before storing the field data to the database, Phorum will trim the data down if it is longer than the defined number of characters. If you need no limit, you can also use `65000` here.
- Disable HTML:
  Enable this option, unless you are absolutely sure that the data for this field is either not shown in the browser or escaped by your module before showing it.
- Show in user admin:
  If you want the field to be visible along with the user data for a user in the admin interface, then enable this option.

Using a single field for storing a complex data structure

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 and that HTML is allowed for the field, so the special PHP serialization code will not be broken by escaping special characters. When your module needs to store multiple fields, this is the preferred way. Recommended settings for storing a full array in a profile field are:

- Field Name:
  Name your field `mod_<module name>`, so you will not risk clashes with standard Phorum user fields or custom fields that are added for other modules. For example, the "foo" module would use the field name `mod_foo`.
- Field Length:
  Use `65000` here. Using smaller values will not make the database storage smaller. This value is only used to trim down the data to the provided length. So for storing serialized data, it is best to set this value as high as possible.
- Disable HTML:
  Disable this option, so the serialize data will not be broken by escaping special characters.
- Show in user admin:
  Disable this option. There is currently no support for showing serialized fields in the user admin pages in a readable way.

##### 2.3.5.3.2. From hooks that get an editable user array as their argument

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. An example is the hook "???". For these kind of hooks, you can update the custom profile field data in the user structure and be done with it. Here's an example of what this could look like in your hook function:

    function phorum_mod_foo_user_save ($user)
    {
        // Some data to store in the "mod_foo" custom field.
        $data = array(
            "user_id" => $user_id,
            "mod_foo" => array (
                "foodata" => "Some user data",
                "bardata" => "Some more user data"
            )
        );

        // Put the data in the user sructure.
        $user["mod_foo"] = $data;

        // Return the updated user. Phorum will take care of
        // storing the "mod_foo" array in the database.
        return $user;
    }

##### 2.3.5.3.3. From other hooks

For storing data in the custom profile field, you can make use of the `phorum_api_user_save()` function. This function needs the user_id of the user and all fields that need to be updated. 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).

Example 2.6. Filling custom profile fields for a user with data

      // When using multiple fields "mod_foo_foodata" and "mod_foo_bardata".

      $userdata = array(
          "user_id"         => $user_id,
          "mod_foo_foodata" => "Some user data",
          "mod_foo_bardata" => "Some more user data"
      );
      phorum_api_user_save($userdata);

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

      $userdata = array(
          "user_id" => $user_id,
          "mod_foo" => array (
              "foodata" => "Some user data",
              "bardata" => "Some more user data"
          )
      );
      phorum_api_user_save($userdata);

Prev | Up | Next
| Home |