Allow modules to override Phorum's session restore management. This hook is the designated hook if you need to let Phorum inherit an authenticated session from some external system.

The array that is passed to this hook, contains a key for each of the Phorum session types:

What the module has to do, is fill the values for each of these keys with the user_id of the Phorum user for which the session that the key represents should be considered active. Other options are FALSE to indicate that no session is active and NULL to tell Phorum to handle session restore on its own.

Note that the user for which a user_id is provided through this hook must exist in the Phorum system before returning from this hook. One option to take care of that constraint is letting this hook create the user on-the-fly if needed. A cleaner way would be to synchronize the user data from the main system at those times when the user data changes (create, update and delete user). Of course it is highly dependent on the other system whether you can implement that kind of Phorum user management in the main application.

Hint: Creating users can be done using the phorum_api_user_save() user API function.

Call time:

Just before Phorum runs its own session restore code in the user API function phorum_api_user_session_restore().

Hook input:

An array containing three keys:

By default, all values for these keys are NULL.

Hook output:

Same as input, possibly with updated array values.

Example code:

See the ??? hook for an example of how to let Phorum setup the PHP session that is picked up in this example hook.

function phorum_mod_foo_user_session_restore($sessions)
{
    // Override the session handling for front end forum sessions.
    // We could for example retrieve a session from a standard PHP
    // session by first starting a PHP session if that was
    // not done yet...
    if (!session_id()) session_start();

    // ...and then retrieving the user_id of the current user
    // from the PHP session data. The user_id is really the
    // only thing that needs to be remembered for a Phorum
    // session, because all other data for the user is stored
    // in the database. If no user id was set in the session,
    // then use FALSE to flag this to Phorum.
    $phorum_user_id = empty($_SESSION['phorum_user_id'])
                    ? FALSE : $_SESSION['phorum_user_id'];

    // If we only use session inheritance for the front end
    // forum session (highly recommended for security), then
    // We keep PHORUM_SESSION_ADMIN at NULL (default value).
    // The other two need to be updated. If the main system does
    // not use the concept of one long and one short term cookie
    // (named "tight security" by Phorum), then simply assign
    // the user_id to both PHORUM_SESSION_LONG_TERM and
    // PHORUM_SESSION_SHORT_TERM.
    $sessions[PHORUM_SESSION_SHORT_TERM] = $phorum_user_id;
    $sessions[PHORUM_SESSION_LONG_TERM] = $phorum_user_id;

    return $sessions;
}