function user_relationships_load in User Relationships 7

Same name and namespace in other branches

1. 5.3 user_relationships_api/user_relationships_api.api.inc \user_relationships_load()
2. 5.2 user_relationships_api.inc \user_relationships_load()
3. 6 user_relationships_api/user_relationships_api.api.inc \user_relationships_load()

Load relationship objects from the database.

Parameters

$param: an array of parameters with the key being the column. columns from both the user_relationships and user_relationship_types tables will work columns from user_relationships: rid, requester_id, requestee_id, rtid, approved, created, changed, flags columns from user_relationship_types: name, plural_name, is_oneway, requires_approval, expires_val There are two special keys: 1) array("between" => array($uid1, $uid2)) will return all relationships between the two user ids. 2) array("user" => $uid) will return all relationships for the specified uid

arguments will process operators as well using the syntax: array(col => '> {value}'). example: show all relationships created in 2007 $start_time = mktime(0,0,0,0,0,2007); $end_time = mktime(0,0,0,0,0,2008); user_relationships_load(array('created' => ">= {$start_time}", 'created' => '< {$end_time'}));

each parameter may be an array, if you wish to pass several values example: user_relationships_load(array('rtid' => array(2, 3), 'between' => array($uid1, $uid2))) will load all relationships of types 2 or 3 between uid1 and uid2 (query will have an IN clause)

@options: An array keyed by the option count a boolean stating whether or not the return value should be the number of relationships found

sort a string containing a valid column name which will become the key for the returned array of relationships default is 'rid'

order a string containing SQL stating the column and direction of the sort (ex. "requester_id ASC, rtid DESC")

limit a string containing SQL stating the limit (ex "10" or "10, 5")

include_user_info a boolean that will load basic user info without having to call user_load columns: uid, name, mail, data, picture

include_twoway_reverse (not used unless there is a specific need) a boolean that, if present, and if sort is set to other than 'rid', will include records for both directions for two-way relationships. Normally for a two-way relationship only one entry is returned, although in the database there are two records. This flag has no effect if sort is 'rid'

$reset: a boolean that will reset the internal static $relationships variable to ensure programmatic relationship insertion works

Return value

an array of relationships if the key is "rid" the array will be a single dimension: array($rid => $relationship, $rid => $relationship) otherwise it'll be multidimensional: array($rtid => array($relationship, $relationship))

each relationship will have the user's name, mail, and data attached as requester_name, requester_mail, requester_data or requestee_name, requestee_mail, requestee_data

36 calls to user_relationships_load()

template_preprocess_user_relationships_block in user_relationship_blocks/user_relationship_blocks.module

Template pre processor for the main block view

template_preprocess_user_relationships_pending_block in user_relationship_blocks/user_relationship_blocks.module

Template pre processor for the pending relationships block

theme_user_relationship_implications_page in user_relationship_implications/user_relationship_implications.module

Categorized list of relationships for a given user

UserRelationshipsTestCase::testNoOnewayRelationships in ./user_relationships.test

Test the load functions if there are no one way relationship types.

UserRelationshipsTestCase::testRelationshipAPI in ./user_relationships.test

Test various relationship APi functions and params.

... See full list

File

./user_relationships.module, line 780

User Relationships API. Module shell.

Code

function user_relationships_load($param = array(), $options = array(), $reset = FALSE) {
  static $relationships = array();
  $default_options = array(
    'sort' => 'rid',
  );
  $options = array_merge($default_options, $options);
  extract($options, EXTR_SKIP);
  if (is_numeric($param)) {
    if (!$reset && isset($relationships[$param])) {
      return is_object($relationships[$param]) ? clone $relationships[$param] : $relationships[$param];
    }
    $rid = $param;
    $param = array(
      'rid' => $param,
    );
  }
  $options['only_count'] = !empty($count);
  $query = _user_relationships_generate_query($param, $options);
  if (!empty($count)) {
    return (int) $query
      ->execute()
      ->fetchField();
  }
  $relationships = array();
  foreach ($query
    ->execute() as $relationship) {
    if (isset($include_user_info)) {
      user_relationships_translate_user_info($relationship);
    }
    if ($sort == 'rid') {
      $relationships[$relationship->{$sort}] = $relationship;
    }
    else {
      $relationships[$relationship->{$sort}][] = $relationship;
    }
  }
  if (isset($rid) && !isset($relationships[$rid])) {
    return FALSE;
  }

  // Always call the hook with an array, even though there is only single entry.
  if (isset($rid)) {
    $return = $relationships[$rid];
    module_invoke_all('user_relationships_load', array(
      $rid => $return,
    ));
  }
  else {
    $return = $relationships;

    // Only execute the hook if the array is not empty.
    if (!empty($return)) {
      module_invoke_all('user_relationships_load', $return);
    }
  }
  return $return;
}