/** * Retrieve the data for forums and/or folders in various ways. Note that * only one of the parameters $forum_ids, $parent_id, $vroot and $inherit_id * will be effective at a time. The parameter $only_inherit_masters can be * used in conjunction with all of these. * * @param mixed $forum_ids * A single forum_id or an array of forum_ids for which to retrieve the * forum data. If this parameter is NULL, then the $parent_id * parameter will be checked. * * @param mixed $parent_id * Retrieve the forum data for all forums that have their parent_id set * to $parent_id. If this parameter is NULL, then the $vroot parameter * will be checked. * * @param mixed $inherit_id * Retrieve the forum data for all forums that inherit their settings * from the forum with id $inherit_id. * * @param mixed $vroot * Retrieve the forum data for all forums that are in the given $vroot. * If this parameter is NULL, then forums from any vroot will be * returned. This parameter can be used in combination with * the $forum_ids, $parent_id and $inherit_id parameters. * * @param integer $flags * If the {@link PHORUM_FLAG_INHERIT_MASTERS} flag is set, then * only forums that can act as a settings inheritance master will be * returned (these are the forums that do not inherit their settings * from either the default settings or from another forum). * If the {@link PHORUM_FLAG_FOLDERS} flag is set, then only * folders will be returned. * If the {@link PHORUM_FLAG_FORUMS} flag is set, then only * forums will be returned. * If the {@link PHORUM_FLAG_INCLUDE_INACTIVE} flag is set, then * inactive forums and folders will be included in the return data. * This is mainly useful for administrative interfaces that need to * be able to access all created forums and folders. * * @return mixed * If the $forum_ids parameter is used and if it contains a single * forum_id, then a single array containing forum data is returned or * NULL if the forum was not found. * For all other cases, an array of forum data arrays is returned, indexed * by the forum_id and sorted by their display order. If the $forum_ids * parameter is an array containing non-existent forum_ids, then the * return array will have no entry available in the returned array for * those forum_ids. */ function phorum_api_forums_get($forum_ids = NULL, $parent_id = NULL, $inherit_id = NULL, $vroot = NULL, $flags = 0) { global $PHORUM; // We might get an $inherit_id parameter that is NULL or -1, since we // present the database value NULL as -1 from this API (because using // NULL values in a form isn't really an option. $inherit_id = $inherit_id != -1 && $inherit_id !== NULL ? (int) $inherit_id : NULL; // Find the return_type parameter for the db call. // 0 = forums and folders, 1 = folders, 2 = forums. if ($flags & PHORUM_FLAG_FOLDERS) { $return_type = $flags & PHORUM_FLAG_FORUMS ? 0 : 1; } elseif ($flags & PHORUM_FLAG_FORUMS) { $return_type = 2; } else { $return_type = 0; } // Retrieve the forums/folders from the database. $forums = $PHORUM['DB']->get_forums($forum_ids, $parent_id, $vroot, $inherit_id, $flags & PHORUM_FLAG_INHERIT_MASTERS, $return_type, $flags & PHORUM_FLAG_INCLUDE_INACTIVE); // Process the returned records. foreach ($forums as $id => $forum) { $forums[$id]['folder_flag'] = $forum['folder_flag'] ? 1 : 0; $forums[$id]['forum_path'] = unserialize($forum['forum_path']); // This is a special one. The database value is NULL or // a positive integer, but NULL is not an easy value to // use in HTML forms. Therefore, we provide the value // -1 to indicate a NULL value here. $forums[$id]['inherit_id'] = $forum['inherit_id'] === NULL ? -1 : (int) $forum['inherit_id']; } // retrieve and apply the custom fields for forums if (!empty($PHORUM['CUSTOM_FIELDS'][PHORUM_CUSTOM_FIELD_FORUM])) { $forums = phorum_api_custom_field_apply(PHORUM_CUSTOM_FIELD_FORUM, $forums); } // If forum_id 0 (zero) is requested, then we create a fake folder // record. This is the root folder, which does not correspond to an // actual record in the database. if ($forum_ids !== NULL) { if (is_array($forum_ids) && in_array(0, $forum_ids) || !is_array($forum_ids) && $forum_ids !== NULL && $forum_ids == 0) { $template = $PHORUM['default_forum_options']['template']; $language = $PHORUM['default_forum_options']['language']; $forums[0] = array('forum_id' => 0, 'folder_flag' => 1, 'vroot' => 0, 'parent_id' => NULL, 'inherit_id' => 0, 'active' => 1, 'name' => $PHORUM['title'], 'description' => $PHORUM['description'], 'forum_path' => array(0 => $PHORUM['title']), 'template' => $template, 'language' => $language, 'cache_version' => 0, 'reg_perms' => 0, 'pub_perms' => 0); } } if ($forum_ids === NULL || is_array($forum_ids)) { return $forums; } else { return isset($forums[$forum_ids]) ? $forums[$forum_ids] : NULL; } }
/** * Retrieve data for Phorum users. * * @param mixed $user_id * Either a single user_id or an array of user_ids. * * @param boolean $detailed * If this parameter is TRUE (default is FALSE), then the user's * groups and permissions are included in the user data. * * @param 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. * * @param boolean $raw_data * This parameter is for internal use only. * When this parameter is TRUE (default is FALSE), then custom fields * that are configured with html_disabled will not be HTML encoded in * the return data. * * @return mixed * 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. */ function phorum_api_user_get($user_id, $detailed = FALSE, $use_write_server = FALSE, $raw_data = FALSE) { global $PHORUM; if (!is_array($user_id)) { $user_ids = array($user_id); } else { $user_ids = $user_id; } // Prepare the return data array. For each requested user_id, // a slot is prepared in this array. Also, turn the user id array // into an array that has the user_id as both the key and value. $users = array(); $new_user_ids = array(); foreach ($user_ids as $id) { $users[$id] = NULL; $new_user_ids[$id] = $id; } $user_ids = $new_user_ids; // First, try to retrieve user data from the user cache, // if user caching is enabled. if (!empty($PHORUM['cache_users'])) { $cached_users = phorum_api_cache_get('user', $user_ids); if (is_array($cached_users)) { foreach ($cached_users as $id => $user) { $users[$user['user_id']] = $user; unset($user_ids[$id]); } // We need to retrieve the data for some dynamic fields // from the database. $dynamic_data = $PHORUM['DB']->user_get_fields(array_keys($cached_users), array('date_last_active', 'last_active_forum', 'posts')); // Store the results in the users array. foreach ($dynamic_data as $d_user_id => $data) { $users[$d_user_id] = array_merge($users[$d_user_id], $data); } } } // Retrieve user data for the users for which no data was // retrieved from the cache. if (count($user_ids)) { $db_users = $PHORUM['DB']->user_get($user_ids, $detailed, $use_write_server); // Retrieve and apply the custom fields for users. if (!empty($PHORUM['CUSTOM_FIELDS'][PHORUM_CUSTOM_FIELD_USER])) { $db_users = phorum_api_custom_field_apply(PHORUM_CUSTOM_FIELD_USER, $db_users, $raw_data); } foreach ($db_users as $id => $user) { // Merge the group and forum permissions into a final // permission value per forum. Forum permissions that are // assigned to a user directly override any group based // permission. if (!$user['admin']) { if (!empty($user['group_permissions'])) { foreach ($user['group_permissions'] as $fid => $perm) { if (!isset($user['permissions'][$fid])) { $user['permissions'][$fid] = $perm; } else { $user['permissions'][$fid] |= $perm; } } } if (!empty($user['forum_permissions'])) { foreach ($user['forum_permissions'] as $fid => $perm) { $user['permissions'][$fid] = $perm; } } } // If detailed information was requested, we store the data in // the cache. For non-detailed information, we do not cache the // data, because there is not much to gain there by caching. if ($detailed && !empty($PHORUM['cache_users'])) { phorum_api_cache_put('user', $id, $user); } // Store the results in the users array. $users[$id] = $user; } } // Remove the users for which we did not find data from the array. foreach ($users as $id => $user) { if ($user === NULL) { unset($users[$id]); } } /** * [hook] * user_get * * [description] * This hook can be used to handle the data that was retrieved * from the database for a user. Modules can add and modify the * user data.<sbr/> * <sbr/> * In combination with the <hook>user_save</hook> hook, this hook * could also be used to store and retrieve some of the Phorum * user fields in some external system * * [category] * User data handling * * [when] * Just after user data has been retrieved from the database. * * [input] * This hook receives two arguments.<sbr/> * The first argument contains an array of users. * Each item in this array is an array containing data for * a single user, which can be updated.<sbr/> * The second argument contains a boolean that indicates whether * detailed information (i.e. including group info) is retrieved. * * [output] * The array that was used as the first argument for the hook call, * possibly with some updated users in it. * * [example] * <hookcode> * function phorum_mod_foo_user_get($user, $detailed) * { * // Let's asume that our usernames are based on the * // system users on a UNIX system. We could merge some * // info from the password file with the Phorum info here. * * // First try to lookup the password file entry. * // Return if this lookup fails. * $pw = posix_getpwnam($user['username']); * if (empty($pw)) return $user; * * // On a lot of systems, the "gecos" field contains * // the real name for the user. * $user['real_name'] = $pw["gecos"] != '' * ? $pw["gecos"] * : $user["real_name"]; * * // If a custom profile field "shell" was created, then * // we could also put the user's shell in the data. * $user['shell'] = $pw['shell']; * * return $user; * } * </hookcode> */ if (isset($PHORUM['hooks']['user_get'])) { $users = phorum_api_hook('user_get', $users, $detailed); } // A backward compatibility hook. The advised hook for modifying // loaded user data is "user_get" from above. if (isset($PHORUM["hooks"]["read_user_info"])) { $users = phorum_api_hook("read_user_info", $users); } // Return the results. if (is_array($user_id)) { return $users; } else { return isset($users[$user_id]) ? $users[$user_id] : NULL; } }