Functions
	elgg_get_entity_class (string $type, string $subtype)
	Return the class name registered as a constructor for an entity of a given type and subtype. More...

	elgg_set_entity_class (string $type, string $subtype, string $class= '')
	Sets class constructor name for entities with given type and subtype. More...

	elgg_get_entity_as_row (int $guid)
	Returns a database row from the entities table. More...

	get_entity (int $guid)
	Loads and returns an entity object from a guid. More...

	elgg_entity_exists (int $guid)
	Does an entity exist? More...

	elgg_get_site_entity ()
	Get the current site entity. More...

	elgg_get_entities (array $options=[])
	Fetches/counts entities or performs a calculation on their properties. More...

	elgg_count_entities (array $options=[])
	Returns a count of entities. More...

	elgg_list_entities (array $options=[], callable $getter=null, callable $viewer=null)
	Returns a string of rendered entities. More...

	elgg_get_entity_dates (array $options=[])
	Returns a list of months in which entities were updated or created. More...

	elgg_search (array $options=[])
	Returns search results as an array of entities, as a batch, or a count, depending on parameters given. More...

	elgg_get_entity_statistics (array $options=[])
	Return an array reporting the number of various entities in the system. More...

	elgg_entity_has_capability (string $type, string $subtype, string $capability, bool $default=false)
	Checks if a capability is enabled for a specified type/subtype. More...

	elgg_entity_enable_capability (string $type, string $subtype, string $capability)
	Enables the capability for a specified type/subtype. More...

	elgg_entity_disable_capability (string $type, string $subtype, string $capability)
	Disables the capability for a specified type/subtype. More...

	elgg_entity_types_with_capability (string $capability)
	Returns an array of type/subtypes with the requested capability enabled. More...

Function Documentation

elgg_count_entities ( array $options = [] )

Returns a count of entities.

Parameters

array $options the same options as elgg_get_entities() but forces 'count' to true

Returns: int

Definition at line 518 of file entities.php.

elgg_entity_disable_capability	(	string	$type,
		string	$subtype,
		string	$capability
	)

Disables the capability for a specified type/subtype.

Parameters

string	$type	type of the entity
string	$subtype	subtype of the entity
string	$capability	name of the capability to set

Returns: void

Since: 4.1

Definition at line 745 of file entities.php.

elgg_entity_enable_capability	(	string	$type,
		string	$subtype,
		string	$capability
	)

Enables the capability for a specified type/subtype.

Parameters

string	$type	type of the entity
string	$subtype	subtype of the entity
string	$capability	name of the capability to set

Returns: void

Since: 4.1

Definition at line 731 of file entities.php.

elgg_entity_exists ( int $guid )

Does an entity exist?

This function checks for the existence of an entity independent of access permissions. It is useful for situations when a user cannot access an entity and it must be determined whether entity has been deleted or the access level has changed.

Parameters

int $guid The GUID of the entity

Returns: bool

Since: 1.8.0

Definition at line 91 of file entities.php.

elgg_entity_has_capability	(	string	$type,
		string	$subtype,
		string	$capability,
		bool	$default = `false`
	)

Checks if a capability is enabled for a specified type/subtype.

Parameters

string	$type	type of the entity
string	$subtype	subtype of the entity
string	$capability	name of the capability to check
bool	$default	default value to return if it is not explicitly set

Returns: bool

Since: 4.1

Definition at line 717 of file entities.php.

elgg_entity_types_with_capability ( string $capability )

Returns an array of type/subtypes with the requested capability enabled.

Parameters

string $capability name of the capability to set

Returns: array

Since: 4.1

Definition at line 757 of file entities.php.

elgg_get_entities ( array $options = [] )

Fetches/counts entities or performs a calculation on their properties.

Note that you can use singulars for most options, e.g. $options['type'] will be normalized to $options['types']

TYPE SUBTYPE CONSTRAINTS

Filter entities by their type and subtype

string[] $types string[] $subtypes string[] $type_subtype_pairs

$options['types'] = ['object']; $options['subtypes'] = ['blog', 'file']; $options['type_subtype_pairs'] = [ 'object' => ['blog', 'file'], 'group' => [], // all group subtypes 'user' => null, // all user subtypes ];

GUID CONSTRAINTS

Filter entities by their guid, owner or container

int[]|ElggEntity[] $guids int[]|ElggEntity[] $owner_guids int[]|ElggEntity[] $container_guids

TIME CONSTRAINTS

Filter entities that were created, updated or last acted on within certain bounds

$options['created_after'] = '-1 year'; $options['created_before'] = 'now';

ACCESS CONSTRAINTS

Filter entities by their access_id attribute. Note that this filter apply to entities that the user has access to. You can ignore access system using elgg_call()

int[] $access_id

LIMIT AND OFFSET

This options are used for paginating lists of entities

int $limit int $offset

METADATA CONSTRAINTS

Filter entities by their metadata and attributes

The following options will be merged and applied as a metadata pair to ['metadata_name_value_pairs'] Note metadata names can contain attributes names and will be resolved automatically during query building. int[] $metadata_ids string[] $metadata_names mixed $metadata_values DateTime|string|int $metadata_created_after DateTime|string|int $metadata_created_before bool $metadata_case_sensitive

Metadata name value pairs will be joined by the boolean specified in $metadata_name_value_pairs_operator array $metadata_name_value_pairs string $metadata_name_value_pairs_operator

In addition to metadata name value pairs, you can specify search pair, which will be merged using OR boolean and will filter entities regardless of metadata name value pairs and their operator

Warning: During normalization, search name value pairs will ignore properties under metadata_ namespace, that is you can not use metadata_ids, metadata_created_before, metadata_created_after, metadata_case_sensitive to constrain search pairs. You will need to pass these properties for each individual search pair, as seen in the example below

array $search_name_value_pairs

// Search for entities with: // status of draft or unsaved_draft // AND index greater than 5 // AND (title/description containing the word hello OR tags containing the word world) $options['metadata_name_value_pairs'] = [ [ 'name' => 'status', 'value' => ['draft', 'unsaved_draft'], 'operand' => 'IN', 'created_after' => '-1 day', ], [ 'name' => 'index', 'value' => 5, 'operand' => '>=', 'type' => ELGG_VALUE_INTEGER, ] ]; $options['search_name_value_pairs'] = [ [ 'name' => ['title', 'description'], 'value' => 'hello', 'operand' => 'LIKE', 'case_sensitive' => false, ], [ // 'ids' => [55, 56, 57, 58, 59, 60], // only search these 5 metadata rows 'name' => 'tags', 'value' => 'world', 'operand' => 'LIKE', 'case_sensitive' => false, 'created_after' => '-1 day', 'created_before' => 'now', ], ];

ANNOTATION CONSTRAINTS

Filter entities by their annotations

The following options will be merged and applied as an annotation pair to ['annotation_name_value_pairs'] int[] $annotation_ids string[] $annotation_names mixed $annotation_values bool $annotation_case_sensitive DateTime|string|int $annotation_created_after DateTime|string|int $annotation_created_before int[]|ElggEntity[] $annotation_owner_guids int[]|ElggEntity[] $annotation_access_ids

Annotation name value pairs will be joined by the boolean specified in $annotation_name_value_pairs_operator array $annotation_name_value_pairs string $annotation_name_value_pairs_operator

$options['annotation_name_value_pairs'] = [ [ 'name' => 'likes', 'created_after' => '-1 day', ], [ 'name' => 'rating', 'value' => 5, 'operand' => '>=', 'type' => ELGG_VALUE_INTEGER, ], [ 'name' => 'review', 'value' => 'awesome', 'operand' => 'LIKE', 'type' => ELGG_VALUE_STRING, ] ];

RELATIONSHIP CONSTRAINTS

Filter entities by their relationships

The following options will be merged and applied as a relationship pair to $options['relationship_name_value_pairs'] int[] $relationship_ids string[] $relationship int[]|ElggEntity[] $relationship_guid bool $inverse_relationship DateTime|string|int $relationship_created_after DateTime|string|int $relationship_created_before string $relationship_join_on Column name in the name main table

array $relationship_pairs

// Get all entities that user with guid 25 has friended or been friended by $options['relationship_pairs'] = [ [ 'relationship' => 'friend', 'relationship_guid' => 25, 'inverse_relationship' => true, ], [ 'relationship' => 'friend', 'relationship_guid' => 25, 'inverse_relationship' => false, ], ];

SORTING

You can specify sorting options using ONE of the following options

NOTE: Some order by options only work when fetching entities and not from derived function (eg elgg_get_annotations, elgg_get_relationships)

Order by a calculation performed on annotation name value pairs $option array annotation_sort_by_calculation e.g. avg, max, min, sum

Order by arbitrary clauses array $order_by

Order by attribute/annotation/metadata sort_by an array of sorting definitions

$sort_by = new (); $sort_by->property = 'private'; $sort_by->property_type = 'metadata'; $sort_by->join_type = 'left';

$fallback = new ('e.time_created', 'desc');

$options['order_by'] = [ $sort_by, $fallback, ];

//

See also

// single sort_by option $options['sort_by'] = [ 'property_type' => 'attribute', 'property' => 'time_created', 'direction' => 'ASC', ];

// multiple sort_by options $options['sort_by'] = [ [ 'property_type' => 'attribute', 'property' => 'time_created', 'direction' => 'ASC', ], [ 'property_type' => 'metadata', 'property' => 'name', 'direction' => 'DESC', ], [ 'property_type' => 'annotation', 'property' => 'priority', 'direction' => 'ASC', 'signed' => true, ], [ 'property_type' => 'relationship', 'property' => 'members', 'direction' => 'ASC', 'inverse_relationship' => true, ], ];

COUNT/CALCULATION

Performs a calculation on a set of entities that match all of the criteria If any of these are specific, the return of this function will be int or float

Return total number of entities bool $count

Perform a calculation on a set of entity's annotations using a numeric sql function If specified, the number of annotation name value pairs can not be more than 1, or they must be merged using OR operator string $annotation_calculation e.g. avg, max, min, sum

Perform a calculation on a set of entity's metadat using a numeric sql function If specified, the number of metadata name value pairs can not be more than 1, or they must be merged using OR operator string $metadata_calculation e.g. avg, max, min, sum

SQL SELECT

array $selects $options['selects'] = [ 'e.last_action AS last_action', function(QueryBulder $qb, $main_alias) { $joined_alias = $qb->joinMetadataTable($main_alias, 'guid', 'status'); return "$joined_alias.value AS status"; } ];

SQL JOIN

array $joins $on = function(QueryBuilder $qb, $joined_alias, $main_alias) { return $qb->compare("$joined_alias.user_guid", '=', "$main_alias.guid"); }; $options['joins'] = [ new JoinClause('access_collections_membership', 'acm', $on); ];

SQL GROUPS

array $group_by array $having

$options['group_by'] = [ function(QueryBuilder $qb, $main_alias) { return "$main_alias.guid"; } ]; $options['having'] = [ function(QueryBuilder $qb, $main_alias) { return $qb->compare("$main_alias.guid", '>=', 50, ELGG_VALUE_INTEGER); } ];

SQL WHERE

array $where $options['wheres'] = [ function(QueryBuilder $qb, $main_alias) { return $qb->merge([ $qb->compare("$main_alias.guid", '>=', 50, ELGG_VALUE_INTEGER), $qb->compare("$main_alias.guid", '<=', 250, ELGG_VALUE_INTEGER), ], 'OR'); } ];

RESULT OPTIONS

bool $distinct 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. Default: true callable|false $callback A callback function to pass each row through Default: _elgg_services()->entityTable->rowToElggStar() bool $preload_owners If set to true, this function will preload all the owners of the returned entities resulting in better performance when displaying entities owned by several users Default: false bool $preload_containers If set to true, this function will preload all the containers of the returned entities resulting in better performance when displaying entities contained by several users/groups Default: false bool $batch If set to true, an object will be returned instead of an array. Default: false bool $batch_inc_offset 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. Default: true int $batch_size If "batch" is used, this is the number of entities/rows to pull in before requesting more. Default: 25

See also: elgg_list_entities()

Parameters

array $options Options

Returns: []|int|mixed If count, int. Otherwise an array or an

Since: 1.7.0

Definition at line 507 of file entities.php.

elgg_get_entity_as_row ( int $guid )

Returns a database row from the entities table.

Use get_entity() to return the fully loaded entity.

Warning: This will only return results if a) it exists, b) you have access to it.

Parameters

int $guid The GUID of the object to extract

Returns: |null

Definition at line 59 of file entities.php.

elgg_get_entity_class	(	string	$type,
		string	$subtype
	)

Return the class name registered as a constructor for an entity of a given type and subtype.

See also: elgg_set_entity_type()

Parameters

string	$type	The type
string	$subtype	The subtype

Returns: string

Definition at line 21 of file entities.php.

elgg_get_entity_dates ( array $options = [] )

Returns a list of months in which entities were updated or created.

Use this to generate a list of archives by month for when entities were added or updated.

Warning: Months are returned in the form YYYYMM.

Parameters

array $options all entity options supported by {

See also: elgg_get_entities()}

Returns: array An array months as YYYYMM

Since: 3.0

Definition at line 616 of file entities.php.

elgg_get_entity_statistics ( array $options = [] )

Return an array reporting the number of various entities in the system.

Parameters

array $options additional options

Returns: array

Since: 4.3

See also: elgg_get_entities()

Definition at line 661 of file entities.php.

elgg_get_site_entity ( )

Get the current site entity.

Returns

Since: 1.8.0

Definition at line 101 of file entities.php.

elgg_list_entities	(	array	$options = `[]`,
		callable	$getter = `null`,
		callable	$viewer = `null`
	)

Returns a string of rendered entities.

Displays list of entities with formatting specified by the entity view.

Pagination is handled automatically.

Note: Internal: This also provides the views for elgg_view_annotation().; Internal: If the initial COUNT query returns 0, the $getter will not be called again.

Parameters

array	$options	Any options from $getter options plus: item_view => STR Optional. Alternative view used to render list items full_view => BOOL Display full view of entities (default: false) list_type => STR 'list', 'gallery', or 'table' columns => ARR instances of Elgg if list_type is "table" pagination => BOOL Display pagination links no_results => STR\|true for default notfound text\|Closure Message to display when there are no entities
callable	$getter	The entity getter function to use to fetch the entities.
callable	$viewer	The function to use to view the entity list.

Returns: string

Since: 1.7

See also: elgg_get_entities(); elgg_view_entity_list()

Definition at line 551 of file entities.php.

elgg_search ( array $options = [] )

Returns search results as an array of entities, as a batch, or a count, depending on parameters given.

Parameters

array $options Search parameters Accepts all options supported by elgg_get_entities()

string $query Search query string $type Entity type. Required if no search type is set string $search_type Custom search type. Required if no type is set array $fields An array of fields to search in, supported keys are [ 'attributes' => ['some attribute', 'some other attribute'], 'metadata' => ['some metadata name', 'some other metadata name'], 'annotations' => ['some annotation name', 'some other annotation name'], ] bool $partial_match Allow partial matches, e.g. find 'elgg' when search for 'el' bool $tokenize Break down search query into tokens, e.g. find 'elgg has been released' when searching for 'elgg released'

Returns: ElggBatch|ElggEntity[]|int|false

See also: elgg_get_entities()

Definition at line 644 of file entities.php.

elgg_set_entity_class	(	string	$type,
		string	$subtype,
		string	$class = `''`
	)

Sets class constructor name for entities with given type and subtype.

By default entities are loaded as one of the 4 parent objects:

site: ElggSite
user: ElggUser
object: ElggObject
group: ElggGroup

Entity classes for subtypes should extend the base class for entity type, e.g. ElggBlog must extend ElggObject

Parameters

string	$type	Entity type
string	$subtype	Entity subtype
string	$class	Class name for the object Can be empty to reset previously declared class name

Returns: void

Definition at line 44 of file entities.php.

get_entity ( int $guid )

Loads and returns an entity object from a guid.

Parameters

int $guid The GUID of the entity

Returns: null| The correct Elgg or custom object based upon entity type and subtype

Definition at line 70 of file entities.php.

Functions

Function Documentation

TYPE SUBTYPE CONSTRAINTS

GUID CONSTRAINTS

TIME CONSTRAINTS

ACCESS CONSTRAINTS

LIMIT AND OFFSET

METADATA CONSTRAINTS

ANNOTATION CONSTRAINTS

RELATIONSHIP CONSTRAINTS

SORTING

COUNT/CALCULATION

SQL SELECT

SQL JOIN

SQL GROUPS

SQL WHERE

RESULT OPTIONS