Entities are the basic unit of storage in Elgg. This function
provides the simplest way to get an array of entities. There
are many options available that can be passed to filter
what sorts of entities are returned.
| public getEntities ( array $options = [] ) : ElggEntity[] | integer | mixed | ||
| $options | array | Array in format: types => null|STR entity type (type IN ('type1', 'type2') Joined with subtypes by AND. See below) subtypes => null|STR entity subtype (SQL: subtype IN ('subtype1', 'subtype2)) Use ELGG_ENTITIES_NO_VALUE to match the default subtype. Use ELGG_ENTITIES_ANY_VALUE to match any subtype. type_subtype_pairs => null|ARR (array('type' => 'subtype')) array( 'object' => array('blog', 'file'), // All objects with subtype of 'blog' or 'file' 'user' => ELGG_ENTITY_ANY_VALUE, // All users irrespective of subtype ); guids => null|ARR Array of entity guids owner_guids => null|ARR Array of owner guids container_guids => null|ARR Array of container_guids order_by => null (time_created desc)|STR SQL order by clause reverse_order_by => BOOL Reverse the default order by clause limit => null (10)|INT SQL limit clause (0 means no limit) offset => null (0)|INT SQL offset clause created_time_lower => null|INT Created time lower boundary in epoch time created_time_upper => null|INT Created time upper boundary in epoch time modified_time_lower => null|INT Modified time lower boundary in epoch time modified_time_upper => null|INT Modified time upper boundary in epoch time count => true|false return a count instead of entities wheres => array() Additional where clauses to AND together joins => array() Additional joins preload_owners => bool (false) If set to true, this function will preload all the owners of the returned entities resulting in better performance if those owners need to be displayed preload_containers => bool (false) If set to true, this function will preload all the containers of the returned entities resulting in better performance if those containers need to be displayed callback => string A callback function to pass each row through distinct => bool (true) If set to false, Elgg will drop the DISTINCT clause from the MySQL query, which will improve performance in some situations. Avoid setting this option without a full understanding of the underlying SQL query Elgg creates. batch => bool (false) If set to true, an Elgg\BatchResult object will be returned instead of an array. Since 2.3 batch_inc_offset => bool (true) If "batch" is used, this tells the batch to increment the offset on each fetch. This must be set to false if you delete the batched results. batch_size => int (25) If "batch" is used, this is the number of entities/rows to pull in before requesting more. |
| return | ElggEntity[] | integer | mixed | If count, int. Otherwise an array or an Elgg\BatchResult. false on errors. |
/**
* Returns entities based upon private settings
*
* Also accepts all options available to elgg_get_entities(). Supports
* the singular option shortcut.
*
* @param array $options Array in format:
*
* private_setting_names => null|ARR private setting names
*
* private_setting_values => null|ARR metadata values
*
* private_setting_name_value_pairs => null|ARR (
* name => 'name',
* value => 'value',
* 'operand' => '=',
* )
* Currently if multiple values are sent via
* an array (value => array('value1', 'value2')
* the pair's operand will be forced to "IN".
*
* private_setting_name_value_pairs_operator => null|STR The operator to
* use for combining
* (name = value) OPERATOR (name = value);
* default AND
*
* private_setting_name_prefix => STR A prefix to apply to all private
* settings. Used to namespace plugin user
* settings or by plugins to namespace their
* own settings.
*
* @return mixed int If count, int. If not count, array. false on errors.
*/
public function getEntities(array $options = array())
{
$defaults = array('private_setting_names' => ELGG_ENTITIES_ANY_VALUE, 'private_setting_values' => ELGG_ENTITIES_ANY_VALUE, 'private_setting_name_value_pairs' => ELGG_ENTITIES_ANY_VALUE, 'private_setting_name_value_pairs_operator' => 'AND', 'private_setting_name_prefix' => '');
$options = array_merge($defaults, $options);
$singulars = array('private_setting_name', 'private_setting_value', 'private_setting_name_value_pair');
$options = _elgg_normalize_plural_options_array($options, $singulars);
$clauses = $this->getWhereSql('e', $options['private_setting_names'], $options['private_setting_values'], $options['private_setting_name_value_pairs'], $options['private_setting_name_value_pairs_operator'], $options['private_setting_name_prefix']);
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']);
// 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']);
}
return $this->entities->getEntities($options);
}
/**
* Constructor
*
* @param EntityCache $entity_cache Entity cache
* @param EntityTable $entity_table Entity service
*/
public function __construct(EntityCache $entity_cache, EntityTable $entity_table)
{
$this->_callable_cache_checker = function ($guid) use($entity_cache) {
return $entity_cache->get($guid);
};
$this->_callable_entity_loader = function ($options) use($entity_table) {
return $entity_table->getEntities($options);
};
}
/**
* Returns entities based upon metadata. Also accepts all
* options available to elgg_get_entities(). Supports
* the singular option shortcut.
*
* @note Using metadata_names and metadata_values results in a
* "names IN (...) AND values IN (...)" clause. This is subtly
* differently than default multiple metadata_name_value_pairs, which use
* "(name = value) AND (name = value)" clauses.
*
* When in doubt, use name_value_pairs.
*
* To ask for entities that do not have a metadata value, use a custom
* where clause like this:
*
* $options['wheres'][] = "NOT EXISTS (
* SELECT 1 FROM {$dbprefix}metadata md
* WHERE md.entity_guid = e.guid
* AND md.name_id = $name_metastring_id
* AND md.value_id = $value_metastring_id)";
*
* Note the metadata name and value has been denormalized in the above example.
*
* @see elgg_get_entities
*
* @param array $options Array in format:
*
* metadata_names => null|ARR metadata names
*
* metadata_values => null|ARR metadata values
*
* metadata_name_value_pairs => null|ARR (
* name => 'name',
* value => 'value',
* 'operand' => '=',
* 'case_sensitive' => true
* )
* Currently if multiple values are sent via
* an array (value => array('value1', 'value2')
* the pair's operand will be forced to "IN".
* If passing "IN" as the operand and a string as the value,
* the value must be a properly quoted and escaped string.
*
* metadata_name_value_pairs_operator => null|STR The operator to use for combining
* (name = value) OPERATOR (name = value); default AND
*
* metadata_case_sensitive => BOOL Overall Case sensitive
*
* order_by_metadata => null|ARR array(
* 'name' => 'metadata_text1',
* 'direction' => ASC|DESC,
* 'as' => text|integer
* )
* Also supports array('name' => 'metadata_text1')
*
* metadata_owner_guids => null|ARR guids for metadata owners
*
* @return \ElggEntity[]|mixed If count, int. If not count, array. false on errors.
*/
function getEntities(array $options = array())
{
$defaults = array('metadata_names' => ELGG_ENTITIES_ANY_VALUE, 'metadata_values' => ELGG_ENTITIES_ANY_VALUE, 'metadata_name_value_pairs' => ELGG_ENTITIES_ANY_VALUE, 'metadata_name_value_pairs_operator' => 'AND', 'metadata_case_sensitive' => true, 'order_by_metadata' => array(), 'metadata_owner_guids' => ELGG_ENTITIES_ANY_VALUE);
$options = array_merge($defaults, $options);
$singulars = array('metadata_name', 'metadata_value', 'metadata_name_value_pair', 'metadata_owner_guid');
$options = _elgg_normalize_plural_options_array($options, $singulars);
if (!($options = _elgg_entities_get_metastrings_options('metadata', $options))) {
return false;
}
return $this->entityTable->getEntities($options);
}
