Elgg  Version 2.2
 All Classes Namespaces Files Functions Variables Pages
Namespaces | Functions | Variables
relationships.php File Reference

Go to the source code of this file.

Namespaces

 Elgg\Core
 Activate a plugin or plugins.
 

Functions

 get_relationship ($id)
 Get a relationship by its ID. More...
 
 delete_relationship ($id)
 Delete a relationship by its ID. More...
 
 add_entity_relationship ($guid_one, $relationship, $guid_two)
 Create a relationship between two entities. More...
 
 check_entity_relationship ($guid_one, $relationship, $guid_two)
 Check if a relationship exists between two entities. More...
 
 remove_entity_relationship ($guid_one, $relationship, $guid_two)
 Delete a relationship between two entities. More...
 
 remove_entity_relationships ($guid, $relationship="", $inverse_relationship=false, $type= '')
 Removes all relationships originating from a particular entity. More...
 
 get_entity_relationships ($guid, $inverse_relationship=false)
 Get all the relationships for a given GUID. More...
 
 elgg_get_entities_from_relationship ($options)
 Return entities matching a given query joining against a relationship. More...
 
 elgg_get_entity_relationship_where_sql ($column, $relationship=null, $relationship_guid=null, $inverse_relationship=false)
 Returns SQL appropriate for relationship joins and wheres. More...
 
 elgg_list_entities_from_relationship (array $options=array())
 Returns a viewable list of entities by relationship. More...
 
 elgg_get_entities_from_relationship_count (array $options=array())
 Gets the number of entities by a the number of entities related to them in a particular way. More...
 
 elgg_list_entities_from_relationship_count ($options)
 Returns a list of entities by relationship count. More...
 
 _elgg_relationships_test ($hook, $type, $tests)
 Register relationship unit tests. More...
 
 _elgg_relationship_init ()
 Initialize the relationship library private. More...
 

Variables

return function (\Elgg\EventsService $events,\Elgg\HooksRegistrationService $hooks)
 

Function Documentation

_elgg_relationship_init ( )

Initialize the relationship library private.

Definition at line 275 of file relationships.php.

_elgg_relationships_test (   $hook,
  $type,
  $tests 
)

Register relationship unit tests.

Parameters
string$hook
string$type
array$tests
Returns
array private

Definition at line 264 of file relationships.php.

add_entity_relationship (   $guid_one,
  $relationship,
  $guid_two 
)

Create a relationship between two entities.

E.g. friendship, group membership, site membership.

This function lets you make the statement "$guid_one is a $relationship of $guid_two". In the statement, $guid_one is the subject of the relationship, $guid_two is the target, and $relationship is the type.

Parameters
int$guid_oneGUID of the subject entity of the relationship
string$relationshipType of the relationship
int$guid_twoGUID of the target entity of the relationship
Returns
bool
Exceptions
InvalidArgumentException

Definition at line 45 of file relationships.php.

check_entity_relationship (   $guid_one,
  $relationship,
  $guid_two 
)

Check if a relationship exists between two entities.

If so, the relationship object is returned.

This function lets you ask "Is $guid_one a $relationship of $guid_two?"

Parameters
int$guid_oneGUID of the subject entity of the relationship
string$relationshipType of the relationship
int$guid_twoGUID of the target entity of the relationship
Returns
|false Depending on success

Definition at line 60 of file relationships.php.

delete_relationship (   $id)

Delete a relationship by its ID.

Parameters
int$idThe relationship ID
Returns
bool

Definition at line 27 of file relationships.php.

elgg_get_entities_from_relationship (   $options)

Return entities matching a given query joining against a relationship.

By default the function finds relationship targets. E.g.:

// find groups with a particular member: $options = [ 'relationship' => 'member', 'relationship_guid' => $member->guid, ];

// find people the user has friended $options = [ 'relationship' => 'friend', 'relationship_guid' => $user->guid, ];

// find stuff created by friends (not in groups) $options = [ 'relationship' => 'friend', 'relationship_guid' => $user->guid, 'relationship_join_on' => 'container_guid', ];

To find relationship subjects, set "inverse_relationship" to true. E.g.:

// find members of a particular group $options = [ 'relationship' => 'member', 'relationship_guid' => $group->guid, 'inverse_relationship' => true, ];

// find users who have friended the current user $options = [ 'relationship' => 'friend', 'relationship_guid' => $user->guid, 'inverse_relationship' => true, ];

Note
You may want to specify "type" because relationship types might be used for other entities.

This also accepts all options available to elgg_get_entities() and elgg_get_entities_from_metadata().

To ask for entities that do not have a particular relationship to an entity, use a custom where clause like the following:

$options['wheres'][] = "NOT EXISTS (
    SELECT 1 FROM {$db_prefix}entity_relationships
        WHERE guid_one = e.guid
        AND relationship = '$relationship'
)";
See Also
elgg_get_entities
elgg_get_entities_from_metadata
Parameters
array$optionsArray in format:

relationship => null|STR Type of the relationship. E.g. "member"

relationship_guid => null|INT GUID of the subject of the relationship, unless "inverse_relationship" is set to true, in which case this will specify the target.

inverse_relationship => false|BOOL Are we searching for relationship subjects? By default, the query finds targets of relationships.

relationship_join_on => null|STR How the entities relate: guid (default), container_guid, or owner_guid Examples using the relationship 'friend':

  1. use 'guid' if you want the user's friends
  2. use 'owner_guid' if you want the entities the user's friends own (including in groups)
  3. use 'container_guid' if you want the entities in the user's personal space (non-group)

relationship_created_time_lower => null|INT Relationship created time lower boundary in epoch time

relationship_created_time_upper => null|INT Relationship created time upper boundary in epoch time

Returns
[]|mixed If count, int. If not count, array. false on errors.
Since
1.7.0

Definition at line 188 of file relationships.php.

elgg_get_entities_from_relationship_count ( array  $options = array())

Gets the number of entities by a the number of entities related to them in a particular way.

This is a good way to get out the users with the most friends, or the groups with the most members.

Parameters
array$optionsAn options array compatible with elgg_get_entities_from_relationship()
Returns
[]|int|boolean If count, int. If not count, array. false on errors.
Since
1.8.0

Definition at line 237 of file relationships.php.

elgg_get_entity_relationship_where_sql (   $column,
  $relationship = null,
  $relationship_guid = null,
  $inverse_relationship = false 
)

Returns SQL appropriate for relationship joins and wheres.

Parameters
string$columnColumn name the GUID should be checked against. Provide in table.column format.
string$relationshipType of the relationship
int$relationship_guidEntity GUID to check
bool$inverse_relationshipIs $relationship_guid the target of the relationship?
Returns
mixed
Since
1.7.0 private

Definition at line 207 of file relationships.php.

elgg_list_entities_from_relationship ( array  $options = array())

Returns a viewable list of entities by relationship.

Parameters
array$optionsOptions array for retrieval of entities
See Also
elgg_list_entities()
elgg_get_entities_from_relationship()
Returns
string The viewable list of entities

Definition at line 223 of file relationships.php.

elgg_list_entities_from_relationship_count (   $options)

Returns a list of entities by relationship count.

See Also
elgg_get_entities_from_relationship_count()
Parameters
array$optionsOptions array
Returns
string
Since
1.8.0

Definition at line 251 of file relationships.php.

get_entity_relationships (   $guid,
  $inverse_relationship = false 
)

Get all the relationships for a given GUID.

Parameters
int$guidGUID of the subject or target entity (see $inverse)
bool$inverse_relationshipIs $guid the target of the relationships? By default $guid is the subject of the relationships.
Returns
[]

Definition at line 103 of file relationships.php.

get_relationship (   $id)

Get a relationship by its ID.

Parameters
int$idThe relationship ID
Returns
|false False if not found

Definition at line 16 of file relationships.php.

remove_entity_relationship (   $guid_one,
  $relationship,
  $guid_two 
)

Delete a relationship between two entities.

This function lets you say "$guid_one is no longer a $relationship of $guid_two."

Parameters
int$guid_oneGUID of the subject entity of the relationship
string$relationshipType of the relationship
int$guid_twoGUID of the target entity of the relationship
Returns
bool

Definition at line 75 of file relationships.php.

remove_entity_relationships (   $guid,
  $relationship = "",
  $inverse_relationship = false,
  $type = '' 
)

Removes all relationships originating from a particular entity.

Parameters
int$guidGUID of the subject or target entity (see $inverse)
string$relationshipType of the relationship (optional, default is all relationships)
bool$inverse_relationshipIs $guid the target of the deleted relationships? By default, $guid is the subject of the relationships.
string$typeThe type of entity related to $guid (defaults to all)
Returns
true

Definition at line 90 of file relationships.php.

Variable Documentation

Definition at line 279 of file relationships.php.