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.
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.
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.
Function call parameter, which tells various functions that an admin back end session has to be handled.
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.
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.
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.
Function call flag, which tells phorum_api_user_set_active_user() that the short term forum session has to be activated.
Function call parameter, which tells various functions that a front end forum session has to be handled.
Function call parameter, which tells phorum_api_user_get_list() that all active users have to be returned.
Function call parameter, which tells phorum_api_user_get_list() that all users have to be returned.
Function call parameter, which tells phorum_api_user_get_list() that all inactive users have to be returned.
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.
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).
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.
Used for identifying admin sessions. The value is used as the name for the session cookie for admin sessions.
Used for identifying long term sessions. The value is used as the name for the session cookie for long term sessions.
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).
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.
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.
Subscription type, which tells Phorum to send out a mail message for every new forum or thread that a user is subscribed to.
Subscription type, which tells Phorum explicitly that the user does not have a subscription of any kind for the forum or thread.
User status, indicating that the registration has been completed and that the user can access the forums.
Permission flag which allows users to attach files to their forum messages.
Permission flag which allows users to edit their own forum messages.
Permission flag which allows users to edit other users' messages.
Permission flag which allows users to moderate user signup requests within the vroot.
Permission flag which allows users to start new forum topics.
Permission flag which allows users to read forum messages.
Permission flag which allows users to reply to forum messages.
Group permission flag for users which are active approved group members.
Group permission flag for users which are group moderator.
Group permission flag for users which are suspended by a group moderator.
Group permission flag for users which are not yet approved by a group moderator.
User status, indicating that the user has been deactivated.
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.
User status, indicating that the user has not yet confirmed the registration by email.
User status, indicating that the registration has not yet been approved by a user moderator.
Check the authentication credentials for a user.
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.
Check if a user has certain access right for forum(s).
Delete a Phorum user.
Retrieve data for Phorum users.
Retrieve the active Phorum user.
This function was added in Phorum 5.2.16.
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.
Retrieve the groups and their subscription statuses for a user.
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.
Retrieve the type of a single subscription.
Increment the posts counter for a user.
Retrieve a list of Phorum users.
Retrieve a list of moderators.
Retrieve the email addresses of the users that are subscribed to a forum/thread, grouped by the preferred language for these users.
Retrieve a list of threads to which a user is subscribed. The list can be limited to those threads which did receive contributions recently.
Create or update Phorum users.
This function can be used for both creating and updating Phorum users. If the user_id in the user data is NULL, 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.
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.
Save the groups and group permissions for a user.
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.
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.
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 keys in the arrays must be the same.
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 keys in the arrays must be the same.
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:
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:
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).
Destroy a Phorum user session.
This will destroy a Phorum user session and set the active Phorum user to the anonymous user.
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.
Set the active Phorum user.
This function can be used to setup the Phorum data in $PHORUM['user'] 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 in $PHORUM['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:
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.
Unsubscribe a user from a thread.
Documentation generated on Sat, 11 Jan 2014 01:45:52 -0600 by phpDocumentor 1.4.3