Docs for page user.php

## /user.php

Description

This script implements the Phorum user API.

The user API is used for managing users and user related data. The API does also implement the Phorum session system, which is used for remembering authenticated users. See the documentation for the function phorum_api_user_session_create() for more information on Phorum user sessions.

The Phorum user API supports modules which can override Phorum's authentication and session handling. And example module is provided with the user API documentation.

- todo: Document what fields are in a user record.
- todo: Create in line docs for all hook calls.
- example: Authentication override module example
- license: Phorum
- copyright: 2007, Phorum Development Team

Constants
PHORUM_ACCESS_ANY = -2 (line 164)

Function call parameter, which tells phorum_api_user_check_access() and phorum_api_user_check_group_access() to check if the user is granted access for respectively any forum or group.

PHORUM_ACCESS_LIST = -1 (line 157)

Function call parameter, which tells phorum_api_user_check_access() and phorum_api_user_check_group_access() to return an array of respectively forums or groups for which a user is granted access.

PHORUM_ADMIN_SESSION = 2 (line 86)

Function call parameter, which tells various functions that an admin back end session has to be handled.

PHORUM_FLAG_HTML = 1 (line 109)

Function call flag, which tells phorum_api_user_get_display_name() that the returned display names have to be HTML formatted, so they can be used for showing the name in HTML pages.

PHORUM_FLAG_PLAINTEXT = 2 (line 117)

Function call flag, which tells phorum_api_user_get_display_name() that the returned display names should be stripped down to plain text format, so they can be used for showing the name in things like mail messages and message quoting.

PHORUM_FLAG_RAW_PASSWORD = 1 (line 102)

Function call flag, which tells phorum_api_user_save() that the password field should be stored as is.

This can be used to feed Phorum MD5 encrypted passwords. Normally, the password field would be MD5 encrypted by the function. This will keep the phorum_api_user_save() function from double encrypting the password.

PHORUM_FLAG_SESSION_ST = 1 (line 93)

Function call flag, which tells phorum_api_user_set_active_user() that the short term forum session has to be activated.

PHORUM_FORUM_SESSION = 1 (line 80)

Function call parameter, which tells various functions that a front end forum session has to be handled.

PHORUM_GET_ACTIVE = 1 (line 144)

Function call parameter, which tells phorum_api_user_get_list() that all active users have to be returned.

PHORUM_GET_ALL = 0 (line 138)

Function call parameter, which tells phorum_api_user_get_list() that all users have to be returned.

PHORUM_GET_INACTIVE = 2 (line 150)

Function call parameter, which tells phorum_api_user_get_list() that all inactive users have to be returned.

PHORUM_ORIGINAL_USER_CODE = TRUE (line 55)

If a user API is written as a replacement for the standard Phorum user API, where the replacement API is incompatible with the standard API, then this define should be set to FALSE. That will disable the user management functions in the admin interface.

PHORUM_SESSID_RESET_ALL = 2 (line 132)

Function call parameter, which tells phorum_api_user_session_create() that all session ids have to be reset to new values. This is for example appropriate after a user changed the password (so active sessions on other computers or browsers will be ended).

PHORUM_SESSID_RESET_LOGIN = 1 (line 124)

Function call parameter, which tells phorum_api_user_session_create() that session ids have to be reset to new values as far as that is sensible for a newly logged in user.

PHORUM_SESSION_ADMIN = 'phorum_admin_session' (line 74)

Used for identifying admin sessions. The value is used as the name for the session cookie for admin sessions.

PHORUM_SESSION_LONG_TERM = 'phorum_session_v5' (line 61)

Used for identifying long term sessions. The value is used as the name for the session cookie for long term sessions.

PHORUM_SESSION_SHORT_TERM = 'phorum_session_st' (line 68)

Used for identifying short term sessions. The value is used as the name for the session cookie for short term sessions (this is used by the tighter authentication scheme).

PHORUM_SUBSCRIPTION_BOOKMARK = 2 (line 279)

Subscription type, which tells Phorum to make the forums or threads that a user is subscribed to accessible from the followed threads interface in the control center. No mail is sent for new messages, but the user can check for new messages using that interface.

PHORUM_SUBSCRIPTION_DIGEST = 1 (line 271)

Subscription type, which tells Phorum to periodially send a mail message, containing a list of new messages in forums or threads that a user is subscribed to. There is currently no support for this type of subscription in the Phorum core code.

PHORUM_SUBSCRIPTION_MESSAGE = 0 (line 263)

Subscription type, which tells Phorum to send out a mail message for every new forum or thread that a user is subscribed to.

PHORUM_SUBSCRIPTION_NONE = -1 (line 257)

Subscription type, which tells Phorum explicitly that the user does not have a subscription of any kind for the forum or thread.

PHORUM_USER_ACTIVE = 1 (line 194)

User status, indicating that the registration has been completed and that the user can access the forums.

PHORUM_USER_ALLOW_ATTACH = 32 (line 219)

Permission flag which allows users to attach files to their forum messages.

PHORUM_USER_ALLOW_EDIT = 4 (line 209)

Permission flag which allows users to edit their own forum messages.

PHORUM_USER_ALLOW_MODERATE_MESSAGES = 64 (line 224)

Permission flag which allows users to edit other users' messages.

PHORUM_USER_ALLOW_MODERATE_USERS = 128 (line 230)

Permission flag which allows users to moderate user signup requests within the vroot.

PHORUM_USER_ALLOW_NEW_TOPIC = 8 (line 214)

Permission flag which allows users to start new forum topics.

PHORUM_USER_ALLOW_READ = 1 (line 199)

Permission flag which allows users to read forum messages.

PHORUM_USER_ALLOW_REPLY = 2 (line 204)

Permission flag which allows users to reply to forum messages.

PHORUM_USER_GROUP_APPROVED = 1 (line 246)

Group permission flag for users which are active approved group members.

PHORUM_USER_GROUP_MODERATOR = 2 (line 251)

Group permission flag for users which are group moderator.

PHORUM_USER_GROUP_SUSPENDED = -1 (line 235)

Group permission flag for users which are suspended by a group moderator.

PHORUM_USER_GROUP_UNAPPROVED = 0 (line 241)

Group permission flag for users which are not yet approved by a group moderator.

PHORUM_USER_INACTIVE = 0 (line 188)

User status, indicating that the user has been deactivated.

PHORUM_USER_PENDING_BOTH = -3 (line 171)

User status, indicating that the user has not yet confirmed the registration by email and that a user moderator will have to approve the registration as well.

PHORUM_USER_PENDING_EMAIL = -2 (line 177)

User status, indicating that the user has not yet confirmed the registration by email.

PHORUM_USER_PENDING_MOD = -1 (line 183)

User status, indicating that the registration has not yet been approved by a user moderator.

Functions
phorum_api_user_authenticate (line 1483)

Check the authentication credentials for a user.

- return: If the authentication credentials are correct, this function returns the user_id of the authenticated user. Otherwise, FALSE is returned.
- example: Handle a user forum login

mixed phorum_api_user_authenticate (mixed $type, mixed $username, mixed $password, string $type , string $username , string $password )

- string $type :

  The type of session for which authentication is run. This must be one of PHORUM_FORUM_SESSION or PHORUM_ADMIN_SESSION.

  This parameter is mostly used for logging purposes and for giving mods a chance to handle user authentication for only a certain type of session. It is not used for denying authentication if for example a standard user tries to authenticate for the admin interface. Those restrictions are handled in a different part of the user API.

  See the documentation for phorum_api_user_session_create() for more information on Phorum user sessions.

- string $username : The username for the user.
- string $password : The password for the user.

phorum_api_user_check_access (line 2726)

Check if a user has certain access right for forum(s).

- return:

  The return value depends on the $forum_id argument that was used:

  - Single forum_id , 0 (zero) or PHORUM_ACCESS_ANY: return either TRUE (access granted) or FALSE (access denied).
  - An array of forum_ids or PHORUM_ACCESS_LIST: return an array, containing all forum_ids for which permission was granted (both keys and values are forum_ids in this array).

mixed phorum_api_user_check_access (mixed $permission, [mixed $forum_id = 0], [mixed $user = 0], integer $permission , mixed $forum_id , mixed $user )

- integer $permission : The permission to check for. Multiple permissions can be OR-ed together. The available permissions are:
  - PHORUM_USER_ALLOW_READ
  - PHORUM_USER_ALLOW_REPLY
  - PHORUM_USER_ALLOW_EDIT
  - PHORUM_USER_ALLOW_NEW_TOPIC
  - PHORUM_USER_ALLOW_ATTACH
  - PHORUM_USER_ALLOW_MODERATE_MESSAGES
  - PHORUM_USER_ALLOW_MODERATE_USERS
- mixed $forum_id : Specifies the forum(s) to look at. Available options are:
  - The id of the forum for which to check the access
  - 0 (zero, the default) to check access for the active forum
  - An array of forum_ids to check
  - PHORUM_ACCESS_ANY to check if the user has access rights for any of the available forums
  - PHORUM_ACCESS_LIST to return a list of forum_ids for which the user has access rights
- mixed $user : Specifies the user to look at. Available options are:
  - 0 (zero, the default) to look at the active Phorum user.
  - A full user data array.
  - A single user_id.

phorum_api_user_check_group_access (line 2887)

- return:

  The return value depends on the $group_id argument that was used:

  - Single group_id or PHORUM_ACCESS_ANY: return either TRUE (access granted) or FALSE (access denied).
  - An array of group_ids or PHORUM_ACCESS_LIST: return an array, containing all groups for which permission was granted. The keys in this array are group_ids and the values are group info arrays. These arrays contain the fields "group_id", "name", "open", "permissions" (which contains an array of forum permissions, indexed by forum_id), "user_status" (which contains the group status for the user, i.e. one of the PHORUM_USER_GROUP_* constants).

mixed phorum_api_user_check_group_access (mixed $permission, mixed $group_id, [mixed $user = 0], integer $permission , mixed $group_id , mixed $user )

- integer $permission : The permission level to check for. The function will check if the user has equal or higher permissions for the group(s). The available permission levels in low-to-high level order are:
  - PHORUM_USER_GROUP_SUSPENDED
  - PHORUM_USER_GROUP_UNAPPROVED
  - PHORUM_USER_GROUP_APPROVED
  - PHORUM_USER_GROUP_MODERATOR
- mixed $group_id : Specifies the group(s) to look at. Available options are:
  - The id of the group for which to check the access.
  - An array of group_ids to check.
  - PHORUM_ACCESS_ANY to check if the user has access rights for any of the available groups.
  - PHORUM_ACCESS_LIST to return a list of group_ids for which the user has access rights.
- mixed $user : Specifies the user to look at. Available options are:
  - 0 (zero, the default) to look at the active Phorum user.
  - A full user data array.
  - A single user_id.

phorum_api_user_delete (line 1391)

Delete a Phorum user.

void phorum_api_user_delete (mixed $user_id, integer $user_id )

- integer $user_id : The user_id of the user that has to be deleted.

phorum_api_user_get (line 875)

Retrieve data for Phorum users.

- return: If the $user_id parameter is a single user_id, then either an array containing user data is returned or NULL if the user was not found. If the $user_id parameter is an array of user_ids, then an array of user data arrays is returned, indexed by the user_id. Users for user_ids that are not found are not included in the returned array.

mixed phorum_api_user_get (mixed $user_id, [mixed $detailed = FALSE], [mixed $use_write_server = FALSE], mixed $user_id , boolean $detailed , boolean $use_write_server )

- mixed $user_id : Either a single user_id or an array of user_ids.
- boolean $detailed : If this parameter is TRUE (default is FALSE), then the user's groups and permissions are included in the user data.
- boolean $use_write_server : This parameter is for internal use only. It is used to flag that the database layer has to run the query against the master database server (known as the "write server"; only applicable if the database system is setup as a replicated master/slave environment). When you are using this API call in your own code, then you most probably do not need to use this parameter.

phorum_api_user_get_display_name (line 1097)

Retrieve the display name to use for one or more users.

The name to use depends on the "display_name_source" setting. This one points to either the username or the real_name field of the user. If the display_name is requested for an unknown user, then a fallback name will be used.

- return: If the $user_id parameter was NULL or a single user_id, then this function will return a single display name. If it was an array, then this function will return an array of display names, indexed by user_id.

mixed phorum_api_user_get_display_name ([mixed $user_id = NULL], [mixed $fallback = NULL], [mixed $flags = PHORUM_FLAG_HTML], mixed $user_id , mixed $fallback , mixed $flags )

- mixed $user_id : Either a single user_id, an array of user_ids or NULL to use the user_id of the active Phorum user.
- mixed $fallback : The fallback display name to use in case the user is unknown or NULL to use the "AnonymousUser" language string.
- mixed $flags : One of PHORUM_FLAG_HTML (the default) or PHORUM_FLAG_PLAINTEXT. These determine what output format is used for the display names.

phorum_api_user_get_setting (line 1053)

This function can be used to retrieve the value for a user setting that was stored by the phorum_api_user_save_settings() function for the active Phorum user.

- return: The value of the setting or NULL if it is not available.

mixed phorum_api_user_get_setting (mixed $name, string $name )

- string $name : The name of the setting for which to retrieve the setting value.

phorum_api_user_get_subscription (line 3095)

Retrieve the type of a single subscription.

- return: The type of subscription if there is a subscription available or NULL in case no subscription was found. Available types are:
  - PHORUM_SUBSCRIPTION_NONE
  - PHORUM_SUBSCRIPTION_MESSAGE
  - PHORUM_SUBSCRIPTION_BOOKMARK
  - PHORUM_SUBSCRIPTION_DIGEST

mixed phorum_api_user_get_subscription (mixed $user_id, mixed $forum_id, mixed $thread, integer $user_id , integer $thread , integer $forum_id )

- integer $user_id : The id of the user to retrieve a subscription for.
- integer $thread : The id of the thread to retrieve a subscription for.
- integer $forum_id : The id of the forum to retrieve a subscription for.

phorum_api_user_increment_posts (line 1373)

Increment the posts counter for a user.

void phorum_api_user_increment_posts ([mixed $user_id = NULL], mixed $user_id )

- mixed $user_id : The user_id for which to increment the posts counter or NULL (the default) to increment the posts counter for the active Phorum user.

phorum_api_user_list (line 1299)

Retrieve a list of Phorum users.

- return: An array of users, indexed by user_id. Each element in the array is an array, containing the fields "user_id", "username" and "display_name".
- todo: Do we really need phorum_api_user_list() or could we use the phorum_api_user_search() functionality in combination with phorum_api_user_get() instead?

array phorum_api_user_list ([mixed $type = PHORUM_GET_ALL], int $flags )

- int $flags : One of:
  - PHORUM_GET_ALL: retrieve a list of all users (the default)
  - PHORUM_GET_ACTIVE: retrieve a list of all active users
  - PHORUM_GET_INACTIVE: retrieve a list of all inactive users

phorum_api_user_list_moderators (line 3004)

Retrieve a list of moderators.

- return: An array of moderator users, indexed by user_id.

array phorum_api_user_list_moderators ([mixed $forum_id = 0], [mixed $exclude_admin = FALSE], [mixed $for_mail = FALSE], integer $forum_id , boolean $exclude_admin , boolean $for_mail )

- integer $forum_id : The id of the forum for which to retrieve a list of moderators or
  1. (zero, the default) to use the active forum.
- boolean $exclude_admin : If TRUE, then the admin users are kept out of the list. The default is to include admin users.
- boolean $for_mail : If TRUE, then a list of moderators is created for sending moderator mail messages. Moderators which have disabled the moderation_email option will be excluded from the list in this case. The default is to include all moderators.

phorum_api_user_list_subscribers (line 3158)

Retrieve the email addresses of the users that are subscribed to a forum/thread, grouped by the preferred language for these users.

- return: An array containing the subscriber email addresses. The keys in the result array are language names. The values are arrays. Each array contains a list of email addresses of users which are using the language from the key field.

array phorum_api_user_list_subscribers (mixed $forum_id, mixed $thread, mixed $type, [mixed $ignore_active_user = TRUE], integer $forum_id , integer $thread , integer $type , boolean $ignore_active_user )

- integer $forum_id : The forum_id to check on.
- integer $thread : The thread id to check on.
- integer $type : The type of subscription. Available types are:
  - PHORUM_SUBSCRIPTION_MESSAGE
  - PHORUM_SUBSCRIPTION_BOOKMARK
  - PHORUM_SUBSCRIPTION_DIGEST
- boolean $ignore_active_user : If this parameter is set to FALSE (it is TRUE by default), then the active Phorum user will be excluded from the list.

phorum_api_user_list_subscriptions (line 3124)

Retrieve a list of threads to which a user is subscribed. The list can be limited to those threads which did receive contributions recently.

- return: An array of matching threads, indexed by thread id. One special key "forum_ids" is set too. This one contains an array of all involved forum_ids.

array phorum_api_user_list_subscriptions (mixed $user_id, [mixed $days = 0], [mixed $forum_ids = NULL], integer $user_id , integer $days , integer $forum_ids )

- integer $user_id : The id of the user for which to retrieve the subscribed threads.
- integer $days : If set to 0 (zero), then all subscriptions will be returned. If set to a different value, then only threads which have received contributions within the last $days days will be included in the list.
- integer $forum_ids : If this parameter is NULL, then subscriptions from all forums will be included. This parameter can also be an array of forum_ids, in which case the search will be limited to the forums in this array.

phorum_api_user_save (line 397)

Create or update Phorum users.

This function can be used for both creating and updating Phorum users. If no user_id is provided in the user data, a new user will be created. If a user_id is provided, then the existing user will be updated or a new user with that user_id is created.

Often when calling this function yourself, you will be doing that for synchronizing a user from some external system with the Phorum database. For those cases, the most basic use of this API function can be found in the examples below.

     $user = array(
         "user_id"   => 1234,
         "username"  => 'johndoe',
         "password"  => '#barbar#',
         "email"     => 'john.doe@example.com',
         "admin"     => 0,
         "active"    => PHORUM_USER_ACTIVE
     );
     phorum_api_user_save($user);

If you do not have the plain text password available, but only an MD5 hash for the password, then you can use the following code instead.

     $user = array(
         "user_id"   => 1234,
         "username"  => 'johndoe',
         "password"  => '5d61ed116ffdecf2d29cd1ed9bd9d4cb',
         "email"     => 'john.doe@example.com',
         "admin"     => 0,
         "active"    => PHORUM_USER_ACTIVE
     );
     phorum_api_user_save($user, PHORUM_FLAG_RAW_PASSWORD);

- return: The user_id of the user. For new users, the newly assigned user_id will be returned.

int phorum_api_user_save (mixed $user, [mixed $flags = 0], array $user , int $flags )

- array $user : An array containing user data. This array should at least contain a field "user_id". This field can be NULL to create a new user with an automatically assigned user_id. It can also be set to a user_id to either update an existing user or to create a new user with the provided user_id. If a new user is created, then all user fields must be provided in the user data.
- int $flags : If the flag PHORUM_FLAG_RAW_PASSWORD is set, then the password fields ("password" and "password_temp") are considered to be MD5 encrypted already. So this can be used to feed Phorum existing MD5 encrypted passwords.

phorum_api_user_save_groups (line 2652)

Save the groups and group permissions for a user.

void phorum_api_user_save_groups (mixed $user_id, mixed $groups, integer $user_id , array $groups )

- integer $user_id : The user_id of the user for which to store the group permissions.
- array $groups : An array of groups and their permissions. The keys in this array are group ids. The values are either group permission values or arrays containing at least the key "user_status" (which has the group permission as its value) in them. The group permission value must be one of the PHORUM_USER_GROUP_* constants.

phorum_api_user_save_raw (line 755)

This function quickly updates the Phorum users table, using all fields in the user data as real user table fields.

This is the quickest way to update the user table. Care has to be taken by the calling function though, to provide the information exactly as the Phorum users table expects it. Only use this function if speed is really an issue.

void phorum_api_user_save_raw (mixed $user, array $user )

- array $user : An array containing user data. This array should at least contain a field "user_id", pointing to the user_id of an existing user to update. Besides "user_id", this array can contain other fields, which should all be valid fields from the users table.

phorum_api_user_save_settings (line 811)

Create or update user settings for the active Phorum user.

This function can be used to store arbitrairy settings for the active Phorum user in the database. The main goal for this function is to store user settings which are not available as a Phorum user table field in the database. These are settings which do not really belong to the Phorum core, but which are for example used for remembering some kind of state in a user interface (templates). Since each user interface might require different settings, a dynamic settings storage like this is required.

If you are writing modules that need to store data for a user, then please do not use this function. Instead, use custom profile fields. The data that is stored using this function can be best looked at as if it were session data.

void phorum_api_user_save_settings (mixed $settings, array $settings )

- array $settings : An array of setting name => value pairs to store as user settings in the database.

phorum_api_user_search (line 1226)

Search for users, based on simple search conditions, which act on fields in the user table.

The parameters $field, $value and $operator (which are used for defining the search condition) can be arrays or single values. If arrays are used, then all three parameter arrays must contain the same number of elements and the key values in the arrays must be the same.

- return: An array of matching user_ids or a single user_id (based on the $return_array parameter). If no user_ids can be found at all, then 0 (zero) will be returned.

mixed phorum_api_user_search (mixed $field, mixed $value, [mixed $operator = '='], [mixed $return_array = FALSE], [mixed $type = 'AND'], [mixed $sort = NULL], [mixed $offset = 0], [mixed $length = 0], mixed $field , mixed $value , mixed $operator , boolean $return_array , string $type , mixed $sort , integer $offset , integer $length )

- mixed $field : The user table field (string) or fields (array) to search on.
- mixed $value : The value (string) or values (array) to search for.
- mixed $operator : The operator (string) or operators (array) to use. Valid operators are "=", "!=", "<>", "<", ">", ">=" and "<=", "*". The "*" operator is for executing a "LIKE '%value%'" matching query.
- boolean $return_array : If this parameter has a true value, then an array of all matching user_ids will be returned. Else, a single user_id will be returned.
- string $type : The type of search to perform. This can be one of:
  - AND match against all fields
  - OR match against any of the fields
- mixed $sort : The field (string) or fields (array) to sort the results by. For ascending sort, "fieldname" or "+fieldname" can be used. For descending sort, "-fieldname" can be used. By default, the results will be sorted by user_id.
- integer $offset : The result page offset starting with 0.
- integer $length : The result page length (nr. of results per page) or 0 (zero, the default) to return all results.

phorum_api_user_search_custom_profile_field (line 1274)

Search for users, based on a simple search condition, which can be used to search on custom profile fields.

The parameters $field_id, $value and $operator (which are used for defining the search condition) can be arrays or single values. If arrays are used, then all three parameter arrays must contain the same number of elements and the key values in the arrays must be the same.

- return: An array of matching user_ids or a single user_id (based on the $return_array parameter). If no user_ids can be found at all, then 0 (zero) will be returned.

mixed phorum_api_user_search_custom_profile_field (mixed $field_id, mixed $value, [mixed $operator = '='], [mixed $return_array = FALSE], [mixed $type = 'AND'], [mixed $offset = 0], [mixed $length = 0], mixed $field_id , mixed $value , mixed $operator , boolean $return_array , string $type , integer $offset , integer $length )

- mixed $field_id : The custom profile field id (integer) or ids (array) to search on.
- mixed $value : The value (string) or values (array) to search for.
- mixed $operator : The operator (string) or operators (array) to use. Valid operators are "=", "!=", "<>", "<", ">", ">=" and "<=", "*". The "*" operator is for executing a "LIKE '%value%'" matching query.
- boolean $return_array : If this parameter has a true value, then an array of all matching user_ids will be returned. Else, a single user_id will be returned.
- string $type : The type of search to perform. This can be one of:
  - AND match against all fields
  - OR match against any of the fields
- integer $offset : The result page offset starting with 0.
- integer $length : The result page length (nr. of results per page) or 0 (zero, the default) to return all results.

phorum_api_user_session_create (line 1895)

Create a Phorum user session.

Before calling this function, the variable $PHORUM['use_cookies'] should be set to one of PHORUM_NO_COOKIES, PHORUM_USE_COOKIES or PHORUM_REQUIRE_COOKIES.

Phorum does not use PHP sessions. Instead, it uses its own session management system for remembering logged in users. There are multiple reasons for that, amongst which are:

- the lack of session support (on some PHP installs);
- missing out of the box load balancing support (sessions are normally written to local session state files, so multiple machines would not work well together);
- file I/O problems (both performance and file system permissions can be a problem);
- the amount of unneeded overhead that is caused by the PHP session system;
- the fact that Phorum also supports URI based sessions (without cookie).

This function can be used to create or maintain a login session for a Phorum user. A prerequisite is that an active Phorum user is set through the phorum_api_user_set_active_user() function, before calling this function.

There are two session types available: PHORUM_FORUM_SESSION (used for the front end application) and PHORUM_ADMIN_SESSION (used for the administrative back end).

Admin sessions are used for the administrative back end system. For security reasons, the back end does not share the front end session, but uses a fully separate session instead. This session does not have a timeout restriction, but it does not survive closing the browser. It is always tracked using a cookie, never using URI authentication (for security reasons).

The forum sessions can be split up into long term and short term sessions:

- Long term session: The standard Phorum user session. This session is long lasting and will survive after closing the browser (unless the long term session timeout is set to zero). If tighter security is not enabled, then this session is all a user needs to fully use all forum options. This session is tracked using either a cookie or URI authentication.

- Short term session: This session has a limited life time and will not survive closing the browser. If tighter security is enabled, then the user will not be able to use all forum functions, unless there is a short term session active (e.g. posting forum messages and reading/writing private messages are restricted). This session is tracked using a cookie. If URI authentication is in use (because of admin config or cookie-less browsers) Phorum will only look at the long term session (even in tighter security mode), since URI authentication can be considered to be short term by nature.

- return: TRUE in case the session was initialized successfully. Otherwise, FALSE will be returned. The functions phorum_api_strerror() and phorum_api_errno() can be used to retrieve information about the error which occurred.
- example: Handle a user forum login

boolean phorum_api_user_session_create (mixed $type, [mixed $reset = 0], string $type , integer $reset )

- string $type : The type of session to initialize. This must be one of PHORUM_FORUM_SESSION or PHORUM_ADMIN_SESSION.
- integer $reset :

  If it is set to 0 (zero, the default), then existing session_ids will be reused if possible.

  If this parameter is set to PHORUM_SESSID_RESET_LOGIN, then a new session id will be generated for short term forum sessions and if cookies are disabled for some reason, for long term forum sessions as well (to prevent accidental distribution of URLs with auth info in them). This is the type of session id reset that is appropriate after handling a login action.

  If this parameter is set to PHORUM_SESSID_RESET_ALL, then all session ids will be reset to new values. This is for example appropriate after a user changed the password (so active sessions on other computers or browsers will be ended).

phorum_api_user_session_destroy (line 2516)

Destroy a Phorum user session.

This will destroy a Phorum user session and set the active Phorum user to the anonymous user.

void phorum_api_user_session_destroy (mixed $type, string $type )

- string $type : The type of session to destroy. This must be one of PHORUM_FORUM_SESSION or PHORUM_ADMIN_SESSION. See the documentation for phorum_api_user_session_create() for more information on Phorum user sessions.

phorum_api_user_session_restore (line 2168)

Restore a Phorum user session.

This function will check for a valid user session for either the forum or the admin interface (based on the $type parameter). If a valid session is found, then the user session will be restored.

Before calling this function, the variable $PHORUM['use_cookies'] should be set to one of PHORUM_NO_COOKIES, PHORUM_USE_COOKIES or PHORUM_REQUIRE_COOKIES.

- return: TRUE in case a valid session is detected, otherwise FALSE. Note that a PHORUM_FORUM_SESSION will return TRUE if a long term session is detected and that the sort term session might be missing. Code which depends on short term sessions should investigate the $PHORUM["DATA"]["FULLY_LOGGEDIN"] variable.

boolean phorum_api_user_session_restore (mixed $type, string $type )

- string $type : The type of session to check for. This must be one of PHORUM_FORUM_SESSION or PHORUM_ADMIN_SESSION. See the documentation for phorum_api_user_session_create() for more information on Phorum user sessions.

phorum_api_user_set_active_user (line 1682)

Set the active Phorum user.

This function can be used to setup the Phorum data to indicate which user is logged in or to setup the anonymous user. Calling this function is all that is needed to tell Phorum which user is logged in (or to tell that no user is logged in by setting up the anonymous user).

Next to setting up the user data, the function will handle user activity tracking (based on the "track_user_activity" setting) and setup some special (template) variables:

The variabe $PHORUM["DATA"]["ADMINISTRATOR"] will be set to TRUE if the active user is an administrator, FALSE otherwise.

For type PHORUM_FORUM_SESSION, the following extra variables will be filled:

- $PHORUM["DATA"]["LOGGEDIN"]: TRUE if the user is logged in, FALSE otherwise.

- $PHORUM["DATA"]["FULLY_LOGGEDIN"]: TRUE if a short term session is active (by setting the PHORUM_FLAG_SESSION_ST flag for the $flags parameter), FALSE otherwise.

- return: TRUE if a real user was set as the active user successfully or FALSE if the anonymous user was set (either because that was requested or because setting the real user failed). If setting a real user as the active user failed, the functions phorum_api_strerror() and phorum_api_errno() can be used to retrieve information about the error which occurred.
- example: Handle a user forum login

boolean phorum_api_user_set_active_user (mixed $type, [mixed $user = NULL], [mixed $flags = 0], string $type , mixed $user , integer $flags )

- string $type : The type of session for which to set the active user. This must be one of PHORUM_FORUM_SESSION or PHORUM_ADMIN_SESSION. See the documentation for phorum_api_user_session_create() for more information on Phorum user sessions.
- mixed $user : The user_id or the full user data array for the user that has to be the active user or NULL if the active user has to be set to the anonymous user (the default).
- integer $flags : If the flag PHORUM_FLAG_SESSION_ST is set, then the short term session will be enabled for PHORUM_FORUM_SESSION based sessions.

phorum_api_user_subscribe (line 3041)

Subscribe a user to a thread.

Remark: Currently, there is no active support for subscribing to forums using subscription type PHORUM_SUBSCRIPTION_DIGEST in the Phorum core.

void phorum_api_user_subscribe (mixed $user_id, mixed $thread, mixed $forum_id, mixed $type, integer $user_id , integer $thread , integer $forum_id , integer $type )

- integer $user_id : The id of the user to create the subscription for.
- integer $thread : The id of the thread to describe to.
- integer $forum_id : The id of the forum in which the thread to subscribe to resides.
- integer $type : The type of subscription. Available types are:
  - PHORUM_SUBSCRIPTION_NONE
  - PHORUM_SUBSCRIPTION_MESSAGE
  - PHORUM_SUBSCRIPTION_BOOKMARK
  - PHORUM_SUBSCRIPTION_DIGEST

phorum_api_user_unsubscribe (line 3067)

Unsubscribe a user from a thread.

void phorum_api_user_unsubscribe (mixed $user_id, mixed $thread, [mixed $forum_id = 0], integer $user_id , integer $thread , integer $forum_id )

- integer $user_id : The id of the user to remove the subscription for.
- integer $thread : The id of the thread to describe from.
- integer $forum_id : The id of the forum in which the thread to unsubscribe from resides. This parameter can be 0 (zero) to simply unsubscribe by thread id alone.

Documentation generated on Wed, 16 Jan 2008 08:31:14 -0600 by phpDocumentor 1.3.0RC5