The following information is provided from user_relationships/user_relationships_api/user_relationships_api.api.inc

Please refer to that file for the most up to date documentation.

The main module is built to be as bare-bones as possible then provide an API that other developers can take advantage of. By way of example, as well as to keep the size of the main module down, there are several plugin modules bundled with the core module. These should give you an example of how plugins can be developed to extend and enhance the functionality of the core.

/**
 * Public API for retrieving a specific relationship
 *
 * @param $param
 *    The rtid or an associative array of attributes to search for in selecting the
 *    relationship, such as rtid or name. Attributes must match column names
 *    in the user_relationship_types table.
 *
 * @param $reset
 *    a boolean that forces a reset of the internal static types list
 *
 * @return
 *    object of the requested relationship type
 *
 */
function user_relationships_type_load($param = array(), $reset = NULL) {

/**
 * Public API for loading the full list of relationship types
 *
 * @param $reset
 *    a boolean that forces a reset of the internal static types list
 *
 * @return
 *    array of relationship_type objects
 */
function user_relationships_types_load($reset = NULL) {

/**
 * Create or Update a User Relationship Type
 *
 * @param $rtype
 *   A User Relationship type object
 */
function user_relationships_type_save(&$rtype) {

/**
 * Delete a User Relationship Type
 *
 * @param $rtid
 *   A User Relationship type ID
 */
function user_relationships_type_delete($rtid) {

/**
 * Request a new user relationship
 *
 * @param $requester
 *   object or UID of the requester
 * @param $requestee
 *   object  or UID of the requestee
 * @param $type
 *   object or RTID of the relationship type
 * @param $approved
 *    boolean status of the relationship
 *
 * @return
 *    object of the newly created relationship
 */
function user_relationships_request_relationship($requester, $requestee = NULL, $type = NULL, $approved = FALSE) {

/**
 * Create or update a user relationship.
 *
 * @param $relationship
 *   object of the current relationship
 * @param $op
 *   the reason for the update
 *
 * @return
 *    object of the updated relationship
 *    or
 *    false if the relationship wasn't able to save
 */
function user_relationships_save_relationship(&$relationship, $op = 'request') {

/**
 * Public API for deleting a relationship.
 *
 * @param $relationship
 *    object of the relationship
 * @param $deleted_by
 *    object of the user that initiated the delete command
 * @param $op
 *    string reason for removal ('cancel','disapprove','remove')
 */
function user_relationships_delete_relationship(&$relationship, &$deleted_by, $op = 'remove') {

/**
  * Load relationship objects from the database.
  *
  * @param $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_at, updated_at, 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_at' => ">= {$start_time}", 'created_at' => '< {$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)
  *
  * @param @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'
  *
  * @param $reset
  *   a boolean that will reset the internal static $relationships variable to ensure programatic relationship insertion works
  *
  * @return
  *   an array of relationships
  *   if the key is "rid" the array will be a single dimention: array($rid => $relationship, $rid => $relationship)
  *   otherwise it'll be multidimentional: 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
 */
function user_relationships_load($param = array(), $options = array(), $reset = FALSE) {

/**
 * Used when the "include_user_info" option is set on user_relationships_load
 * to translate the retrieved user fields into actual user objects. This allows us
 * to pull the basic user data without having to run user_load
 *
 * @param $relationship
 *    The relationship object with pulled user info
 */
function user_relationships_api_translate_user_info(&$relationship) {

/**
 * Check whether a user is allowed to request a certain relationship type
 *
 * @param $requester requesting user object or uid
 * @param $relationship_type loaded relationship type object or rtid
 * @return TRUE iff requester is allowed to request this type of relationship
 */
function user_relationships_api_can_request($requester, $relationship_type) {

/**
 * Check whether a user is allowed to receive a certain relationship type
 *
 * @param $requestee requesting user object or uid
 * @param $relationship_type loaded relationship type object or rtid
 * @return TRUE iff receiver is allowed to request this type of relationship
 */
function user_relationships_api_can_receive($requestee, $relationship_type) {

/**
 * Implements the hook_cck_field_privacy_access to allow users to display privacy fields
 * based on a relationship with other users
 */
function user_relationships_api_cck_field_privacy_access($requestee, $requester) {

Comments

mansspams’s picture

mansspams commented

code has changed, up to date and well commented code in module, file user_relationships_api.api.inc in directory user_relationships\user_relationships_api, look for function user_relationships_load

here is code to get relationship request count

<?php
 $requests = user_relationships_load($param = array("approved" => 0, "user" => $account->uid), $options = array(), $reset = FALSE);
 $requestcount = count($requests);
?>

$requests is array of all requests. "approved" => 0 means we only need requests or unapproved relationships (1 is to get list of approved relationships) and "user" => $account->uid is to get relationship data for particular user, insert UID or remove element alltogather to get all relationships.

menteb’s picture

menteb commented

I needed a selection list of connected users in a content type.
This is how I did it. Feel free to shorten where possible.
The code will return an array containing the UID as key and the Username as value.

global $user;
$relationship = "Buddy";
$currentuser = $user->uid;

$items = user_relationships_load($param = array("user" => $currentuser, "name" => $relationship, "approved" => 1), $options = array("include_user_info" => 1));

foreach($items as $item):
  if ($item->requester->uid != $currentuser): 
    $buddyuid = $item->requester->uid;
    $buddyname = $item->requester->name;
    $buddies[$buddyuid] = $buddyname;
  endif;
  if ($item->requestee->uid != $currentuser): 
    $buddyuid = $item->requestee->uid;
    $buddyname = $item->requestee->name;
    $buddies[$buddyuid] = $buddyname;
  endif;
endforeach;

return $buddies;
aidanlis’s picture

aidanlis commented

The user_relationships API is a bit of a joke; it seems nearly impossible to do simple things. Here's a simple function to check if a relationship exists:

/**
 * Check if a relationship exists.
 *
 * Returns the number of active relationships.
 */
function _user_relationships_relationship_exists($requester, $requestee, $rtid) {
  return db_result(db_query('SELECT COUNT(rid) AS count FROM {user_relationships} WHERE requester_id=%d AND requestee_id=%d AND rtid=%d AND approved=1',
    $requester, $requestee, $rtid));
}