Elgg  Version 2.2
 All Classes Namespaces Files Functions Variables Pages
Functions | Variables
entities.php File Reference

Go to the source code of this file.

Functions

 get_subtype_id ($type, $subtype)
 Return the id for a given subtype. More...
 
 get_subtype_from_id ($subtype_id)
 Gets the denormalized string for a given subtype ID. More...
 
 get_subtype_class ($type, $subtype)
 Return the class name for a registered type and subtype. More...
 
 get_subtype_class_from_id ($subtype_id)
 Returns the class name for a subtype id. More...
 
 add_subtype ($type, $subtype, $class="")
 Register with a certain type and subtype to be loaded as a specific class. More...
 
 remove_subtype ($type, $subtype)
 Removes a registered type, subtype, and classname. More...
 
 update_subtype ($type, $subtype, $class= '')
 Update a registered type, subtype, and class name. More...
 
 can_write_to_container ($user_guid=0, $container_guid=0, $type= 'all', $subtype= 'all')
 Determine if a given user can write to an entity container. 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_entities (array $options=array())
 Returns an array of entities with optional filtering. More...
 
 _elgg_get_guid_based_where_sql ($column, $guids)
 Returns SQL where clause for owner and containers. More...
 
 _elgg_get_entity_time_where_sql ($table, $time_created_upper=null, $time_created_lower=null, $time_updated_upper=null, $time_updated_lower=null)
 Returns SQL where clause for entity time limits. More...
 
 elgg_list_entities (array $options=array(), $getter= 'elgg_get_entities', $viewer= 'elgg_view_entity_list')
 Returns a string of rendered entities. More...
 
 elgg_get_entities_from_attributes (array $options=array())
 Gets entities based upon attributes in secondary tables. More...
 
 _elgg_get_entity_attribute_where_sql (array $options=array())
 Get the join and where clauses for working with entity attributes. More...
 
 get_entity_dates ($type= '', $subtype= '', $container_guid=0, $site_guid=0, $order_by= 'time_created')
 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_list_registered_entities (array $options=array())
 Returns a viewable list of entities based on the registered types. More...
 
 elgg_instanceof ($entity, $type=null, $subtype=null, $class=null)
 Checks if $entity is an and optionally for type and subtype. More...
 
 update_entity_last_action ($guid, $posted=null)
 Update the last_action column in the entities table for $guid. 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_entities_init ( )

Entities init function; establishes the default entity page handler.

Returns
void init system private

Definition at line 782 of file entities.php.

_elgg_entities_test (   $hook,
  $type,
  $value 
)

Runs unit tests for the entity objects.

Parameters
string$hookunit_test
string$typesystem
array$valueArray of tests
Returns
array private

Definition at line 761 of file entities.php.

_elgg_get_entity_attribute_where_sql ( array  $options = array())

Get the join and where clauses for working with entity attributes.

Returns
false|array False on fail, array('joins', 'wheres')
Since
1.9.0 private
Exceptions
InvalidArgumentException

Definition at line 465 of file entities.php.

_elgg_get_entity_time_where_sql (   $table,
  $time_created_upper = null,
  $time_created_lower = null,
  $time_updated_upper = null,
  $time_updated_lower = null 
)

Returns SQL where clause for entity time limits.

Parameters
string$tableEntity table prefix as defined in SELECT...FROM entities $table
null | int$time_created_upperTime created upper limit
null | int$time_created_lowerTime created lower limit
null | int$time_updated_upperTime updated upper limit
null | int$time_updated_lowerTime updated lower limit
Returns
false|string false on fail, string on success.
Since
1.7.0 private

Definition at line 349 of file entities.php.

_elgg_get_guid_based_where_sql (   $column,
  $guids 
)

Returns SQL where clause for owner and containers.

Parameters
string$columnColumn name the guids should be checked against. Usually best to provide in table.column format.
null | array$guidsArray of GUIDs.
Returns
false|string
Since
1.8.0 private

Definition at line 331 of file entities.php.

add_subtype (   $type,
  $subtype,
  $class = "" 
)

Register with a certain type and subtype to be loaded as a specific class.

By default entities are loaded as one of the 4 parent objects: site, user, object, or group. If you subclass any of these you can register the classname with add_subtype() so it will be loaded as that class automatically when retrieved from the database with get_entity().

Warning
This function cannot be used to change the class for a type-subtype pair. Use update_subtype() for that.
Parameters
string$typeThe type you're subtyping (site, user, object, or group)
string$subtypeThe subtype
string$classOptional class name for the object
Returns
int
See Also
update_subtype()
remove_subtype()
get_entity()

Definition at line 95 of file entities.php.

can_write_to_container (   $user_guid = 0,
  $container_guid = 0,
  $type = 'all',
  $subtype = 'all' 
)

Determine if a given user can write to an entity container.

An entity can be a container for any other entity by setting the container_guid. container_guid can differ from owner_guid.

A plugin hook container_permissions_check:$entity_type is emitted to allow granular access controls in plugins.

Parameters
int$user_guidThe user guid, or 0 for logged in user.
int$container_guidThe container, or 0 for the current page owner.
string$typeThe type of entity we want to create (default: 'all')
string$subtypeThe subtype of the entity we want to create (default: 'all')
Returns
bool

Definition at line 147 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 234 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 221 of file entities.php.

elgg_get_entities ( array  $options = array())

Returns an array of entities with optional filtering.

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.

To output formatted strings of entities, use elgg_list_entities() and its cousins.

Plural arguments can be written as singular if only specifying a single element. ('type' => 'object' vs 'types' => array('object')).

Parameters
array$optionsArray 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

site_guids => null (current_site)|ARR Array of site_guid

order_by => null (time_created desc)|STR SQL order by clause

reverse_order_by => BOOL Reverse the default order by clause

limit => null (from settings)|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 when displaying entities owned by several users

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.

Returns
mixed If count, int. If not count, array. false on errors.
Since
1.7.0
See Also
elgg_get_entities_from_metadata()
elgg_get_entities_from_relationship()
elgg_get_entities_from_access_id()
elgg_get_entities_from_annotations()
elgg_list_entities()

Definition at line 316 of file entities.php.

elgg_get_entities_from_attributes ( array  $options = array())

Gets entities based upon attributes in secondary tables.

Also accepts all options available to elgg_get_entities(), elgg_get_entities_from_metadata(), and elgg_get_entities_from_relationship().

Warning
requires that the entity type be specified and there can only be one type.
See Also
elgg_get_entities
elgg_get_entities_from_metadata
elgg_get_entities_from_relationship
Parameters
array$optionsArray in format:
attribute_name_value_pairs => ARR (
                              'name' => 'name',
                              'value' => 'value',
                              'operand' => '=', (optional)
                              'case_sensitive' => false (optional)
                             )
                             If multiple values are sent via
                          an array ('value' => array('value1', 'value2')
                          the pair's operand will be forced to "IN".

attribute_name_value_pairs_operator => null|STR The operator to use for combining
                                   (name = value) OPERATOR (name = value); default is AND
Returns
[]|mixed If count, int. If not count, array. false on errors.
Since
1.9.0
Exceptions
InvalidArgumentException

Definition at line 453 of file entities.php.

elgg_instanceof (   $entity,
  $type = null,
  $subtype = null,
  $class = 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
string$classClass name
Returns
bool
Since
1.8.0

Definition at line 716 of file entities.php.

elgg_list_entities ( array  $options = array(),
  $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' or 'gallery' list_type_toggle => BOOL Display gallery / list switch pagination => BOOL Display pagination links no_results => STR|Closure Message to display when there are no entities
callback$getterThe entity getter function to use to fetch the entities.
callback$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 382 of file entities.php.

elgg_list_registered_entities ( array  $options = array())

Returns a viewable list of entities based on the registered types.

See Also
elgg_view_entity_list
Parameters
array$optionsAny elgg_get_entity() options plus:
full_view => BOOL Display full view entities

list_type_toggle => BOOL Display gallery / list switch

allowed_types => true|ARRAY True to show all types or an array of valid types.

pagination => BOOL Display pagination links
Returns
string A viewable list of entities
Since
1.7.0

Definition at line 646 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 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 506 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 541 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()
add_subtype()
get_entity() private
Exceptions
ClassException|InstallationException

Definition at line 193 of file entities.php.

get_entity (   $guid)

Loads and returns an entity object from a guid.

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

Definition at line 204 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() private

Definition at line 174 of file entities.php.

get_entity_dates (   $type = '',
  $subtype = '',
  $container_guid = 0,
  $site_guid = 0,
  $order_by = 'time_created' 
)

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
string$typeThe type of entity
string$subtypeThe subtype of entity
int$container_guidThe container GUID that the entities belong to
int$site_guidThe site GUID
string$order_byOrder_by SQL order by clause
Returns
array|false Either an array months as YYYYMM, or false on failure

Definition at line 486 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 579 of file entities.php.

get_subtype_class (   $type,
  $subtype 
)

Return the class name for a registered type and subtype.

Entities can be registered to always be loaded as a certain class with add_subtype() or update_subtype(). This function returns the class name if found and null if not.

Parameters
string$typeThe type
string$subtypeThe subtype
Returns
string|null a class name or null
See Also
get_subtype_from_id()
get_subtype_class_from_id()

Definition at line 57 of file entities.php.

get_subtype_class_from_id (   $subtype_id)

Returns the class name for a subtype id.

Parameters
int$subtype_idThe subtype id
Returns
string|null
See Also
get_subtype_class()
get_subtype_from_id() private

Definition at line 71 of file entities.php.

get_subtype_from_id (   $subtype_id)

Gets the denormalized string for a given subtype ID.

Parameters
int$subtype_idSubtype ID from database
Returns
string|false Subtype name, false if subtype not found
See Also
get_subtype_id() private

Definition at line 39 of file entities.php.

get_subtype_id (   $type,
  $subtype 
)

Return the id for a given subtype.

objects have a type and a subtype. Subtypes are defined upon creation and cannot be changed.

Plugin authors generally don't need to use this function unless writing their own SQL queries. Use ElggEntity::getSubtype()toreturnthestringsubtype.

Definition at line 27 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 607 of file entities.php.

remove_subtype (   $type,
  $subtype 
)

Removes a registered type, subtype, and classname.

Warning
You do not want to use this function. If you want to unregister a class for a subtype, use update_subtype(). Using this function will permanently orphan all the objects created with the specified subtype.
Parameters
string$typeType
string$subtypeSubtype
Returns
bool
See Also
add_subtype()
update_subtype()

Definition at line 113 of file entities.php.

update_entity_last_action (   $guid,
  $posted = null 
)

Update the last_action column in the entities table for $guid.

Warning
This is different to time_updated. Time_updated is automatically set, while last_action is only set when explicitly called.
Parameters
int$guidEntity annotation|relationship action carried out on
int$postedTimestamp of last action
Returns
bool private

Definition at line 747 of file entities.php.

update_subtype (   $type,
  $subtype,
  $class = '' 
)

Update a registered type, subtype, and class name.

Parameters
string$typeType
string$subtypeSubtype
string$classClass name to use when loading this entity
Returns
bool

Definition at line 126 of file entities.php.

Variable Documentation

Definition at line 786 of file entities.php.