<?php
/**
- * Elgg entities.
- * Functions to manage all elgg entities (sites, collections, objects and users).
+ * Procedural code for creating, loading, and modifying ElggEntity objects.
*
- * @package Elgg
- * @subpackage Core
- * @author Curverider Ltd <info@elgg.com>
- * @link http://elgg.org/
+ * @package Elgg.Core
+ * @subpackage DataModel
+ * @link http://docs.elgg.org/DataModel/Entities
*/
-/// Cache objects in order to minimise database access.
+/**
+ * Cache entities in memory once loaded.
+ *
+ * @global array $ENTITY_CACHE
+ * @access private
+ */
$ENTITY_CACHE = NULL;
-/// Cache subtype searches
+/**
+ * Cache subtypes and related class names once loaded.
+ *
+ * @global array $SUBTYPE_CACHE
+ * @access private
+ */
$SUBTYPE_CACHE = NULL;
/**
* Initialise the entity cache.
+ * @todo remove this.
+ * @access private
*/
function initialise_entity_cache() {
global $ENTITY_CACHE;
if (!$ENTITY_CACHE) {
- //select_default_memcache('entity_cache'); // @todo Replace with memcache?
$ENTITY_CACHE = array();
}
}
/**
- * Invalidate this class' entry in the cache.
+ * Invalidate this class's entry in the cache.
*
- * @param int $guid The guid
+ * @param int $guid The entity guid
+ * @access private
*/
function invalidate_cache_for_entity($guid) {
global $ENTITY_CACHE;
$guid = (int)$guid;
unset($ENTITY_CACHE[$guid]);
- //$ENTITY_CACHE->delete($guid);
}
/**
* Cache an entity.
*
+ * Stores an entity in $ENTITY_CACHE;
+ *
* @param ElggEntity $entity Entity to cache
+ * @see retrieve_cached_entity()
+ * @see invalidate_cache_for_entity()
+ * @access private
*/
function cache_entity(ElggEntity $entity) {
global $ENTITY_CACHE;
* Retrieve a entity from the cache.
*
* @param int $guid The guid
+ * @see cache_entity()
+ * @see invalidate_cache_for_entity()
+ * @access private
*/
function retrieve_cached_entity($guid) {
global $ENTITY_CACHE;
* expect a database row.)
*
* @param int $guid The guid
+ * @todo unused
+ * @access private
*/
function retrieve_cached_entity_row($guid) {
$obj = retrieve_cached_entity($guid);
}
/**
- * Return the integer ID for a given subtype, or 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.
*
* @todo Move to a nicer place?
*
* @param string $type
* @param string $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 $CONFIG, $SUBTYPE_CACHE;
$subtype = sanitise_string($subtype);
if ($subtype=="") {
- //return $subtype;
return FALSE;
}
if ($result) {
if (!$SUBTYPE_CACHE) {
- //select_default_memcache('subtype_cache');
$SUBTYPE_CACHE = array();
}
}
/**
- * For a given subtype ID, return its identifier text.
+ * Return string name for a given subtype ID.
*
* @todo Move to a nicer place?
*
* @param int $subtype_id
+ * @return string Subtype name
+ * @link http://docs.elgg.org/DataModel/Entities/Subtypes
+ * @see get_subtype_from_id()
+ * @access private
*/
function get_subtype_from_id($subtype_id) {
global $CONFIG, $SUBTYPE_CACHE;
$result = get_data_row("SELECT * from {$CONFIG->dbprefix}entity_subtypes where id=$subtype_id");
if ($result) {
if (!$SUBTYPE_CACHE) {
- //select_default_memcache('subtype_cache');
$SUBTYPE_CACHE = array();
}
}
/**
- * This function tests to see if a subtype has a registered class handler.
+ * Return a classname for a registered type and subtype.
+ *
+ * Entities can be registered to always be loaded as a certain class
+ * with {@link register_entity_subtype()}. This function returns
+ * the class name if found, and NULL if not.
*
* @param string $type The type
* @param string $subtype The subtype
- * @return a class name or null
+ * @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 $CONFIG, $SUBTYPE_CACHE;
if ($result) {
if (!$SUBTYPE_CACHE) {
- //select_default_memcache('subtype_cache');
$SUBTYPE_CACHE = array();
}
}
/**
- * This function tests to see if a subtype has a registered class handler by its id.
+ * Returns the classname for a subtype id.
*
- * @param int $subtype_id The subtype
- * @return a class name or null
+ * @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 $CONFIG, $SUBTYPE_CACHE;
if ($result) {
if (!$SUBTYPE_CACHE) {
- //select_default_memcache('subtype_cache');
$SUBTYPE_CACHE = array();
}
$SUBTYPE_CACHE[$subtype_id] = $result;
}
/**
- * This function will register a new subtype, returning its ID as required.
+ * Register ElggEntities with a certain type and subtype to be loaded as a specific class.
*
- * @param string $type The type you're subtyping
- * @param string $subtype The subtype label
- * @param string $class Optional class handler (if you don't want it handled by the generic elgg handler for the type)
+ * 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()}.
+ *
+ * @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
+ * @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;
}
/**
- * Removes a registered subtype
+ * Removes a registered ElggEntity type, subtype, and classname.
*
* @param string $type
* @param string $subtype
+ * @see add_subtype()
+ * @see update_subtype()
*/
function remove_subtype($type, $subtype) {
global $CONFIG;
}
/**
- * Update the registered information
+ * Update a registered ElggEntity type, subtype, and classname
*
* @param string $type
* @param string $subtype
");
}
-
/**
- * Update an existing entity.
+ * 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
* @param int $owner_guid
* @param int $access_id
* @param int $container_guid
+ * @return bool
+ * @link http://docs.elgg.org/DataModel/Entities
+ * @access private
*/
function update_entity($guid, $owner_guid, $access_id, $container_guid = null) {
global $CONFIG, $ENTITY_CACHE;
$entity = get_entity($guid);
if ($entity->canEdit()) {
- if (trigger_elgg_event('update',$entity->type,$entity)) {
+ if (trigger_elgg_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_updated='$time' WHERE guid=$guid");
if ($entity instanceof ElggObject) {
}
/**
- * Determine whether a given user is able to write to a given container.
+ * Determine if a given user is 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 get_loggedin_userid()
* @param int $container_guid The container, or 0 for the current page owner.
+ * @return bool
+ * @link http://docs.elgg.org/DataModel/Containers
*/
function can_write_to_container($user_guid = 0, $container_guid = 0, $entity_type = 'all') {
global $CONFIG;
}
// Basics, see if the user is a member of the group.
+ // @todo this should be moved to the groups plugin
if ($user && $container instanceof ElggGroup) {
if (!$container->isMember($user)) {
$return = FALSE;
}
/**
- * Create a new entity of a given type.
+ * 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).
+ * @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. Leave as 0 (default) for the current site.
- * @return mixed The new entity's GUID, or false on failure
+ * @return int|false The new entity's GUID, or false on failure
+ * @throws InvalidParameterException
+ * @access private
+ * @link http://docs.elgg.org/DataModel/Entities
*/
function create_entity($type, $subtype, $owner_guid, $access_id, $site_guid = 0, $container_guid = 0) {
global $CONFIG;
}
/**
- * Retrieve the entity details for a specific GUID, returning it as a stdClass db row.
+ * Returns a database row from the entities table.
*
- * You will only get an object if a) it exists, b) you have access to it.
+ * @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;
/**
* Create an Elgg* object from a given entity row.
+ *
+ * Handles loading all tables into the correct class.
+ *
+ * @param stdClass The row of the entry in the entities table.
+ * @return object|false
+ * @link http://docs.elgg.org/DataModel/Entities
+ * @see get_entity_as_row()
+ * @see add_subtype()
+ * @see get_entity()
+ * @access private
*/
function entity_row_to_elggstar($row) {
if (!($row instanceof stdClass)) {
}
/**
- * Return the entity for a given guid as the correct object.
+ * Loads and returns an entity object from a guid.
+ *
* @param int $guid The GUID of the entity
- * @return a child of ElggEntity appropriate for the type.
+ * @return object The correct Elgg or custom object based upon entity type and subtype
+ * @link http://docs.elgg.org/DataModel/Entities
*/
function get_entity($guid) {
static $newentity_cache;
/**
- * Get all entities. NB: Plural arguments can be written as
- * singular if only specifying a single element. (e.g., 'type' => 'object'
- * vs 'types' => array('object')).
+ * 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:
*
*
* joins => array() Additional joins
*
- * @return if count, int
- * if not count, array or false if no entities
+ * @return mixed int if count is true, an array of entity objects, or false on failure
* @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;
}
/**
- * Returns type and subtype SQL appropriate for inclusion in an IN clause.
+ * Returns SQL where clause for type and subtype on main entity table
*
- * @param string $table entity table prefix.
+ * @param string $table entity table prefix as defined in SELECT ... FROM prefix_entities $table
* @param NULL|$types
* @param NULL|array $subtypes
* @param NULL|array $pairs
* @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.
return '';
}
-
-
/**
- * Returns SQL for owner and containers.
+ * Returns SQL where clause for owner and containers.
*
* @todo Probably DRY up once things are settled.
- * @param str $table
+ * @param string $table entity table prefix as defined in SELECT ... FROM prefix_entities $table
* @param NULL|array $owner_guids
* @return FALSE|str
* @since 1.7.0
+ * @access private
*/
function elgg_get_entity_owner_where_sql($table, $owner_guids) {
// short circuit if nothing requested
}
/**
- * Returns SQL for containers.
+ * Returns SQL where clause for containers.
*
- * @param string $table entity table prefix
+ * @param string $table entity table prefix as defined in SELECT ... FROM prefix_entities $table
* @param NULL|array $container_guids
* @return FALSE|string
* @since 1.7.0
+ * @access private
*/
function elgg_get_entity_container_where_sql($table, $container_guids) {
// short circuit if nothing is requested.
/**
* Returns SQL where clause for entity time limits.
*
- * @param string $table Prefix for entity table name.
+ * @param string $table entity table prefix as defined in SELECT ... FROM prefix_entities $table
* @param NULL|int $time_created_upper
* @param NULL|int $time_created_lower
* @param NULL|int $time_updated_upper
* @param NULL|int $time_updated_lower
- *
* @return FALSE|str 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) {
}
/**
- * Gets SQL for site entities
+ * Returns SQL where clause for site entities
*
- * @param string $table entity table name
+ * @param string $table entity table prefix as defined in SELECT ... FROM prefix_entities $table
* @param NULL|array $site_guids
* @return FALSE|string
* @since 1.7.0
+ * @access private
*/
function elgg_get_entity_site_where_sql($table, $site_guids) {
// short circuit if nothing requested
}
/**
- * Returns a viewable list of entities
+ * Returns a string of parsed entities.
*
- * @see elgg_view_entity_list
+ * Displays list of entities with formatting specified
+ * by the entity view.
+ *
+ * @tip Pagination is handled automatically.
*
* @param array $options Any elgg_get_entity() options plus:
*
*
* @return str
* @since 1.7.0
+ * @see elgg_view_entity_list()
+ * @see elgg_get_entities()
+ * @link http://docs.elgg.org/Entities/Output
*/
function elgg_list_entities($options) {
$defaults = array(
}
/**
- * Returns a viewable list of entities contained in a number of groups.
+ * Lists entities that belong to a group.
+ *
+ * @warning This function is largely redundant. The preferred
+ * method of listing group entities is by setting the container
+ * guid option in {@link elgg_list_entities()}.
*
* @param string $subtype The arbitrary subtype of the entity
* @param int $owner_guid The GUID of the owning user
* @param true|false $fullview Whether or not to display the full view (default: true)
* @param true|false $viewtypetoggle Whether or not to allow gallery view (default: true)
* @param true|false $pagination Whether to display pagination (default: true)
- * @return string A viewable list of entities
+ * @return string List of parsed entities
+ * @see elgg_list_entities()
*/
function list_entities_groups($subtype = "", $owner_guid = 0, $container_guid = 0, $limit = 10, $fullview = true, $viewtypetoggle = true, $pagination = true) {
$offset = (int) get_input('offset');
}
/**
- * Returns a list of months containing content specified by the parameters
+ * 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 str order_by SQL order by clause
- * @return array|false Either an array of timestamps, or false on failure
+ * @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;
}
/**
- * Disable an entity but not delete it.
+ * 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
+ * @access private
+ * @see access_show_hidden_entities()
+ * @link http://docs.elgg.org/Entities
*/
function disable_entity($guid, $reason = "", $recursive = true) {
global $CONFIG;
}
/**
- * Enable an entity again.
+ * 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
+ * @return bool
*/
function enable_entity($guid) {
global $CONFIG;
}
/**
- * Delete a given entity.
+ * 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
* @param bool $recursive If true (default) then all entities which are owned or contained by $guid will also be deleted.
- * Note: this bypasses ownership of sub items.
+ * @access private
*/
function delete_entity($guid, $recursive = true) {
global $CONFIG, $ENTITY_CACHE;
/**
* Delete multiple entities that match a given query.
- * This function itterates through and calls delete_entity on each one, this is somewhat inefficient but lets
+ * This function iterates through and calls delete_entity on each one, this is somewhat inefficient but lets
* the 'delete' even be called for each entity.
*
* @deprecated 1.7. This is a dangerous function as it defaults to deleting everything.
}
/**
- * A plugin hook to get certain volitile (generated on the fly) attributes about an entity in order to export them.
+ * Exports attributes generated on the fly (volatile) about an entity.
*
* @param unknown_type $hook
* @param unknown_type $entity_type
* @param unknown_type $returnvalue
* @param unknown_type $params The parameters, passed 'guid' and 'varname'
- * @return unknown
+ * @return 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'];
}
/**
- * Handler called by trigger_plugin_hook on the "export" event.
+ * Exports all attributes of an entity.
+ *
+ * @warning Only exports fields in the entity and entity type tables.
+ *
+ * @elgg_event_handler export all
+ * @todo document
*/
function export_entity_plugin_hook($hook, $entity_type, $returnvalue, $params) {
// Sanity check values
*
* @param ODDEntity $element The OpenDD element
* @return ElggEntity the unsaved entity which should be populated by items.
+ * @todo Remove this.
*/
function oddentity_to_elggentity(ODDEntity $element) {
$class = $element->getAttribute('class');
/**
* 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.
+ *
+ * @elgg_plugin_hook_handler import all
+ * @todo document
*/
function import_entity_plugin_hook($hook, $entity_type, $returnvalue, $params) {
$element = $params['element'];
}
/**
- * Determines whether or not the specified user can edit the specified entity.
+ * Returns if $user_guid is able to edit $entity_guid.
+ *
+ * @tip Can be overridden by by registering for the permissions_check
+ * plugin hook.
*
- * This is extendible by registering a plugin hook taking in the parameters 'entity' and 'user',
- * which are the entity and user entities respectively
+ * @warning If a $user_guid is not passed it will default to the logged in user.
*
- * @see register_plugin_hook
+ * @tip Use ElggEntity::canEdit() instead.
*
* @param int $entity_guid The GUID of the entity
* @param int $user_guid The GUID of the user
- * @return true|false Whether the specified user can edit the specified entity.
+ * @return bool
+ * @link http://docs.elgg.org/Entities/AccessControl
*/
function can_edit_entity($entity_guid, $user_guid = 0) {
global $CONFIG;
}
/**
- * Determines whether or not the specified user can edit metadata on the specified entity.
+ * Returns if $user_guid can edit the metadata on $entity_guid.
*
- * This is extendible by registering a plugin hook taking in the parameters 'entity' and 'user',
- * which are the entity and user entities respectively
+ * @tip Can be overridden by by registering for the permissions_check:metadata
+ * plugin hook.
*
- * @see register_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 true|false Whether the specified user can edit the specified entity.
+ * @return bool
+ * @see register_plugin_hook()
*/
function can_edit_entity_metadata($entity_guid, $user_guid = 0, $metadata = null) {
if ($entity = get_entity($entity_guid)) {
}
}
-
/**
- * Get the icon for an entity
+ * Return the icon URL for an entity.
+ *
+ * @tip Can be overridden by registering a plugin hook for entity:icon:url OR
+ * with {@link register_
+ *
+ * @internal This is passed an entity rather than a guid to handle non-created entities.
*
- * @param ElggEntity $entity The entity (passed an entity rather than a guid to handle non-created entities)
+ * @param ElggEntity $entity The entity
* @param string $size
+ * @return string URL to the entity icon.
*/
function get_entity_icon_url(ElggEntity $entity, $size = 'medium') {
global $CONFIG;
}
/**
- * Gets the URL for an entity, given a particular GUID
+ * 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;
* @param string $entity_type The entity type
* @param string $entity_subtype The entity subtype
* @return true|false Depending on success
+ * @see get_entity_url()
+ * @see ElggEntity::getURL()
*/
function register_entity_url_handler($function_name, $entity_type = "all", $entity_subtype = "all") {
global $CONFIG;
}
/**
- * Default Icon URL handler for entities.
- * This will attempt to find a default entity for the current view and return a url. This is registered at
- * a low priority so that other handlers will pick it up first.
+ * Default Icon handler for entities.
+ *
+ * @tip This will attempt to find a default entity for the current view and return a url.
+ * This is registered at a high priority so that other handlers will pick it up first.
*
* @param unknown_type $hook
* @param unknown_type $entity_type
* @param unknown_type $returnvalue
* @param unknown_type $params
+ * @elgg_plugin_hook_handler entity:icon:url all
*/
function default_entity_icon_hook($hook, $entity_type, $returnvalue, $params) {
global $CONFIG;
}
/**
- * Registers and entity type and subtype to return in search and other places.
- * A description in the elgg_echo languages file of the form item:type:subtype
- * is also expected.
+ * 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 true|false Depending on success
+ * @see get_registered_entity_types()
+ * @link http://docs.elgg.org/Search
+ * @link http://docs.elgg.org/Tutorials/Search
*/
function register_entity_type($type, $subtype) {
global $CONFIG;
/**
* Returns registered entity types and subtypes
*
- * @see register_entity_type
- *
* @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 register_entity_type()
*/
function get_registered_entity_types($type = '') {
global $CONFIG;
}
/**
- * Determines whether or not the specified entity type and subtype have been registered in the system
+ * Returns if the entity type and subtype have been registered with {@see register_entity_type()}.
*
* @param string $type The type of entity (object, site, user, group)
* @param string $subtype The subtype (may be blank)
if (in_array($subtype, $CONFIG->registered_entities[$type])) {
return true;
}
-
}
/**
* Page handler for generic entities view system
*
* @param array $page Page elements from pain page handler
+ * @elgg_page_handler view
*/
function entities_page_handler($page) {
if (isset($page[0])) {
}
/**
- * Get entities based on their private data, in a similar way to metadata.
+ * Get entities based on their private data.
*
* @param string $name The name of the setting
* @param string $value The value of the setting
* @param int $site_guid The site to get entities for. Leave as 0 (default) for the current site; -1 for all sites.
* @param int|array $container_guid The container or containers to get entities from (default: all containers).
* @return array A list of entities.
+ * @todo deprecate
*/
function get_entities_from_private_setting($name = "", $value = "", $type = "", $subtype = "", $owner_guid = 0, $order_by = "", $limit = 10, $offset = 0, $count = false, $site_guid = 0, $container_guid = null) {
global $CONFIG;
}
/**
- * Get entities based on their private data by multiple keys, in a similar way to metadata.
+ * Get entities based on their private data by multiple keys.
*
* @param string $name The name of the setting
* @param string $value The value of the setting
* @param int $site_guid The site to get entities for. Leave as 0 (default) for the current site; -1 for all sites.
* @param int|array $container_guid The container or containers to get entities from (default: all containers).
* @return array A list of entities.
+ * @todo deprecate
*/
function get_entities_from_private_setting_multi(array $name, $type = "", $subtype = "", $owner_guid = 0, $order_by = "", $limit = 10, $offset = 0, $count = false, $site_guid = 0, $container_guid = null) {
global $CONFIG;
/**
* Gets a private setting for an entity.
*
+ * Plugin authors can set private data on entities. By default
+ * private data will not be searched or exported.
+ *
+ * @internal Private data is used to store settings for plugins
+ * and user settings.
+ *
* @param int $entity_guid The entity GUID
* @param string $name The name of the setting
* @return mixed The setting value, or false on failure
+ * @see set_private_setting()
+ * @see get_all_private_settings()
+ * @see remove_private_setting()
+ * @see remove_all_private_settings()
+ * @link http://docs.elgg.org/DataModel/Entities/PrivateSettings
*/
function get_private_setting($entity_guid, $name) {
global $CONFIG;
}
/**
- * Return an array of all private settings for a given
+ * Return an array of all private settings.
*
* @param int $entity_guid The entity GUID
+ * @return array|false
+ * @see set_private_setting()
+ * @see get_private_settings()
+ * @see remove_private_setting()
+ * @see remove_all_private_settings()
+ * @link http://docs.elgg.org/DataModel/Entities/PrivateSettings
*/
function get_all_private_settings($entity_guid) {
global $CONFIG;
* @param string $name The name of the setting
* @param string $value The value of the setting
* @return mixed The setting ID, or false on failure
+ * @see get_private_setting()
+ * @see get_all_private_settings()
+ * @see remove_private_setting()
+ * @see remove_all_private_settings()
+ * @link http://docs.elgg.org/DataModel/Entities/PrivateSettings
*/
function set_private_setting($entity_guid, $name, $value) {
global $CONFIG;
* @param int $entity_guid The Entity GUID
* @param string $name The name of the setting
* @return true|false depending on success
- *
+ * @see get_private_setting()
+ * @see get_all_private_settings()
+ * @see set_private_setting()
+ * @see remove_all_private_settings()
+ * @link http://docs.elgg.org/DataModel/Entities/PrivateSettings
*/
function remove_private_setting($entity_guid, $name) {
global $CONFIG;
*
* @param int $entity_guid The Entity GUID
* @return true|false depending on success
- *
+ * @see get_private_setting()
+ * @see get_all_private_settings()
+ * @see set_private_setting()
+ * @see remove_private_settings()
+ * @link http://docs.elgg.org/DataModel/Entities/PrivateSettings
*/
function remove_all_private_settings($entity_guid) {
global $CONFIG;
}
/*
- * Check the recurisve delete permissions token.
+ * Check the recursive delete permissions token.
*
+ * If an entity is deleted recursively, a permissions override is required to allow
+ * contained or owned entities to be removed.
+ *
+ * @access private
* @return bool
+ * @elgg_plugin_hook_handler permissions_check all
+ * @elgg_plugin_hook_handler permissions_check:metadata all
*/
function recursive_delete_permissions_check($hook, $entity_type, $returnvalue, $params) {
static $__RECURSIVE_DELETE_TOKEN;
/**
* 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 $entity
* @param $type
* @param $subtype
if ($subtype) {
$return = $return && ($entity->getSubtype() == $subtype);
}
-
+
if ($class) {
$return = $return && ($entity instanceof $class);
}
/**
- * Update last_action on the given entity.
+ * Update the last_action column in the entities table for $guid.
+ *
+ * This determines the sort order of 1.8's default river.
+ *
+ * @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
* @param unknown_type $user
* @param unknown_type $returnvalue
* @param unknown_type $tag
+ * @elgg_plugin_hook_handler gc system
*/
function entities_gc($hook, $user, $returnvalue, $tag) {
global $CONFIG;
}
/**
- * Runs unit tests for the entities object.
+ * Runs unit tests for the entity objects.
+ *
+ * @elgg_plugin_hook_handler unit_test system
*/
function entities_test($hook, $type, $value, $params) {
global $CONFIG;
}
/**
- * Entities init function; establishes the page handler
+ * Entities init function; establishes the default entity page handler
*
+ * @elgg_event_handler init system
*/
function entities_init() {
register_page_handler('view','entities_page_handler');
register_plugin_hook('entity:icon:url', 'all', 'default_entity_icon_hook', 1000);
/** Register init system event **/
-register_elgg_event_handler('init','system','entities_init');
+register_elgg_event_handler('init', 'system', 'entities_init');
\ No newline at end of file
projects / lorea / elgg.git / commitdiff