/**
* Return entities matching a given query joining against a relationship.
* 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 elgg_get_entities
* @see elgg_get_entities_from_metadata
*
* @param array $options Array 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
*
* @return \ElggEntity[]|mixed If count, int. If not count, array. false on errors.
*/
public function getEntities($options)
{
$defaults = array('relationship' => null, 'relationship_guid' => null, 'inverse_relationship' => false, 'relationship_join_on' => 'guid', 'relationship_created_time_lower' => ELGG_ENTITIES_ANY_VALUE, 'relationship_created_time_upper' => ELGG_ENTITIES_ANY_VALUE);
$options = array_merge($defaults, $options);
$join_column = "e.{$options['relationship_join_on']}";
$clauses = $this->getEntityRelationshipWhereSql($join_column, $options['relationship'], $options['relationship_guid'], $options['inverse_relationship']);
if ($clauses) {
// merge wheres to pass to get_entities()
if (isset($options['wheres']) && !is_array($options['wheres'])) {
$options['wheres'] = array($options['wheres']);
} elseif (!isset($options['wheres'])) {
$options['wheres'] = array();
}
$options['wheres'] = array_merge($options['wheres'], $clauses['wheres']);
// limit based on time created
$time_wheres = $this->entities->getEntityTimeWhereSql('r', $options['relationship_created_time_upper'], $options['relationship_created_time_lower']);
if ($time_wheres) {
$options['wheres'] = array_merge($options['wheres'], array($time_wheres));
}
// merge joins to pass to get_entities()
if (isset($options['joins']) && !is_array($options['joins'])) {
$options['joins'] = array($options['joins']);
} elseif (!isset($options['joins'])) {
$options['joins'] = array();
}
$options['joins'] = array_merge($options['joins'], $clauses['joins']);
if (isset($options['selects']) && !is_array($options['selects'])) {
$options['selects'] = array($options['selects']);
} elseif (!isset($options['selects'])) {
$options['selects'] = array();
}
$select = array('r.id');
$options['selects'] = array_merge($options['selects'], $select);
if (!isset($options['group_by'])) {
$options['group_by'] = $clauses['group_by'];
}
}
return $this->metadata->getEntities($options);
}