Elgg  Version master
Functions
entities.php File Reference

Go to the source code of this file.

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 (int $owner_guid=0)
 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$optionsthe same options as elgg_get_entities() but forces 'count' to true
Returns
int

Definition at line 516 of file entities.php.

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

Disables the capability for a specified type/subtype.

Parameters
string$typetype of the entity
string$subtypesubtype of the entity
string$capabilityname of the capability to set
Returns
void
Since
4.1

Definition at line 726 of file entities.php.

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

Enables the capability for a specified type/subtype.

Parameters
string$typetype of the entity
string$subtypesubtype of the entity
string$capabilityname of the capability to set
Returns
void
Since
4.1

Definition at line 712 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$guidThe GUID of the entity
Returns
bool
Since
1.8.0

Definition at line 89 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$typetype of the entity
string$subtypesubtype of the entity
string$capabilityname of the capability to check
bool$defaultdefault value to return if it is not explicitly set
Returns
bool
Since
4.1

Definition at line 698 of file entities.php.

elgg_entity_types_with_capability ( string  $capability)

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

Parameters
string$capabilityname of the capability to set
Returns
array
Since
4.1

Definition at line 738 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

DateTime|string|int $created_after DateTime|string|int $created_before DateTime|string|int $updated_after DateTime|string|int $updated_before DateTime|string|int $last_action_after DateTime|string|int $last_action_before

$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$optionsOptions
Returns
[]|int|mixed If count, int. Otherwise an array or an
Since
1.7.0

Definition at line 505 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$guidThe GUID of the object to extract
Returns
|null

Definition at line 57 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$typeThe type
string$subtypeThe subtype
Returns
string

Definition at line 19 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$optionsall entity options supported by {
See also
elgg_get_entities()}
Returns
array An array months as YYYYMM
Since
3.0

Definition at line 614 of file entities.php.

elgg_get_entity_statistics ( int  $owner_guid = 0)

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

Parameters
int$owner_guidOptional owner of the statistics
Returns
array
Since
4.3

Definition at line 658 of file entities.php.

elgg_get_site_entity ( )

Get the current site entity.

Returns
Since
1.8.0

Definition at line 99 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$optionsAny 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$getterThe entity getter function to use to fetch the entities.
callable$viewerThe 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 549 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$optionsSearch 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 642 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:

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

Parameters
string$typeEntity type
string$subtypeEntity subtype
string$classClass name for the object Can be empty to reset previously declared class name
Returns
void

Definition at line 42 of file entities.php.

get_entity ( int  $guid)

Loads and returns an entity object from a guid.

Parameters
int$guidThe GUID of the entity
Returns
null| The correct Elgg or custom object based upon entity type and subtype

Definition at line 68 of file entities.php.