Elgg  Version 3.0
Functions | Variables
entities.php File Reference

Go to the source code of this file.

Functions

 elgg_get_entity_class ($type, $subtype)
 Procedural code for creating, loading, and modifying objects. More...
 
 elgg_set_entity_class ($type, $subtype, $class="")
 Sets class constructor name for entities with given type and subtype. More...
 
 get_entity_as_row ($guid)
 Returns a database row from the entities table. More...
 
 entity_row_to_elggstar ($row)
 Create an Elgg* object from a given entity row. More...
 
 get_entity ($guid)
 Loads and returns an entity object from a guid. More...
 
 elgg_entity_exists ($guid)
 Does an entity exist? More...
 
 elgg_enable_entity ($guid, $recursive=true)
 Enable an entity. 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_list_entities (array $options=[], $getter= 'elgg_get_entities', $viewer= 'elgg_view_entity_list')
 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_register_entity_type ($type, $subtype=null)
 Registers an entity type and subtype as a public-facing entity that should be shown in search and by elgg_list_registered_entities(). More...
 
 elgg_unregister_entity_type ($type, $subtype=null)
 Unregisters an entity type and subtype as a public-facing type. More...
 
 get_registered_entity_types ($type=null)
 Returns registered entity types and subtypes. More...
 
 is_registered_entity_type ($type, $subtype=null)
 Returns if the entity type and subtype have been registered with elgg_register_entity_type(). More...
 
 elgg_instanceof ($entity, $type=null, $subtype=null)
 Checks if $entity is an and optionally for type and subtype. More...
 
 _elgg_check_unsupported_site_guid (array $options=[])
 Checks options for the existing of site_guid or site_guids contents and reports a warning if found. More...
 
 _elgg_entities_test ($hook, $type, $value)
 Runs unit tests for the entity objects. More...
 
 _elgg_entities_init ()
 Entities init function; establishes the default entity page handler. More...
 

Variables

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

Function Documentation

_elgg_check_unsupported_site_guid ( array  $options = [])

Checks options for the existing of site_guid or site_guids contents and reports a warning if found.

Parameters
array$optionsarray of options to check
Returns
void

Definition at line 820 of file entities.php.

_elgg_entities_init ( )

Entities init function; establishes the default entity page handler.

Returns
void init system

Definition at line 870 of file entities.php.

_elgg_entities_test (   $hook,
  $type,
  $value 
)

Runs unit tests for the entity objects.

Parameters
string$hook'unit_test'
string$type'system'
array$valueArray of tests
Returns
array

Definition at line 852 of file entities.php.

elgg_enable_entity (   $guid,
  $recursive = true 
)

Enable an entity.

Parameters
int$guidGUID of entity to enable
bool$recursiveRecursively enable all entities disabled with the entity?
Returns
bool
Since
1.9.0

Definition at line 120 of file entities.php.

elgg_entity_exists (   $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 107 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_set_ignore_access()

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, ], ];


PRIVATE SETTINGS CONSTRAINTS

Filter entities by their private settings

The following options will be merged and applied as a private_setting pair to $options['private_setting_name_value_pairs'] int[] $private_setting_ids string[] $private_setting_names mixed $private_setting_values bool $private_setting_case_sensitive

Private name value pairs will be joined by the boolean specified in $private_setting_name_value_pairs_operator array $private_setting_name_value_pairs string $private_setting_name_value_pairs_operator

Setting names in all pairs can be namespaced using the prefix string $private_setting_name_prefix

$options['private_setting_name_value_pairs'] = [ [ 'name' => 'handler', 'value' => ['admin', 'dashboard'], 'operand' => 'IN', ], ];


SORTING

You can specify sorting options using ONE of the following options

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

Order by value of a specific annotation array $order_by_annotation

Order by value of a speicifc metadata/attribute array $order_by_metadata

Order by arbitrary clauses array $order_by

$options['order_by_metadata'] = [ 'name' => 'priority', 'direction' => 'DESC', 'as' => 'integer', ]; $options['order_by_annotation'] = [ 'name' => 'priority', 'direction' => 'DESC', 'as' => 'integer', ];

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

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

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


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: entity_row_to_elggstar 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 $preload_private_settings If set to true, this function will preload all the private settings of the returned entities resulting in better performance when displaying entities where private settings are often used, such as widgets Default: false bool $batch If set to true, an Elgg 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 Elgg. false on errors.
Since
1.7.0

Definition at line 545 of file entities.php.

elgg_get_entity_class (   $type,
  $subtype 
)

Procedural code for creating, loading, and modifying objects.

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 16 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|false Either an array months as YYYYMM, or false on failure
Since
3.0

Definition at line 639 of file entities.php.

elgg_get_site_entity ( )

Get the current site entity.

Returns
Since
1.8.0

Definition at line 130 of file entities.php.

elgg_instanceof (   $entity,
  $type = null,
  $subtype = null 
)

Checks if $entity is an and optionally for type and subtype.

Use this function in actions and views to check that you are dealing with the correct type of entity.

Parameters
mixed$entityEntity
string$typeEntity type
string$subtypeEntity subtype
Returns
bool
Since
1.8.0

Definition at line 798 of file entities.php.

elgg_list_entities ( array  $options = [],
  $getter = 'elgg_get_entities',
  $viewer = 'elgg_view_entity_list' 
)

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" list_type_toggle => BOOL Display gallery / list switch 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 577 of file entities.php.

elgg_register_entity_type (   $type,
  $subtype = null 
)

Registers an entity type and subtype as a public-facing entity that should be shown in search and by elgg_list_registered_entities().

Warning
Entities that aren't registered here will not show up in search.

Add a language string item:type:subtype and collection:type:subtype to make sure the items are display properly.

Parameters
string$typeThe type of entity (object, site, user, group)
string$subtypeThe subtype to register (may be blank)
Returns
bool Depending on success
See also
get_registered_entity_types()

Definition at line 657 of file entities.php.

elgg_set_entity_class (   $type,
  $subtype,
  $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 39 of file entities.php.

elgg_unregister_entity_type (   $type,
  $subtype = null 
)

Unregisters an entity type and subtype as a public-facing type.

Warning
With a blank subtype, it unregisters that entity type including all subtypes. This must be called after all subtypes have been registered.
Parameters
string$typeThe type of entity (object, site, user, group)
string$subtypeThe subtype to register (may be blank)
Returns
bool Depending on success
See also
elgg_register_entity_type()

Definition at line 698 of file entities.php.

entity_row_to_elggstar (   $row)

Create an Elgg* object from a given entity row.

Handles loading all tables into the correct class.

Parameters
\stdClass$rowThe row of the entry in the entities table.
Returns
|false
See also
get_entity_as_row()
get_entity()

Definition at line 76 of file entities.php.

get_entity (   $guid)

Loads and returns an entity object from a guid.

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

Definition at line 87 of file entities.php.

get_entity_as_row (   $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. see _elgg_get_access_where_sql().
Parameters
int$guidThe GUID of the object to extract
Returns
|false
See also
entity_row_to_elggstar()

Definition at line 58 of file entities.php.

get_registered_entity_types (   $type = null)

Returns registered entity types and subtypes.

Parameters
string$typeThe type of entity (object, site, user, group) or blank for all
Returns
array|false Depending on whether entities have been registered
See also
elgg_register_entity_type()

Definition at line 736 of file entities.php.

is_registered_entity_type (   $type,
  $subtype = null 
)

Returns if the entity type and subtype have been registered with elgg_register_entity_type().

Parameters
string$typeThe type of entity (object, site, user, group)
string$subtypeThe subtype (may be blank)
Returns
bool Depending on whether or not the type has been registered

Definition at line 765 of file entities.php.

Variable Documentation

See also
::loadCore Do not do work here. Just register for events.

Definition at line 877 of file entities.php.