aboutsummaryrefslogtreecommitdiff
path: root/engine/lib/entities.php
diff options
context:
space:
mode:
Diffstat (limited to 'engine/lib/entities.php')
-rw-r--r--engine/lib/entities.php2526
1 files changed, 2526 insertions, 0 deletions
diff --git a/engine/lib/entities.php b/engine/lib/entities.php
new file mode 100644
index 000000000..ce736ce05
--- /dev/null
+++ b/engine/lib/entities.php
@@ -0,0 +1,2526 @@
+<?php
+/**
+ * Procedural code for creating, loading, and modifying ElggEntity objects.
+ *
+ * @package Elgg.Core
+ * @subpackage DataModel.Entities
+ * @link http://docs.elgg.org/DataModel/Entities
+ */
+
+/**
+ * Cache entities in memory once loaded.
+ *
+ * @global array $ENTITY_CACHE
+ * @access private
+ */
+global $ENTITY_CACHE;
+$ENTITY_CACHE = array();
+
+/**
+ * Cache subtypes and related class names.
+ *
+ * @global array|null $SUBTYPE_CACHE array once populated from DB, initially null
+ * @access private
+ */
+global $SUBTYPE_CACHE;
+$SUBTYPE_CACHE = null;
+
+/**
+ * Invalidate this class's entry in the cache.
+ *
+ * @param int $guid The entity guid
+ *
+ * @return null
+ * @access private
+ */
+function invalidate_cache_for_entity($guid) {
+ global $ENTITY_CACHE;
+
+ $guid = (int)$guid;
+
+ unset($ENTITY_CACHE[$guid]);
+
+ elgg_get_metadata_cache()->clear($guid);
+}
+
+/**
+ * Cache an entity.
+ *
+ * Stores an entity in $ENTITY_CACHE;
+ *
+ * @param ElggEntity $entity Entity to cache
+ *
+ * @return null
+ * @see retrieve_cached_entity()
+ * @see invalidate_cache_for_entity()
+ * @access private
+ * TODO(evan): Use an ElggCache object
+ */
+function cache_entity(ElggEntity $entity) {
+ global $ENTITY_CACHE;
+
+ // Don't cache non-plugin entities while access control is off, otherwise they could be
+ // exposed to users who shouldn't see them when control is re-enabled.
+ if (!($entity instanceof ElggPlugin) && elgg_get_ignore_access()) {
+ return;
+ }
+
+ // Don't store too many or we'll have memory problems
+ // TODO(evan): Pick a less arbitrary limit
+ if (count($ENTITY_CACHE) > 256) {
+ $random_guid = array_rand($ENTITY_CACHE);
+
+ unset($ENTITY_CACHE[$random_guid]);
+
+ // Purge separate metadata cache. Original idea was to do in entity destructor, but that would
+ // have caused a bunch of unnecessary purges at every shutdown. Doing it this way we have no way
+ // to know that the expunged entity will be GCed (might be another reference living), but that's
+ // OK; the metadata will reload if necessary.
+ elgg_get_metadata_cache()->clear($random_guid);
+ }
+
+ $ENTITY_CACHE[$entity->guid] = $entity;
+}
+
+/**
+ * Retrieve a entity from the cache.
+ *
+ * @param int $guid The guid
+ *
+ * @return ElggEntity|bool false if entity not cached, or not fully loaded
+ * @see cache_entity()
+ * @see invalidate_cache_for_entity()
+ * @access private
+ */
+function retrieve_cached_entity($guid) {
+ global $ENTITY_CACHE;
+
+ if (isset($ENTITY_CACHE[$guid])) {
+ if ($ENTITY_CACHE[$guid]->isFullyLoaded()) {
+ return $ENTITY_CACHE[$guid];
+ }
+ }
+
+ return false;
+}
+
+/**
+ * As retrieve_cached_entity, but returns the result as a stdClass
+ * (compatible with load functions that expect a database row.)
+ *
+ * @param int $guid The guid
+ *
+ * @return mixed
+ * @todo unused
+ * @access private
+ */
+function retrieve_cached_entity_row($guid) {
+ $obj = retrieve_cached_entity($guid);
+ if ($obj) {
+ $tmp = new stdClass;
+
+ foreach ($obj as $k => $v) {
+ $tmp->$k = $v;
+ }
+
+ return $tmp;
+ }
+
+ return false;
+}
+
+/**
+ * Return the id for a given subtype.
+ *
+ * ElggEntity 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 {@link ElggEntity::getSubtype()}
+ * to return the string subtype.
+ *
+ * @warning {@link ElggEntity::subtype} returns the ID. You probably want
+ * {@link ElggEntity::getSubtype()} instead!
+ *
+ * @internal Subtypes are stored in the entity_subtypes table. There is a foreign
+ * key in the entities table.
+ *
+ * @param string $type Type
+ * @param string $subtype Subtype
+ *
+ * @return int Subtype ID
+ * @link http://docs.elgg.org/DataModel/Entities/Subtypes
+ * @see get_subtype_from_id()
+ * @access private
+ */
+function get_subtype_id($type, $subtype) {
+ global $SUBTYPE_CACHE;
+
+ if (!$subtype) {
+ return false;
+ }
+
+ if ($SUBTYPE_CACHE === null) {
+ _elgg_populate_subtype_cache();
+ }
+
+ // use the cache before hitting database
+ $result = _elgg_retrieve_cached_subtype($type, $subtype);
+ if ($result !== null) {
+ return $result->id;
+ }
+
+ return false;
+}
+
+/**
+ * Return string name for a given subtype ID.
+ *
+ * @param int $subtype_id Subtype ID
+ *
+ * @return string|false Subtype name, false if subtype not found
+ * @link http://docs.elgg.org/DataModel/Entities/Subtypes
+ * @see get_subtype_from_id()
+ * @access private
+ */
+function get_subtype_from_id($subtype_id) {
+ global $SUBTYPE_CACHE;
+
+ if (!$subtype_id) {
+ return false;
+ }
+
+ if ($SUBTYPE_CACHE === null) {
+ _elgg_populate_subtype_cache();
+ }
+
+ if (isset($SUBTYPE_CACHE[$subtype_id])) {
+ return $SUBTYPE_CACHE[$subtype_id]->subtype;
+ }
+
+ return false;
+}
+
+/**
+ * Retrieve subtype from the cache.
+ *
+ * @param string $type
+ * @param string $subtype
+ * @return stdClass|null
+ *
+ * @access private
+ */
+function _elgg_retrieve_cached_subtype($type, $subtype) {
+ global $SUBTYPE_CACHE;
+
+ if ($SUBTYPE_CACHE === null) {
+ _elgg_populate_subtype_cache();
+ }
+
+ foreach ($SUBTYPE_CACHE as $obj) {
+ if ($obj->type === $type && $obj->subtype === $subtype) {
+ return $obj;
+ }
+ }
+ return null;
+}
+
+/**
+ * Fetch all suptypes from DB to local cache.
+ *
+ * @access private
+ */
+function _elgg_populate_subtype_cache() {
+ global $CONFIG, $SUBTYPE_CACHE;
+
+ $results = get_data("SELECT * FROM {$CONFIG->dbprefix}entity_subtypes");
+
+ $SUBTYPE_CACHE = array();
+ foreach ($results as $row) {
+ $SUBTYPE_CACHE[$row->id] = $row;
+ }
+}
+
+/**
+ * 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.
+ *
+ * @param string $type The type
+ * @param string $subtype The subtype
+ *
+ * @return string|null a class name or null
+ * @see get_subtype_from_id()
+ * @see get_subtype_class_from_id()
+ * @access private
+ */
+function get_subtype_class($type, $subtype) {
+ global $SUBTYPE_CACHE;
+
+ if ($SUBTYPE_CACHE === null) {
+ _elgg_populate_subtype_cache();
+ }
+
+ // use the cache before going to the database
+ $obj = _elgg_retrieve_cached_subtype($type, $subtype);
+ if ($obj) {
+ return $obj->class;
+ }
+
+ return null;
+}
+
+/**
+ * Returns the class name for a subtype id.
+ *
+ * @param int $subtype_id The subtype id
+ *
+ * @return string|null
+ * @see get_subtype_class()
+ * @see get_subtype_from_id()
+ * @access private
+ */
+function get_subtype_class_from_id($subtype_id) {
+ global $SUBTYPE_CACHE;
+
+ if (!$subtype_id) {
+ return null;
+ }
+
+ if ($SUBTYPE_CACHE === null) {
+ _elgg_populate_subtype_cache();
+ }
+
+ if (isset($SUBTYPE_CACHE[$subtype_id])) {
+ return $SUBTYPE_CACHE[$subtype_id]->class;
+ }
+
+ return null;
+}
+
+/**
+ * Register ElggEntities 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
+ * {@link get_entity()}.
+ *
+ * @warning This function cannot be used to change the class for a type-subtype pair.
+ * Use update_subtype() for that.
+ *
+ * @param string $type The type you're subtyping (site, user, object, or group)
+ * @param string $subtype The subtype
+ * @param string $class Optional class name for the object
+ *
+ * @return int
+ * @link http://docs.elgg.org/Tutorials/Subclasses
+ * @link http://docs.elgg.org/DataModel/Entities
+ * @see update_subtype()
+ * @see remove_subtype()
+ * @see get_entity()
+ */
+function add_subtype($type, $subtype, $class = "") {
+ global $CONFIG, $SUBTYPE_CACHE;
+
+ if (!$subtype) {
+ return 0;
+ }
+
+ $id = get_subtype_id($type, $subtype);
+
+ if (!$id) {
+ // In cache we store non-SQL-escaped strings because that's what's returned by query
+ $cache_obj = (object) array(
+ 'type' => $type,
+ 'subtype' => $subtype,
+ 'class' => $class,
+ );
+
+ $type = sanitise_string($type);
+ $subtype = sanitise_string($subtype);
+ $class = sanitise_string($class);
+
+ $id = insert_data("INSERT INTO {$CONFIG->dbprefix}entity_subtypes"
+ . " (type, subtype, class) VALUES ('$type', '$subtype', '$class')");
+
+ // add entry to cache
+ $cache_obj->id = $id;
+ $SUBTYPE_CACHE[$id] = $cache_obj;
+ }
+
+ return $id;
+}
+
+/**
+ * Removes a registered ElggEntity 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.
+ *
+ * @param string $type Type
+ * @param string $subtype Subtype
+ *
+ * @return bool
+ * @see add_subtype()
+ * @see update_subtype()
+ */
+function remove_subtype($type, $subtype) {
+ global $CONFIG;
+
+ $type = sanitise_string($type);
+ $subtype = sanitise_string($subtype);
+
+ return delete_data("DELETE FROM {$CONFIG->dbprefix}entity_subtypes"
+ . " WHERE type = '$type' AND subtype = '$subtype'");
+}
+
+/**
+ * Update a registered ElggEntity type, subtype, and class name
+ *
+ * @param string $type Type
+ * @param string $subtype Subtype
+ * @param string $class Class name to use when loading this entity
+ *
+ * @return bool
+ */
+function update_subtype($type, $subtype, $class = '') {
+ global $CONFIG, $SUBTYPE_CACHE;
+
+ $id = get_subtype_id($type, $subtype);
+ if (!$id) {
+ return false;
+ }
+
+ if ($SUBTYPE_CACHE === null) {
+ _elgg_populate_subtype_cache();
+ }
+
+ $unescaped_class = $class;
+
+ $type = sanitise_string($type);
+ $subtype = sanitise_string($subtype);
+ $class = sanitise_string($class);
+
+ $success = update_data("UPDATE {$CONFIG->dbprefix}entity_subtypes
+ SET type = '$type', subtype = '$subtype', class = '$class'
+ WHERE id = $id
+ ");
+
+ if ($success && isset($SUBTYPE_CACHE[$id])) {
+ $SUBTYPE_CACHE[$id]->class = $unescaped_class;
+ }
+
+ return $success;
+}
+
+/**
+ * Update an entity in the database.
+ *
+ * There are 4 basic entity types: site, user, object, and group.
+ * All entities are split between two tables: the entities table and their type table.
+ *
+ * @warning Plugin authors should never call this directly. Use ->save() instead.
+ *
+ * @param int $guid The guid of the entity to update
+ * @param int $owner_guid The new owner guid
+ * @param int $access_id The new access id
+ * @param int $container_guid The new container guid
+ * @param int $time_created The time creation timestamp
+ *
+ * @return bool
+ * @link http://docs.elgg.org/DataModel/Entities
+ * @access private
+ */
+function update_entity($guid, $owner_guid, $access_id, $container_guid = null, $time_created = null) {
+ global $CONFIG, $ENTITY_CACHE;
+
+ $guid = (int)$guid;
+ $owner_guid = (int)$owner_guid;
+ $access_id = (int)$access_id;
+ $container_guid = (int) $container_guid;
+ if (is_null($container_guid)) {
+ $container_guid = $owner_guid;
+ }
+ $time = time();
+
+ $entity = get_entity($guid);
+
+ if ($time_created == null) {
+ $time_created = $entity->time_created;
+ } else {
+ $time_created = (int) $time_created;
+ }
+
+ if ($entity && $entity->canEdit()) {
+ if (elgg_trigger_event('update', $entity->type, $entity)) {
+ $ret = update_data("UPDATE {$CONFIG->dbprefix}entities
+ set owner_guid='$owner_guid', access_id='$access_id',
+ container_guid='$container_guid', time_created='$time_created',
+ time_updated='$time' WHERE guid=$guid");
+
+ if ($entity instanceof ElggObject) {
+ update_river_access_by_object($guid, $access_id);
+ }
+
+ // If memcache is available then delete this entry from the cache
+ static $newentity_cache;
+ if ((!$newentity_cache) && (is_memcache_available())) {
+ $newentity_cache = new ElggMemcache('new_entity_cache');
+ }
+ if ($newentity_cache) {
+ $newentity_cache->delete($guid);
+ }
+
+ // Handle cases where there was no error BUT no rows were updated!
+ if ($ret === false) {
+ return false;
+ }
+
+ return true;
+ }
+ }
+}
+
+/**
+ * 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.
+ *
+ * @param int $user_guid The user guid, or 0 for logged in user
+ * @param int $container_guid The container, or 0 for the current page owner.
+ * @param string $type The type of entity we're looking to write
+ * @param string $subtype The subtype of the entity we're looking to write
+ *
+ * @return bool
+ * @link http://docs.elgg.org/DataModel/Containers
+ */
+function can_write_to_container($user_guid = 0, $container_guid = 0, $type = 'all', $subtype = 'all') {
+ $user_guid = (int)$user_guid;
+ $user = get_entity($user_guid);
+ if (!$user) {
+ $user = elgg_get_logged_in_user_entity();
+ }
+
+ $container_guid = (int)$container_guid;
+ if (!$container_guid) {
+ $container_guid = elgg_get_page_owner_guid();
+ }
+
+ $return = false;
+
+ if (!$container_guid) {
+ $return = true;
+ }
+
+ $container = get_entity($container_guid);
+
+ if ($container) {
+ // If the user can edit the container, they can also write to it
+ if ($container->canEdit($user_guid)) {
+ $return = true;
+ }
+
+ // If still not approved, see if the user is a member of the group
+ // @todo this should be moved to the groups plugin/library
+ if (!$return && $user && $container instanceof ElggGroup) {
+ if ($container->isMember($user)) {
+ $return = true;
+ }
+ }
+ }
+
+ // See if anyone else has anything to say
+ return elgg_trigger_plugin_hook(
+ 'container_permissions_check',
+ $type,
+ array(
+ 'container' => $container,
+ 'user' => $user,
+ 'subtype' => $subtype
+ ),
+ $return);
+}
+
+/**
+ * Create a new entry in the entities table.
+ *
+ * Saves the base information in the entities table for the entity. Saving
+ * the type information is handled in the calling class method.
+ *
+ * @warning Plugin authors should never call this directly. Always use entity objects.
+ *
+ * @warning Entities must have an entry in both the entities table and their type table
+ * or they will throw an exception when loaded.
+ *
+ * @param string $type The type of the entity (site, user, object, group).
+ * @param string $subtype The subtype of the entity.
+ * @param int $owner_guid The GUID of the object's owner.
+ * @param int $access_id The access control group to create the entity with.
+ * @param int $site_guid The site to add this entity to. 0 for current.
+ * @param int $container_guid The container GUID
+ *
+ * @return int|false The new entity's GUID, or false on failure
+ * @throws InvalidParameterException
+ * @link http://docs.elgg.org/DataModel/Entities
+ * @access private
+ */
+function create_entity($type, $subtype, $owner_guid, $access_id, $site_guid = 0,
+$container_guid = 0) {
+
+ global $CONFIG;
+
+ $type = sanitise_string($type);
+ $subtype_id = add_subtype($type, $subtype);
+ $owner_guid = (int)$owner_guid;
+ $access_id = (int)$access_id;
+ $time = time();
+ if ($site_guid == 0) {
+ $site_guid = $CONFIG->site_guid;
+ }
+ $site_guid = (int) $site_guid;
+ if ($container_guid == 0) {
+ $container_guid = $owner_guid;
+ }
+
+ $user_guid = elgg_get_logged_in_user_guid();
+ if (!can_write_to_container($user_guid, $owner_guid, $type, $subtype)) {
+ return false;
+ }
+ if ($owner_guid != $container_guid) {
+ if (!can_write_to_container($user_guid, $container_guid, $type, $subtype)) {
+ return false;
+ }
+ }
+ if ($type == "") {
+ throw new InvalidParameterException(elgg_echo('InvalidParameterException:EntityTypeNotSet'));
+ }
+
+ return insert_data("INSERT into {$CONFIG->dbprefix}entities
+ (type, subtype, owner_guid, site_guid, container_guid,
+ access_id, time_created, time_updated, last_action)
+ values
+ ('$type',$subtype_id, $owner_guid, $site_guid, $container_guid,
+ $access_id, $time, $time, $time)");
+}
+
+/**
+ * Returns a database row from the entities table.
+ *
+ * @tip 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 {@link get_access_sql_suffix()}.
+ *
+ * @param int $guid The GUID of the object to extract
+ *
+ * @return stdClass|false
+ * @link http://docs.elgg.org/DataModel/Entities
+ * @see entity_row_to_elggstar()
+ * @access private
+ */
+function get_entity_as_row($guid) {
+ global $CONFIG;
+
+ if (!$guid) {
+ return false;
+ }
+
+ $guid = (int) $guid;
+ $access = get_access_sql_suffix();
+
+ return get_data_row("SELECT * from {$CONFIG->dbprefix}entities where guid=$guid and $access");
+}
+
+/**
+ * Create an Elgg* object from a given entity row.
+ *
+ * Handles loading all tables into the correct class.
+ *
+ * @param stdClass $row The row of the entry in the entities table.
+ *
+ * @return ElggEntity|false
+ * @link http://docs.elgg.org/DataModel/Entities
+ * @see get_entity_as_row()
+ * @see add_subtype()
+ * @see get_entity()
+ * @access private
+ *
+ * @throws ClassException|InstallationException
+ */
+function entity_row_to_elggstar($row) {
+ if (!($row instanceof stdClass)) {
+ return $row;
+ }
+
+ if ((!isset($row->guid)) || (!isset($row->subtype))) {
+ return $row;
+ }
+
+ $new_entity = false;
+
+ // Create a memcache cache if we can
+ static $newentity_cache;
+ if ((!$newentity_cache) && (is_memcache_available())) {
+ $newentity_cache = new ElggMemcache('new_entity_cache');
+ }
+ if ($newentity_cache) {
+ $new_entity = $newentity_cache->load($row->guid);
+ }
+ if ($new_entity) {
+ return $new_entity;
+ }
+
+ // load class for entity if one is registered
+ $classname = get_subtype_class_from_id($row->subtype);
+ if ($classname != "") {
+ if (class_exists($classname)) {
+ $new_entity = new $classname($row);
+
+ if (!($new_entity instanceof ElggEntity)) {
+ $msg = elgg_echo('ClassException:ClassnameNotClass', array($classname, 'ElggEntity'));
+ throw new ClassException($msg);
+ }
+ } else {
+ error_log(elgg_echo('ClassNotFoundException:MissingClass', array($classname)));
+ }
+ }
+
+ if (!$new_entity) {
+ //@todo Make this into a function
+ switch ($row->type) {
+ case 'object' :
+ $new_entity = new ElggObject($row);
+ break;
+ case 'user' :
+ $new_entity = new ElggUser($row);
+ break;
+ case 'group' :
+ $new_entity = new ElggGroup($row);
+ break;
+ case 'site' :
+ $new_entity = new ElggSite($row);
+ break;
+ default:
+ $msg = elgg_echo('InstallationException:TypeNotSupported', array($row->type));
+ throw new InstallationException($msg);
+ }
+ }
+
+ // Cache entity if we have a cache available
+ if (($newentity_cache) && ($new_entity)) {
+ $newentity_cache->save($new_entity->guid, $new_entity);
+ }
+
+ return $new_entity;
+}
+
+/**
+ * Loads and returns an entity object from a guid.
+ *
+ * @param int $guid The GUID of the entity
+ *
+ * @return ElggEntity The correct Elgg or custom object based upon entity type and subtype
+ * @link http://docs.elgg.org/DataModel/Entities
+ */
+function get_entity($guid) {
+ // This should not be a static local var. Notice that cache writing occurs in a completely
+ // different instance outside this function.
+ // @todo We need a single Memcache instance with a shared pool of namespace wrappers. This function would pull an instance from the pool.
+ static $shared_cache;
+
+ // We could also use: if (!(int) $guid) { return FALSE },
+ // but that evaluates to a false positive for $guid = TRUE.
+ // This is a bit slower, but more thorough.
+ if (!is_numeric($guid) || $guid === 0 || $guid === '0') {
+ return false;
+ }
+
+ // Check local cache first
+ $new_entity = retrieve_cached_entity($guid);
+ if ($new_entity) {
+ return $new_entity;
+ }
+
+ // Check shared memory cache, if available
+ if (null === $shared_cache) {
+ if (is_memcache_available()) {
+ $shared_cache = new ElggMemcache('new_entity_cache');
+ } else {
+ $shared_cache = false;
+ }
+ }
+
+ // until ACLs in memcache, DB query is required to determine access
+ $entity_row = get_entity_as_row($guid);
+ if (!$entity_row) {
+ return false;
+ }
+
+ if ($shared_cache) {
+ $cached_entity = $shared_cache->load($guid);
+ // @todo store ACLs in memcache http://trac.elgg.org/ticket/3018#comment:3
+ if ($cached_entity) {
+ // @todo use ACL and cached entity access_id to determine if user can see it
+ return $cached_entity;
+ }
+ }
+
+ // don't let incomplete entities cause fatal exceptions
+ try {
+ $new_entity = entity_row_to_elggstar($entity_row);
+ } catch (IncompleteEntityException $e) {
+ return false;
+ }
+
+ if ($new_entity) {
+ cache_entity($new_entity);
+ }
+ return $new_entity;
+}
+
+/**
+ * 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.
+ *
+ * @param int $guid The GUID of the entity
+ *
+ * @return bool
+ * @since 1.8.0
+ */
+function elgg_entity_exists($guid) {
+ global $CONFIG;
+
+ $guid = sanitize_int($guid);
+
+ $query = "SELECT count(*) as total FROM {$CONFIG->dbprefix}entities WHERE guid = $guid";
+ $result = get_data_row($query);
+ if ($result->total == 0) {
+ return false;
+ } else {
+ return true;
+ }
+}
+
+/**
+ * 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.
+ *
+ * @tip To output formatted strings of entities, use {@link elgg_list_entities()} and
+ * its cousins.
+ *
+ * @tip Plural arguments can be written as singular if only specifying a
+ * single element. ('type' => 'object' vs 'types' => array('object')).
+ *
+ * @param array $options 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 for no subtype.
+ *
+ * type_subtype_pairs => NULL|ARR (array('type' => 'subtype'))
+ * (type = '$type' AND subtype = '$subtype') pairs
+ *
+ * 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 (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
+ *
+ * callback => string A callback function to pass each row through
+ *
+ * @return mixed If count, int. If not count, array. false on errors.
+ * @since 1.7.0
+ * @see elgg_get_entities_from_metadata()
+ * @see elgg_get_entities_from_relationship()
+ * @see elgg_get_entities_from_access_id()
+ * @see elgg_get_entities_from_annotations()
+ * @see elgg_list_entities()
+ * @link http://docs.elgg.org/DataModel/Entities/Getters
+ */
+function elgg_get_entities(array $options = array()) {
+ global $CONFIG;
+
+ $defaults = array(
+ 'types' => ELGG_ENTITIES_ANY_VALUE,
+ 'subtypes' => ELGG_ENTITIES_ANY_VALUE,
+ 'type_subtype_pairs' => ELGG_ENTITIES_ANY_VALUE,
+
+ 'guids' => ELGG_ENTITIES_ANY_VALUE,
+ 'owner_guids' => ELGG_ENTITIES_ANY_VALUE,
+ 'container_guids' => ELGG_ENTITIES_ANY_VALUE,
+ 'site_guids' => $CONFIG->site_guid,
+
+ 'modified_time_lower' => ELGG_ENTITIES_ANY_VALUE,
+ 'modified_time_upper' => ELGG_ENTITIES_ANY_VALUE,
+ 'created_time_lower' => ELGG_ENTITIES_ANY_VALUE,
+ 'created_time_upper' => ELGG_ENTITIES_ANY_VALUE,
+
+ 'reverse_order_by' => false,
+ 'order_by' => 'e.time_created desc',
+ 'group_by' => ELGG_ENTITIES_ANY_VALUE,
+ 'limit' => 10,
+ 'offset' => 0,
+ 'count' => FALSE,
+ 'selects' => array(),
+ 'wheres' => array(),
+ 'joins' => array(),
+
+ 'callback' => 'entity_row_to_elggstar',
+ );
+
+ $options = array_merge($defaults, $options);
+
+ // can't use helper function with type_subtype_pair because
+ // it's already an array...just need to merge it
+ if (isset($options['type_subtype_pair'])) {
+ if (isset($options['type_subtype_pairs'])) {
+ $options['type_subtype_pairs'] = array_merge($options['type_subtype_pairs'],
+ $options['type_subtype_pair']);
+ } else {
+ $options['type_subtype_pairs'] = $options['type_subtype_pair'];
+ }
+ }
+
+ $singulars = array('type', 'subtype', 'guid', 'owner_guid', 'container_guid', 'site_guid');
+ $options = elgg_normalise_plural_options_array($options, $singulars);
+
+ // evaluate where clauses
+ if (!is_array($options['wheres'])) {
+ $options['wheres'] = array($options['wheres']);
+ }
+
+ $wheres = $options['wheres'];
+
+ $wheres[] = elgg_get_entity_type_subtype_where_sql('e', $options['types'],
+ $options['subtypes'], $options['type_subtype_pairs']);
+
+ $wheres[] = elgg_get_guid_based_where_sql('e.guid', $options['guids']);
+ $wheres[] = elgg_get_guid_based_where_sql('e.owner_guid', $options['owner_guids']);
+ $wheres[] = elgg_get_guid_based_where_sql('e.container_guid', $options['container_guids']);
+ $wheres[] = elgg_get_guid_based_where_sql('e.site_guid', $options['site_guids']);
+
+ $wheres[] = elgg_get_entity_time_where_sql('e', $options['created_time_upper'],
+ $options['created_time_lower'], $options['modified_time_upper'], $options['modified_time_lower']);
+
+ // see if any functions failed
+ // remove empty strings on successful functions
+ foreach ($wheres as $i => $where) {
+ if ($where === FALSE) {
+ return FALSE;
+ } elseif (empty($where)) {
+ unset($wheres[$i]);
+ }
+ }
+
+ // remove identical where clauses
+ $wheres = array_unique($wheres);
+
+ // evaluate join clauses
+ if (!is_array($options['joins'])) {
+ $options['joins'] = array($options['joins']);
+ }
+
+ // remove identical join clauses
+ $joins = array_unique($options['joins']);
+
+ foreach ($joins as $i => $join) {
+ if ($join === FALSE) {
+ return FALSE;
+ } elseif (empty($join)) {
+ unset($joins[$i]);
+ }
+ }
+
+ // evalutate selects
+ if ($options['selects']) {
+ $selects = '';
+ foreach ($options['selects'] as $select) {
+ $selects .= ", $select";
+ }
+ } else {
+ $selects = '';
+ }
+
+ if (!$options['count']) {
+ $query = "SELECT DISTINCT e.*{$selects} FROM {$CONFIG->dbprefix}entities e ";
+ } else {
+ $query = "SELECT count(DISTINCT e.guid) as total FROM {$CONFIG->dbprefix}entities e ";
+ }
+
+ // add joins
+ foreach ($joins as $j) {
+ $query .= " $j ";
+ }
+
+ // add wheres
+ $query .= ' WHERE ';
+
+ foreach ($wheres as $w) {
+ $query .= " $w AND ";
+ }
+
+ // Add access controls
+ $query .= get_access_sql_suffix('e');
+
+ // reverse order by
+ if ($options['reverse_order_by']) {
+ $options['order_by'] = elgg_sql_reverse_order_by_clause($options['order_by']);
+ }
+
+ if (!$options['count']) {
+ if ($options['group_by']) {
+ $query .= " GROUP BY {$options['group_by']}";
+ }
+
+ if ($options['order_by']) {
+ $query .= " ORDER BY {$options['order_by']}";
+ }
+
+ if ($options['limit']) {
+ $limit = sanitise_int($options['limit'], false);
+ $offset = sanitise_int($options['offset'], false);
+ $query .= " LIMIT $offset, $limit";
+ }
+
+ if ($options['callback'] === 'entity_row_to_elggstar') {
+ $dt = _elgg_fetch_entities_from_sql($query);
+ } else {
+ $dt = get_data($query, $options['callback']);
+ }
+
+ if ($dt) {
+ // populate entity and metadata caches
+ $guids = array();
+ foreach ($dt as $item) {
+ // A custom callback could result in items that aren't ElggEntity's, so check for them
+ if ($item instanceof ElggEntity) {
+ cache_entity($item);
+ // plugins usually have only settings
+ if (!$item instanceof ElggPlugin) {
+ $guids[] = $item->guid;
+ }
+ }
+ }
+ // @todo Without this, recursive delete fails. See #4568
+ reset($dt);
+
+ if ($guids) {
+ elgg_get_metadata_cache()->populateFromEntities($guids);
+ }
+ }
+ return $dt;
+ } else {
+ $total = get_data_row($query);
+ return (int)$total->total;
+ }
+}
+
+/**
+ * Return entities from an SQL query generated by elgg_get_entities.
+ *
+ * @param string $sql
+ * @return ElggEntity[]
+ *
+ * @access private
+ * @throws LogicException
+ */
+function _elgg_fetch_entities_from_sql($sql) {
+ static $plugin_subtype;
+ if (null === $plugin_subtype) {
+ $plugin_subtype = get_subtype_id('object', 'plugin');
+ }
+
+ // Keys are types, values are columns that, if present, suggest that the secondary
+ // table is already JOINed
+ $types_to_optimize = array(
+ 'object' => 'title',
+ 'user' => 'password',
+ 'group' => 'name',
+ );
+
+ $rows = get_data($sql);
+
+ // guids to look up in each type
+ $lookup_types = array();
+ // maps GUIDs to the $rows key
+ $guid_to_key = array();
+
+ if (isset($rows[0]->type, $rows[0]->subtype)
+ && $rows[0]->type === 'object'
+ && $rows[0]->subtype == $plugin_subtype) {
+ // Likely the entire resultset is plugins, which have already been optimized
+ // to JOIN the secondary table. In this case we allow retrieving from cache,
+ // but abandon the extra queries.
+ $types_to_optimize = array();
+ }
+
+ // First pass: use cache where possible, gather GUIDs that we're optimizing
+ foreach ($rows as $i => $row) {
+ if (empty($row->guid) || empty($row->type)) {
+ throw new LogicException('Entity row missing guid or type');
+ }
+ if ($entity = retrieve_cached_entity($row->guid)) {
+ $rows[$i] = $entity;
+ continue;
+ }
+ if (isset($types_to_optimize[$row->type])) {
+ // check if row already looks JOINed.
+ if (isset($row->{$types_to_optimize[$row->type]})) {
+ // Row probably already contains JOINed secondary table. Don't make another query just
+ // to pull data that's already there
+ continue;
+ }
+ $lookup_types[$row->type][] = $row->guid;
+ $guid_to_key[$row->guid] = $i;
+ }
+ }
+ // Do secondary queries and merge rows
+ if ($lookup_types) {
+ $dbprefix = elgg_get_config('dbprefix');
+ }
+ foreach ($lookup_types as $type => $guids) {
+ $set = "(" . implode(',', $guids) . ")";
+ $sql = "SELECT * FROM {$dbprefix}{$type}s_entity WHERE guid IN $set";
+ $secondary_rows = get_data($sql);
+ if ($secondary_rows) {
+ foreach ($secondary_rows as $secondary_row) {
+ $key = $guid_to_key[$secondary_row->guid];
+ // cast to arrays to merge then cast back
+ $rows[$key] = (object)array_merge((array)$rows[$key], (array)$secondary_row);
+ }
+ }
+ }
+ // Second pass to finish conversion
+ foreach ($rows as $i => $row) {
+ if ($row instanceof ElggEntity) {
+ continue;
+ } else {
+ try {
+ $rows[$i] = entity_row_to_elggstar($row);
+ } catch (IncompleteEntityException $e) {
+ // don't let incomplete entities throw fatal errors
+ unset($rows[$i]);
+ }
+ }
+ }
+ return $rows;
+}
+
+/**
+ * Returns SQL where clause for type and subtype on main entity table
+ *
+ * @param string $table Entity table prefix as defined in SELECT...FROM entities $table
+ * @param NULL|array $types Array of types or NULL if none.
+ * @param NULL|array $subtypes Array of subtypes or NULL if none
+ * @param NULL|array $pairs Array of pairs of types and subtypes
+ *
+ * @return FALSE|string
+ * @since 1.7.0
+ * @access private
+ */
+function elgg_get_entity_type_subtype_where_sql($table, $types, $subtypes, $pairs) {
+ // subtype depends upon type.
+ if ($subtypes && !$types) {
+ elgg_log("Cannot set subtypes without type.", 'WARNING');
+ return FALSE;
+ }
+
+ // short circuit if nothing is requested
+ if (!$types && !$subtypes && !$pairs) {
+ return '';
+ }
+
+ // these are the only valid types for entities in elgg
+ $valid_types = elgg_get_config('entity_types');
+
+ // pairs override
+ $wheres = array();
+ if (!is_array($pairs)) {
+ if (!is_array($types)) {
+ $types = array($types);
+ }
+
+ if ($subtypes && !is_array($subtypes)) {
+ $subtypes = array($subtypes);
+ }
+
+ // decrementer for valid types. Return FALSE if no valid types
+ $valid_types_count = count($types);
+ $valid_subtypes_count = 0;
+ // remove invalid types to get an accurate count of
+ // valid types for the invalid subtype detection to use
+ // below.
+ // also grab the count of ALL subtypes on valid types to decrement later on
+ // and check against.
+ //
+ // yes this is duplicating a foreach on $types.
+ foreach ($types as $type) {
+ if (!in_array($type, $valid_types)) {
+ $valid_types_count--;
+ unset($types[array_search($type, $types)]);
+ } else {
+ // do the checking (and decrementing) in the subtype section.
+ $valid_subtypes_count += count($subtypes);
+ }
+ }
+
+ // return false if nothing is valid.
+ if (!$valid_types_count) {
+ return FALSE;
+ }
+
+ // subtypes are based upon types, so we need to look at each
+ // type individually to get the right subtype id.
+ foreach ($types as $type) {
+ $subtype_ids = array();
+ if ($subtypes) {
+ foreach ($subtypes as $subtype) {
+ // check that the subtype is valid (with ELGG_ENTITIES_NO_VALUE being a valid subtype)
+ if (ELGG_ENTITIES_NO_VALUE === $subtype || $subtype_id = get_subtype_id($type, $subtype)) {
+ $subtype_ids[] = (ELGG_ENTITIES_NO_VALUE === $subtype) ? ELGG_ENTITIES_NO_VALUE : $subtype_id;
+ } else {
+ $valid_subtypes_count--;
+ elgg_log("Type-subtype '$type:$subtype' does not exist!", 'NOTICE');
+ continue;
+ }
+ }
+
+ // return false if we're all invalid subtypes in the only valid type
+ if ($valid_subtypes_count <= 0) {
+ return FALSE;
+ }
+ }
+
+ if (is_array($subtype_ids) && count($subtype_ids)) {
+ $subtype_ids_str = implode(',', $subtype_ids);
+ $wheres[] = "({$table}.type = '$type' AND {$table}.subtype IN ($subtype_ids_str))";
+ } else {
+ $wheres[] = "({$table}.type = '$type')";
+ }
+ }
+ } else {
+ // using type/subtype pairs
+ $valid_pairs_count = count($pairs);
+ $valid_pairs_subtypes_count = 0;
+
+ // same deal as above--we need to know how many valid types
+ // and subtypes we have before hitting the subtype section.
+ // also normalize the subtypes into arrays here.
+ foreach ($pairs as $paired_type => $paired_subtypes) {
+ if (!in_array($paired_type, $valid_types)) {
+ $valid_pairs_count--;
+ unset($pairs[array_search($paired_type, $pairs)]);
+ } else {
+ if ($paired_subtypes && !is_array($paired_subtypes)) {
+ $pairs[$paired_type] = array($paired_subtypes);
+ }
+ $valid_pairs_subtypes_count += count($paired_subtypes);
+ }
+ }
+
+ if ($valid_pairs_count <= 0) {
+ return FALSE;
+ }
+ foreach ($pairs as $paired_type => $paired_subtypes) {
+ // this will always be an array because of line 2027, right?
+ // no...some overly clever person can say pair => array('object' => null)
+ if (is_array($paired_subtypes)) {
+ $paired_subtype_ids = array();
+ foreach ($paired_subtypes as $paired_subtype) {
+ if (ELGG_ENTITIES_NO_VALUE === $paired_subtype
+ || ($paired_subtype_id = get_subtype_id($paired_type, $paired_subtype))) {
+
+ $paired_subtype_ids[] = (ELGG_ENTITIES_NO_VALUE === $paired_subtype) ?
+ ELGG_ENTITIES_NO_VALUE : $paired_subtype_id;
+ } else {
+ $valid_pairs_subtypes_count--;
+ elgg_log("Type-subtype '$paired_type:$paired_subtype' does not exist!", 'NOTICE');
+ // return false if we're all invalid subtypes in the only valid type
+ continue;
+ }
+ }
+
+ // return false if there are no valid subtypes.
+ if ($valid_pairs_subtypes_count <= 0) {
+ return FALSE;
+ }
+
+
+ if ($paired_subtype_ids_str = implode(',', $paired_subtype_ids)) {
+ $wheres[] = "({$table}.type = '$paired_type'"
+ . " AND {$table}.subtype IN ($paired_subtype_ids_str))";
+ }
+ } else {
+ $wheres[] = "({$table}.type = '$paired_type')";
+ }
+ }
+ }
+
+ // pairs override the above. return false if they don't exist.
+ if (is_array($wheres) && count($wheres)) {
+ $where = implode(' OR ', $wheres);
+ return "($where)";
+ }
+
+ return '';
+}
+
+/**
+ * Returns SQL where clause for owner and containers.
+ *
+ * @param string $column Column name the guids should be checked against. Usually
+ * best to provide in table.column format.
+ * @param NULL|array $guids Array of GUIDs.
+ *
+ * @return false|string
+ * @since 1.8.0
+ * @access private
+ */
+function elgg_get_guid_based_where_sql($column, $guids) {
+ // short circuit if nothing requested
+ // 0 is a valid guid
+ if (!$guids && $guids !== 0) {
+ return '';
+ }
+
+ // normalize and sanitise owners
+ if (!is_array($guids)) {
+ $guids = array($guids);
+ }
+
+ $guids_sanitized = array();
+ foreach ($guids as $guid) {
+ if ($guid !== ELGG_ENTITIES_NO_VALUE) {
+ $guid = sanitise_int($guid);
+
+ if (!$guid) {
+ return false;
+ }
+ }
+ $guids_sanitized[] = $guid;
+ }
+
+ $where = '';
+ $guid_str = implode(',', $guids_sanitized);
+
+ // implode(',', 0) returns 0.
+ if ($guid_str !== FALSE && $guid_str !== '') {
+ $where = "($column IN ($guid_str))";
+ }
+
+ return $where;
+}
+
+/**
+ * Returns SQL where clause for entity time limits.
+ *
+ * @param string $table Entity table prefix as defined in
+ * SELECT...FROM entities $table
+ * @param NULL|int $time_created_upper Time created upper limit
+ * @param NULL|int $time_created_lower Time created lower limit
+ * @param NULL|int $time_updated_upper Time updated upper limit
+ * @param NULL|int $time_updated_lower Time updated lower limit
+ *
+ * @return FALSE|string FALSE on fail, string on success.
+ * @since 1.7.0
+ * @access private
+ */
+function elgg_get_entity_time_where_sql($table, $time_created_upper = NULL,
+$time_created_lower = NULL, $time_updated_upper = NULL, $time_updated_lower = NULL) {
+
+ $wheres = array();
+
+ // exploit PHP's loose typing (quack) to check that they are INTs and not str cast to 0
+ if ($time_created_upper && $time_created_upper == sanitise_int($time_created_upper)) {
+ $wheres[] = "{$table}.time_created <= $time_created_upper";
+ }
+
+ if ($time_created_lower && $time_created_lower == sanitise_int($time_created_lower)) {
+ $wheres[] = "{$table}.time_created >= $time_created_lower";
+ }
+
+ if ($time_updated_upper && $time_updated_upper == sanitise_int($time_updated_upper)) {
+ $wheres[] = "{$table}.time_updated <= $time_updated_upper";
+ }
+
+ if ($time_updated_lower && $time_updated_lower == sanitise_int($time_updated_lower)) {
+ $wheres[] = "{$table}.time_updated >= $time_updated_lower";
+ }
+
+ if (is_array($wheres) && count($wheres) > 0) {
+ $where_str = implode(' AND ', $wheres);
+ return "($where_str)";
+ }
+
+ return '';
+}
+
+/**
+ * Returns a string of parsed entities.
+ *
+ * Displays list of entities with formatting specified
+ * by the entity view.
+ *
+ * @tip Pagination is handled automatically.
+ *
+ * @internal This also provides the views for elgg_view_annotation().
+ *
+ * @param array $options Any options from $getter options plus:
+ * full_view => BOOL Display full view entities
+ * list_type => STR 'list' or 'gallery'
+ * list_type_toggle => BOOL Display gallery / list switch
+ * pagination => BOOL Display pagination links
+ *
+ * @param mixed $getter The entity getter function to use to fetch the entities
+ * @param mixed $viewer The function to use to view the entity list.
+ *
+ * @return string
+ * @since 1.7
+ * @see elgg_get_entities()
+ * @see elgg_view_entity_list()
+ * @link http://docs.elgg.org/Entities/Output
+ */
+function elgg_list_entities(array $options = array(), $getter = 'elgg_get_entities',
+ $viewer = 'elgg_view_entity_list') {
+
+ global $autofeed;
+ $autofeed = true;
+
+ $defaults = array(
+ 'offset' => (int) max(get_input('offset', 0), 0),
+ 'limit' => (int) max(get_input('limit', 10), 0),
+ 'full_view' => TRUE,
+ 'list_type_toggle' => FALSE,
+ 'pagination' => TRUE,
+ );
+
+ $options = array_merge($defaults, $options);
+
+ //backwards compatibility
+ if (isset($options['view_type_toggle'])) {
+ $options['list_type_toggle'] = $options['view_type_toggle'];
+ }
+
+ $options['count'] = TRUE;
+ $count = $getter($options);
+
+ $options['count'] = FALSE;
+ $entities = $getter($options);
+
+ $options['count'] = $count;
+
+ return $viewer($entities, $options);
+}
+
+/**
+ * Returns a list of months in which entities were updated or created.
+ *
+ * @tip 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.
+ *
+ * @param string $type The type of entity
+ * @param string $subtype The subtype of entity
+ * @param int $container_guid The container GUID that the entinties belong to
+ * @param int $site_guid The site GUID
+ * @param string $order_by Order_by SQL order by clause
+ *
+ * @return array|false Either an array months as YYYYMM, or false on failure
+ */
+function get_entity_dates($type = '', $subtype = '', $container_guid = 0, $site_guid = 0,
+$order_by = 'time_created') {
+
+ global $CONFIG;
+
+ $site_guid = (int) $site_guid;
+ if ($site_guid == 0) {
+ $site_guid = $CONFIG->site_guid;
+ }
+ $where = array();
+
+ if ($type != "") {
+ $type = sanitise_string($type);
+ $where[] = "type='$type'";
+ }
+
+ if (is_array($subtype)) {
+ $tempwhere = "";
+ if (sizeof($subtype)) {
+ foreach ($subtype as $typekey => $subtypearray) {
+ foreach ($subtypearray as $subtypeval) {
+ $typekey = sanitise_string($typekey);
+ if (!empty($subtypeval)) {
+ if (!$subtypeval = (int) get_subtype_id($typekey, $subtypeval)) {
+ return false;
+ }
+ } else {
+ $subtypeval = 0;
+ }
+ if (!empty($tempwhere)) {
+ $tempwhere .= " or ";
+ }
+ $tempwhere .= "(type = '{$typekey}' and subtype = {$subtypeval})";
+ }
+ }
+ }
+ if (!empty($tempwhere)) {
+ $where[] = "({$tempwhere})";
+ }
+ } else {
+ if ($subtype) {
+ if (!$subtype_id = get_subtype_id($type, $subtype)) {
+ return FALSE;
+ } else {
+ $where[] = "subtype=$subtype_id";
+ }
+ }
+ }
+
+ if ($container_guid !== 0) {
+ if (is_array($container_guid)) {
+ foreach ($container_guid as $key => $val) {
+ $container_guid[$key] = (int) $val;
+ }
+ $where[] = "container_guid in (" . implode(",", $container_guid) . ")";
+ } else {
+ $container_guid = (int) $container_guid;
+ $where[] = "container_guid = {$container_guid}";
+ }
+ }
+
+ if ($site_guid > 0) {
+ $where[] = "site_guid = {$site_guid}";
+ }
+
+ $where[] = get_access_sql_suffix();
+
+ $sql = "SELECT DISTINCT EXTRACT(YEAR_MONTH FROM FROM_UNIXTIME(time_created)) AS yearmonth
+ FROM {$CONFIG->dbprefix}entities where ";
+
+ foreach ($where as $w) {
+ $sql .= " $w and ";
+ }
+
+ $sql .= "1=1 ORDER BY $order_by";
+ if ($result = get_data($sql)) {
+ $endresult = array();
+ foreach ($result as $res) {
+ $endresult[] = $res->yearmonth;
+ }
+ return $endresult;
+ }
+ return false;
+}
+
+/**
+ * Disable an entity.
+ *
+ * Disabled entities do not show up in list or elgg_get_entity()
+ * calls, but still exist in the database.
+ *
+ * Entities are disabled by setting disabled = yes in the
+ * entities table.
+ *
+ * You can ignore the disabled field by using {@link access_show_hidden_entities()}.
+ *
+ * @note Use ElggEntity::disable() instead.
+ *
+ * @param int $guid The guid
+ * @param string $reason Optional reason
+ * @param bool $recursive Recursively disable all entities owned or contained by $guid?
+ *
+ * @return bool
+ * @see access_show_hidden_entities()
+ * @link http://docs.elgg.org/Entities
+ * @access private
+ */
+function disable_entity($guid, $reason = "", $recursive = true) {
+ global $CONFIG;
+
+ $guid = (int)$guid;
+ $reason = sanitise_string($reason);
+
+ if ($entity = get_entity($guid)) {
+ if (elgg_trigger_event('disable', $entity->type, $entity)) {
+ if ($entity->canEdit()) {
+ if ($reason) {
+ create_metadata($guid, 'disable_reason', $reason, '', 0, ACCESS_PUBLIC);
+ }
+
+ if ($recursive) {
+ $hidden = access_get_show_hidden_status();
+ access_show_hidden_entities(true);
+ $ia = elgg_set_ignore_access(true);
+
+ $sub_entities = get_data("SELECT * FROM {$CONFIG->dbprefix}entities
+ WHERE (
+ container_guid = $guid
+ OR owner_guid = $guid
+ OR site_guid = $guid
+ ) AND enabled='yes'", 'entity_row_to_elggstar');
+
+ if ($sub_entities) {
+ foreach ($sub_entities as $e) {
+ add_entity_relationship($e->guid, 'disabled_with', $entity->guid);
+ $e->disable($reason);
+ }
+ }
+ access_show_hidden_entities($hidden);
+ elgg_set_ignore_access($ia);
+ }
+
+ $entity->disableMetadata();
+ $entity->disableAnnotations();
+ invalidate_cache_for_entity($guid);
+
+ $res = update_data("UPDATE {$CONFIG->dbprefix}entities
+ SET enabled = 'no'
+ WHERE guid = $guid");
+
+ return $res;
+ }
+ }
+ }
+ return false;
+}
+
+/**
+ * Enable an entity.
+ *
+ * @warning In order to enable an entity using ElggEntity::enable(),
+ * you must first use {@link access_show_hidden_entities()}.
+ *
+ * @param int $guid GUID of entity to enable
+ * @param bool $recursive Recursively enable all entities disabled with the entity?
+ *
+ * @return bool
+ */
+function enable_entity($guid, $recursive = true) {
+ global $CONFIG;
+
+ $guid = (int)$guid;
+
+ // Override access only visible entities
+ $old_access_status = access_get_show_hidden_status();
+ access_show_hidden_entities(true);
+
+ $result = false;
+ if ($entity = get_entity($guid)) {
+ if (elgg_trigger_event('enable', $entity->type, $entity)) {
+ if ($entity->canEdit()) {
+
+ $result = update_data("UPDATE {$CONFIG->dbprefix}entities
+ SET enabled = 'yes'
+ WHERE guid = $guid");
+
+ $entity->deleteMetadata('disable_reason');
+ $entity->enableMetadata();
+ $entity->enableAnnotations();
+
+ if ($recursive) {
+ $disabled_with_it = elgg_get_entities_from_relationship(array(
+ 'relationship' => 'disabled_with',
+ 'relationship_guid' => $entity->guid,
+ 'inverse_relationship' => true,
+ 'limit' => 0,
+ ));
+
+ foreach ($disabled_with_it as $e) {
+ $e->enable();
+ remove_entity_relationship($e->guid, 'disabled_with', $entity->guid);
+ }
+ }
+ }
+ }
+ }
+
+ access_show_hidden_entities($old_access_status);
+ return $result;
+}
+
+/**
+ * Delete an entity.
+ *
+ * Removes an entity and its metadata, annotations, relationships, river entries,
+ * and private data.
+ *
+ * Optionally can remove entities contained and owned by $guid.
+ *
+ * @tip Use ElggEntity::delete() instead.
+ *
+ * @warning If deleting recursively, this bypasses ownership of items contained by
+ * the entity. That means that if the container_guid = $guid, the item will be deleted
+ * regardless of who owns it.
+ *
+ * @param int $guid The guid of the entity to delete
+ * @param bool $recursive If true (default) then all entities which are
+ * owned or contained by $guid will also be deleted.
+ *
+ * @return bool
+ * @access private
+ */
+function delete_entity($guid, $recursive = true) {
+ global $CONFIG, $ENTITY_CACHE;
+
+ $guid = (int)$guid;
+ if ($entity = get_entity($guid)) {
+ if (elgg_trigger_event('delete', $entity->type, $entity)) {
+ if ($entity->canEdit()) {
+
+ // delete cache
+ if (isset($ENTITY_CACHE[$guid])) {
+ invalidate_cache_for_entity($guid);
+ }
+
+ // If memcache is available then delete this entry from the cache
+ static $newentity_cache;
+ if ((!$newentity_cache) && (is_memcache_available())) {
+ $newentity_cache = new ElggMemcache('new_entity_cache');
+ }
+ if ($newentity_cache) {
+ $newentity_cache->delete($guid);
+ }
+
+ // Delete contained owned and otherwise releated objects (depth first)
+ if ($recursive) {
+ // Temporary token overriding access controls
+ // @todo Do this better.
+ static $__RECURSIVE_DELETE_TOKEN;
+ // Make it slightly harder to guess
+ $__RECURSIVE_DELETE_TOKEN = md5(elgg_get_logged_in_user_guid());
+
+ $entity_disable_override = access_get_show_hidden_status();
+ access_show_hidden_entities(true);
+ $ia = elgg_set_ignore_access(true);
+
+ // @todo there was logic in the original code that ignored
+ // entities with owner or container guids of themselves.
+ // this should probably be prevented in ElggEntity instead of checked for here
+ $options = array(
+ 'wheres' => array(
+ "((container_guid = $guid OR owner_guid = $guid OR site_guid = $guid)"
+ . " AND guid != $guid)"
+ ),
+ 'limit' => 0
+ );
+
+ $batch = new ElggBatch('elgg_get_entities', $options);
+ $batch->setIncrementOffset(false);
+
+ foreach ($batch as $e) {
+ $e->delete(true);
+ }
+
+ access_show_hidden_entities($entity_disable_override);
+ $__RECURSIVE_DELETE_TOKEN = null;
+ elgg_set_ignore_access($ia);
+ }
+
+ // Now delete the entity itself
+ $entity->deleteMetadata();
+ $entity->deleteOwnedMetadata();
+ $entity->deleteAnnotations();
+ $entity->deleteOwnedAnnotations();
+ $entity->deleteRelationships();
+
+ elgg_delete_river(array('subject_guid' => $guid));
+ elgg_delete_river(array('object_guid' => $guid));
+ remove_all_private_settings($guid);
+
+ $res = delete_data("DELETE from {$CONFIG->dbprefix}entities where guid={$guid}");
+ if ($res) {
+ $sub_table = "";
+
+ // Where appropriate delete the sub table
+ switch ($entity->type) {
+ case 'object' :
+ $sub_table = $CONFIG->dbprefix . 'objects_entity';
+ break;
+ case 'user' :
+ $sub_table = $CONFIG->dbprefix . 'users_entity';
+ break;
+ case 'group' :
+ $sub_table = $CONFIG->dbprefix . 'groups_entity';
+ break;
+ case 'site' :
+ $sub_table = $CONFIG->dbprefix . 'sites_entity';
+ break;
+ }
+
+ if ($sub_table) {
+ delete_data("DELETE from $sub_table where guid={$guid}");
+ }
+ }
+
+ return (bool)$res;
+ }
+ }
+ }
+ return false;
+
+}
+
+/**
+ * Exports attributes generated on the fly (volatile) about an entity.
+ *
+ * @param string $hook volatile
+ * @param string $entity_type metadata
+ * @param string $returnvalue Return value from previous hook
+ * @param array $params The parameters, passed 'guid' and 'varname'
+ *
+ * @return ElggMetadata|null
+ * @elgg_plugin_hook_handler volatile metadata
+ * @todo investigate more.
+ * @access private
+ * @todo document
+ */
+function volatile_data_export_plugin_hook($hook, $entity_type, $returnvalue, $params) {
+ $guid = (int)$params['guid'];
+ $variable_name = sanitise_string($params['varname']);
+
+ if (($hook == 'volatile') && ($entity_type == 'metadata')) {
+ if (($guid) && ($variable_name)) {
+ switch ($variable_name) {
+ case 'renderedentity' :
+ elgg_set_viewtype('default');
+ $view = elgg_view_entity(get_entity($guid));
+ elgg_set_viewtype();
+
+ $tmp = new ElggMetadata();
+ $tmp->type = 'volatile';
+ $tmp->name = 'renderedentity';
+ $tmp->value = $view;
+ $tmp->entity_guid = $guid;
+
+ return $tmp;
+
+ break;
+ }
+ }
+ }
+}
+
+/**
+ * Exports all attributes of an entity.
+ *
+ * @warning Only exports fields in the entity and entity type tables.
+ *
+ * @param string $hook export
+ * @param string $entity_type all
+ * @param mixed $returnvalue Previous hook return value
+ * @param array $params Parameters
+ *
+ * @elgg_event_handler export all
+ * @return mixed
+ * @access private
+ *
+ * @throws InvalidParameterException|InvalidClassException
+ */
+function export_entity_plugin_hook($hook, $entity_type, $returnvalue, $params) {
+ // Sanity check values
+ if ((!is_array($params)) && (!isset($params['guid']))) {
+ throw new InvalidParameterException(elgg_echo('InvalidParameterException:GUIDNotForExport'));
+ }
+
+ if (!is_array($returnvalue)) {
+ throw new InvalidParameterException(elgg_echo('InvalidParameterException:NonArrayReturnValue'));
+ }
+
+ $guid = (int)$params['guid'];
+
+ // Get the entity
+ $entity = get_entity($guid);
+ if (!($entity instanceof ElggEntity)) {
+ $msg = elgg_echo('InvalidClassException:NotValidElggStar', array($guid, get_class()));
+ throw new InvalidClassException($msg);
+ }
+
+ $export = $entity->export();
+
+ if (is_array($export)) {
+ foreach ($export as $e) {
+ $returnvalue[] = $e;
+ }
+ } else {
+ $returnvalue[] = $export;
+ }
+
+ return $returnvalue;
+}
+
+/**
+ * Utility function used by import_entity_plugin_hook() to
+ * process an ODDEntity into an unsaved ElggEntity.
+ *
+ * @param ODDEntity $element The OpenDD element
+ *
+ * @return ElggEntity the unsaved entity which should be populated by items.
+ * @todo Remove this.
+ * @access private
+ *
+ * @throws ClassException|InstallationException|ImportException
+ */
+function oddentity_to_elggentity(ODDEntity $element) {
+ $class = $element->getAttribute('class');
+ $subclass = $element->getAttribute('subclass');
+
+ // See if we already have imported this uuid
+ $tmp = get_entity_from_uuid($element->getAttribute('uuid'));
+
+ if (!$tmp) {
+ // Construct new class with owner from session
+ $classname = get_subtype_class($class, $subclass);
+ if ($classname) {
+ if (class_exists($classname)) {
+ $tmp = new $classname();
+
+ if (!($tmp instanceof ElggEntity)) {
+ $msg = elgg_echo('ClassException:ClassnameNotClass', array($classname, get_class()));
+ throw new ClassException($msg);
+ }
+ } else {
+ error_log(elgg_echo('ClassNotFoundException:MissingClass', array($classname)));
+ }
+ } else {
+ switch ($class) {
+ case 'object' :
+ $tmp = new ElggObject($row);
+ break;
+ case 'user' :
+ $tmp = new ElggUser($row);
+ break;
+ case 'group' :
+ $tmp = new ElggGroup($row);
+ break;
+ case 'site' :
+ $tmp = new ElggSite($row);
+ break;
+ default:
+ $msg = elgg_echo('InstallationException:TypeNotSupported', array($class));
+ throw new InstallationException($msg);
+ }
+ }
+ }
+
+ if ($tmp) {
+ if (!$tmp->import($element)) {
+ $msg = elgg_echo('ImportException:ImportFailed', array($element->getAttribute('uuid')));
+ throw new ImportException($msg);
+ }
+
+ return $tmp;
+ }
+
+ return NULL;
+}
+
+/**
+ * Import an entity.
+ *
+ * This function checks the passed XML doc (as array) to see if it is
+ * a user, if so it constructs a new elgg user and returns "true"
+ * to inform the importer that it's been handled.
+ *
+ * @param string $hook import
+ * @param string $entity_type all
+ * @param mixed $returnvalue Value from previous hook
+ * @param mixed $params Array of params
+ *
+ * @return mixed
+ * @elgg_plugin_hook_handler import all
+ * @todo document
+ * @access private
+ *
+ * @throws ImportException
+ */
+function import_entity_plugin_hook($hook, $entity_type, $returnvalue, $params) {
+ $element = $params['element'];
+
+ $tmp = null;
+
+ if ($element instanceof ODDEntity) {
+ $tmp = oddentity_to_elggentity($element);
+
+ if ($tmp) {
+ // Make sure its saved
+ if (!$tmp->save()) {
+ $msg = elgg_echo('ImportException:ProblemSaving', array($element->getAttribute('uuid')));
+ throw new ImportException($msg);
+ }
+
+ // Belts and braces
+ if (!$tmp->guid) {
+ throw new ImportException(elgg_echo('ImportException:NoGUID'));
+ }
+
+ // We have saved, so now tag
+ add_uuid_to_guid($tmp->guid, $element->getAttribute('uuid'));
+
+ return $tmp;
+ }
+ }
+}
+
+/**
+ * Returns if $user_guid is able to edit $entity_guid.
+ *
+ * @tip Can be overridden by by registering for the permissions_check
+ * plugin hook.
+ *
+ * @warning If a $user_guid is not passed it will default to the logged in user.
+ *
+ * @tip Use ElggEntity::canEdit() instead.
+ *
+ * @param int $entity_guid The GUID of the entity
+ * @param int $user_guid The GUID of the user
+ *
+ * @return bool
+ * @link http://docs.elgg.org/Entities/AccessControl
+ */
+function can_edit_entity($entity_guid, $user_guid = 0) {
+ $user_guid = (int)$user_guid;
+ $user = get_entity($user_guid);
+ if (!$user) {
+ $user = elgg_get_logged_in_user_entity();
+ }
+
+ $return = false;
+ if ($entity = get_entity($entity_guid)) {
+
+ // Test user if possible - should default to false unless a plugin hook says otherwise
+ if ($user) {
+ if ($entity->getOwnerGUID() == $user->getGUID()) {
+ $return = true;
+ }
+ if ($entity->container_guid == $user->getGUID()) {
+ $return = true;
+ }
+ if ($entity->type == "user" && $entity->getGUID() == $user->getGUID()) {
+ $return = true;
+ }
+ if ($container_entity = get_entity($entity->container_guid)) {
+ if ($container_entity->canEdit($user->getGUID())) {
+ $return = true;
+ }
+ }
+ }
+ }
+
+ return elgg_trigger_plugin_hook('permissions_check', $entity->type,
+ array('entity' => $entity, 'user' => $user), $return);
+}
+
+/**
+ * Returns if $user_guid can edit the metadata on $entity_guid.
+ *
+ * @tip Can be overridden by by registering for the permissions_check:metadata
+ * plugin hook.
+ *
+ * @warning If a $user_guid isn't specified, the currently logged in user is used.
+ *
+ * @param int $entity_guid The GUID of the entity
+ * @param int $user_guid The GUID of the user
+ * @param ElggMetadata $metadata The metadata to specifically check (if any; default null)
+ *
+ * @return bool
+ * @see elgg_register_plugin_hook_handler()
+ */
+function can_edit_entity_metadata($entity_guid, $user_guid = 0, $metadata = null) {
+ if ($entity = get_entity($entity_guid)) {
+
+ $return = null;
+
+ if ($metadata->owner_guid == 0) {
+ $return = true;
+ }
+ if (is_null($return)) {
+ $return = can_edit_entity($entity_guid, $user_guid);
+ }
+
+ if ($user_guid) {
+ $user = get_entity($user_guid);
+ } else {
+ $user = elgg_get_logged_in_user_entity();
+ }
+
+ $params = array('entity' => $entity, 'user' => $user, 'metadata' => $metadata);
+ $return = elgg_trigger_plugin_hook('permissions_check:metadata', $entity->type, $params, $return);
+ return $return;
+ } else {
+ return false;
+ }
+}
+
+/**
+ * Returns the URL for an entity.
+ *
+ * @tip Can be overridden with {@link register_entity_url_handler()}.
+ *
+ * @param int $entity_guid The GUID of the entity
+ *
+ * @return string The URL of the entity
+ * @see register_entity_url_handler()
+ */
+function get_entity_url($entity_guid) {
+ global $CONFIG;
+
+ if ($entity = get_entity($entity_guid)) {
+ $url = "";
+
+ if (isset($CONFIG->entity_url_handler[$entity->getType()][$entity->getSubType()])) {
+ $function = $CONFIG->entity_url_handler[$entity->getType()][$entity->getSubType()];
+ if (is_callable($function)) {
+ $url = call_user_func($function, $entity);
+ }
+ } elseif (isset($CONFIG->entity_url_handler[$entity->getType()]['all'])) {
+ $function = $CONFIG->entity_url_handler[$entity->getType()]['all'];
+ if (is_callable($function)) {
+ $url = call_user_func($function, $entity);
+ }
+ } elseif (isset($CONFIG->entity_url_handler['all']['all'])) {
+ $function = $CONFIG->entity_url_handler['all']['all'];
+ if (is_callable($function)) {
+ $url = call_user_func($function, $entity);
+ }
+ }
+
+ if ($url == "") {
+ $url = "view/" . $entity_guid;
+ }
+
+ return elgg_normalize_url($url);
+ }
+
+ return false;
+}
+
+/**
+ * Sets the URL handler for a particular entity type and subtype
+ *
+ * @param string $entity_type The entity type
+ * @param string $entity_subtype The entity subtype
+ * @param string $function_name The function to register
+ *
+ * @return bool Depending on success
+ * @see get_entity_url()
+ * @see ElggEntity::getURL()
+ * @since 1.8.0
+ */
+function elgg_register_entity_url_handler($entity_type, $entity_subtype, $function_name) {
+ global $CONFIG;
+
+ if (!is_callable($function_name, true)) {
+ return false;
+ }
+
+ if (!isset($CONFIG->entity_url_handler)) {
+ $CONFIG->entity_url_handler = array();
+ }
+
+ if (!isset($CONFIG->entity_url_handler[$entity_type])) {
+ $CONFIG->entity_url_handler[$entity_type] = array();
+ }
+
+ $CONFIG->entity_url_handler[$entity_type][$entity_subtype] = $function_name;
+
+ return true;
+}
+
+/**
+ * Registers an entity type and subtype as a public-facing entity that should
+ * be shown in search and by {@link elgg_list_registered_entities()}.
+ *
+ * @warning Entities that aren't registered here will not show up in search.
+ *
+ * @tip Add a language string item:type:subtype to make sure the items are display properly.
+ *
+ * @param string $type The type of entity (object, site, user, group)
+ * @param string $subtype The subtype to register (may be blank)
+ *
+ * @return bool Depending on success
+ * @see get_registered_entity_types()
+ * @link http://docs.elgg.org/Search
+ * @link http://docs.elgg.org/Tutorials/Search
+ */
+function elgg_register_entity_type($type, $subtype = null) {
+ global $CONFIG;
+
+ $type = strtolower($type);
+ if (!in_array($type, $CONFIG->entity_types)) {
+ return FALSE;
+ }
+
+ if (!isset($CONFIG->registered_entities)) {
+ $CONFIG->registered_entities = array();
+ }
+
+ if (!isset($CONFIG->registered_entities[$type])) {
+ $CONFIG->registered_entities[$type] = array();
+ }
+
+ if ($subtype) {
+ $CONFIG->registered_entities[$type][] = $subtype;
+ }
+
+ return TRUE;
+}
+
+/**
+ * Unregisters an entity type and subtype as a public-facing entity.
+ *
+ * @warning With a blank subtype, it unregisters that entity type including
+ * all subtypes. This must be called after all subtypes have been registered.
+ *
+ * @param string $type The type of entity (object, site, user, group)
+ * @param string $subtype The subtype to register (may be blank)
+ *
+ * @return bool Depending on success
+ * @see elgg_register_entity_type()
+ */
+function unregister_entity_type($type, $subtype) {
+ global $CONFIG;
+
+ $type = strtolower($type);
+ if (!in_array($type, $CONFIG->entity_types)) {
+ return FALSE;
+ }
+
+ if (!isset($CONFIG->registered_entities)) {
+ return FALSE;
+ }
+
+ if (!isset($CONFIG->registered_entities[$type])) {
+ return FALSE;
+ }
+
+ if ($subtype) {
+ if (in_array($subtype, $CONFIG->registered_entities[$type])) {
+ $key = array_search($subtype, $CONFIG->registered_entities[$type]);
+ unset($CONFIG->registered_entities[$type][$key]);
+ } else {
+ return FALSE;
+ }
+ } else {
+ unset($CONFIG->registered_entities[$type]);
+ }
+
+ return TRUE;
+}
+
+/**
+ * Returns registered entity types and subtypes
+ *
+ * @param string $type The type of entity (object, site, user, group) or blank for all
+ *
+ * @return array|false Depending on whether entities have been registered
+ * @see elgg_register_entity_type()
+ */
+function get_registered_entity_types($type = null) {
+ global $CONFIG;
+
+ if (!isset($CONFIG->registered_entities)) {
+ return false;
+ }
+ if ($type) {
+ $type = strtolower($type);
+ }
+ if (!empty($type) && empty($CONFIG->registered_entities[$type])) {
+ return false;
+ }
+
+ if (empty($type)) {
+ return $CONFIG->registered_entities;
+ }
+
+ return $CONFIG->registered_entities[$type];
+}
+
+/**
+ * Returns if the entity type and subtype have been registered with {@see elgg_register_entity_type()}.
+ *
+ * @param string $type The type of entity (object, site, user, group)
+ * @param string $subtype The subtype (may be blank)
+ *
+ * @return bool Depending on whether or not the type has been registered
+ */
+function is_registered_entity_type($type, $subtype = null) {
+ global $CONFIG;
+
+ if (!isset($CONFIG->registered_entities)) {
+ return false;
+ }
+
+ $type = strtolower($type);
+
+ // @todo registering a subtype implicitly registers the type.
+ // see #2684
+ if (!isset($CONFIG->registered_entities[$type])) {
+ return false;
+ }
+
+ if ($subtype && !in_array($subtype, $CONFIG->registered_entities[$type])) {
+ return false;
+ }
+ return true;
+}
+
+/**
+ * Page handler for generic entities view system
+ *
+ * @param array $page Page elements from pain page handler
+ *
+ * @return bool
+ * @elgg_page_handler view
+ * @access private
+ */
+function entities_page_handler($page) {
+ if (isset($page[0])) {
+ global $CONFIG;
+ set_input('guid', $page[0]);
+ include($CONFIG->path . "pages/entities/index.php");
+ return true;
+ }
+ return false;
+}
+
+/**
+ * Returns a viewable list of entities based on the registered types.
+ *
+ * @see elgg_view_entity_list
+ *
+ * @param array $options Any 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
+ *
+ * @return string A viewable list of entities
+ * @since 1.7.0
+ */
+function elgg_list_registered_entities(array $options = array()) {
+ global $autofeed;
+ $autofeed = true;
+
+ $defaults = array(
+ 'full_view' => TRUE,
+ 'allowed_types' => TRUE,
+ 'list_type_toggle' => FALSE,
+ 'pagination' => TRUE,
+ 'offset' => 0,
+ 'types' => array(),
+ 'type_subtype_pairs' => array()
+ );
+
+ $options = array_merge($defaults, $options);
+
+ //backwards compatibility
+ if (isset($options['view_type_toggle'])) {
+ $options['list_type_toggle'] = $options['view_type_toggle'];
+ }
+
+ $types = get_registered_entity_types();
+
+ foreach ($types as $type => $subtype_array) {
+ if (in_array($type, $options['allowed_types']) || $options['allowed_types'] === TRUE) {
+ // you must explicitly register types to show up in here and in search for objects
+ if ($type == 'object') {
+ if (is_array($subtype_array) && count($subtype_array)) {
+ $options['type_subtype_pairs'][$type] = $subtype_array;
+ }
+ } else {
+ if (is_array($subtype_array) && count($subtype_array)) {
+ $options['type_subtype_pairs'][$type] = $subtype_array;
+ } else {
+ $options['type_subtype_pairs'][$type] = ELGG_ENTITIES_ANY_VALUE;
+ }
+ }
+ }
+ }
+
+ if (!empty($options['type_subtype_pairs'])) {
+ $count = elgg_get_entities(array_merge(array('count' => TRUE), $options));
+ $entities = elgg_get_entities($options);
+ } else {
+ $count = 0;
+ $entities = array();
+ }
+
+ $options['count'] = $count;
+ return elgg_view_entity_list($entities, $options);
+}
+
+/**
+ * Checks if $entity is an ElggEntity and optionally for type and subtype.
+ *
+ * @tip Use this function in actions and views to check that you are dealing
+ * with the correct type of entity.
+ *
+ * @param mixed $entity Entity
+ * @param string $type Entity type
+ * @param string $subtype Entity subtype
+ * @param string $class Class name
+ *
+ * @return bool
+ * @since 1.8.0
+ */
+function elgg_instanceof($entity, $type = NULL, $subtype = NULL, $class = NULL) {
+ $return = ($entity instanceof ElggEntity);
+
+ if ($type) {
+ $return = $return && ($entity->getType() == $type);
+ }
+
+ if ($subtype) {
+ $return = $return && ($entity->getSubtype() == $subtype);
+ }
+
+ if ($class) {
+ $return = $return && ($entity instanceof $class);
+ }
+
+ return $return;
+}
+
+/**
+ * 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.
+ *
+ * @param int $guid Entity annotation|relationship action carried out on
+ * @param int $posted Timestamp of last action
+ *
+ * @return bool
+ * @access private
+ */
+function update_entity_last_action($guid, $posted = NULL) {
+ global $CONFIG;
+ $guid = (int)$guid;
+ $posted = (int)$posted;
+
+ if (!$posted) {
+ $posted = time();
+ }
+
+ if ($guid) {
+ //now add to the river updated table
+ $query = "UPDATE {$CONFIG->dbprefix}entities SET last_action = {$posted} WHERE guid = {$guid}";
+ $result = update_data($query);
+ if ($result) {
+ return TRUE;
+ } else {
+ return FALSE;
+ }
+ } else {
+ return FALSE;
+ }
+}
+
+/**
+ * Garbage collect stub and fragments from any broken delete/create calls
+ *
+ * @return void
+ * @elgg_plugin_hook_handler gc system
+ * @access private
+ */
+function entities_gc() {
+ global $CONFIG;
+
+ $tables = array ('sites_entity', 'objects_entity', 'groups_entity', 'users_entity');
+
+ foreach ($tables as $table) {
+ delete_data("DELETE from {$CONFIG->dbprefix}{$table}
+ where guid NOT IN (SELECT guid from {$CONFIG->dbprefix}entities)");
+ }
+}
+
+/**
+ * Runs unit tests for the entity objects.
+ *
+ * @param string $hook unit_test
+ * @param string $type system
+ * @param mixed $value Array of tests
+ * @param mixed $params Params
+ *
+ * @return array
+ * @access private
+ */
+function entities_test($hook, $type, $value, $params) {
+ global $CONFIG;
+ $value[] = $CONFIG->path . 'engine/tests/objects/entities.php';
+ return $value;
+}
+
+/**
+ * Entities init function; establishes the default entity page handler
+ *
+ * @return void
+ * @elgg_event_handler init system
+ * @access private
+ */
+function entities_init() {
+ elgg_register_page_handler('view', 'entities_page_handler');
+
+ elgg_register_plugin_hook_handler('unit_test', 'system', 'entities_test');
+
+ elgg_register_plugin_hook_handler('gc', 'system', 'entities_gc');
+}
+
+/** Register the import hook */
+elgg_register_plugin_hook_handler("import", "all", "import_entity_plugin_hook", 0);
+
+/** Register the hook, ensuring entities are serialised first */
+elgg_register_plugin_hook_handler("export", "all", "export_entity_plugin_hook", 0);
+
+/** Hook to get certain named bits of volatile data about an entity */
+elgg_register_plugin_hook_handler('volatile', 'metadata', 'volatile_data_export_plugin_hook');
+
+/** Register init system event **/
+elgg_register_event_handler('init', 'system', 'entities_init');
+