ElggEntity.php

Go to the documentation of this file.

<?php
abstract class ElggEntity extends \ElggData implements
    Notable,   // Calendar interface (deprecated 1.9)
    Locatable, // Geocoding interface
    Importable // Allow import of data (deprecated 1.9)
{
 
    protected $url_override;
 
    protected $icon_override;
 
    protected $temp_metadata = array();
 
    protected $temp_annotations = array();
 
    protected $temp_private_settings = array();
 
    protected $volatile = array();
    
    protected $tables_split;
    
    protected $tables_loaded;
    
    protected function initializeAttributes() {
        parent::initializeAttributes();
 
        $this->attributes['guid'] = null;
        $this->attributes['type'] = null;
        $this->attributes['subtype'] = null;
 
        $this->attributes['owner_guid'] = _elgg_services()->session->getLoggedInUserGuid();
        $this->attributes['container_guid'] = _elgg_services()->session->getLoggedInUserGuid();
 
        $this->attributes['site_guid'] = null;
        $this->attributes['access_id'] = ACCESS_PRIVATE;
        $this->attributes['time_updated'] = null;
        $this->attributes['last_action'] = null;
        $this->attributes['enabled'] = "yes";
 
        // There now follows a bit of a hack
        /* Problem: To speed things up, some objects are split over several tables,
         * this means that it requires n number of database reads to fully populate
         * an entity. This causes problems for caching and create events
         * since it is not possible to tell whether a subclassed entity is complete.
         *
         * Solution: We have two counters, one 'tables_split' which tells whatever is
         * interested how many tables are going to need to be searched in order to fully
         * populate this object, and 'tables_loaded' which is how many have been
         * loaded thus far.
         *
         * If the two are the same then this object is complete.
         *
         * Use: isFullyLoaded() to check
         */
        $this->tables_split = 1;
        $this->tables_loaded = 0;
    }
 
    public function __clone() {
        $orig_entity = get_entity($this->guid);
        if (!$orig_entity) {
            _elgg_services()->logger->error("Failed to clone entity with GUID $this->guid");
            return;
        }
 
        $metadata_array = elgg_get_metadata(array(
            'guid' => $this->guid,
            'limit' => 0
        ));
 
        $this->attributes['guid'] = "";
 
        $this->attributes['subtype'] = $orig_entity->getSubtype();
 
        // copy metadata over to new entity - slightly convoluted due to
        // handling of metadata arrays
        if (is_array($metadata_array)) {
            // create list of metadata names
            $metadata_names = array();
            foreach ($metadata_array as $metadata) {
                $metadata_names[] = $metadata['name'];
            }
            // arrays are stored with multiple enties per name
            $metadata_names = array_unique($metadata_names);
 
            // move the metadata over
            foreach ($metadata_names as $name) {
                $this->__set($name, $orig_entity->$name);
            }
        }
    }
 
    public function __set($name, $value) {
        if (array_key_exists($name, $this->attributes)) {
            // Certain properties should not be manually changed!
            switch ($name) {
                case 'guid':
                case 'time_updated':
                case 'last_action':
                    return;
                    break;
                case 'access_id':
                case 'owner_guid':
                case 'container_guid':
                    if ($value !== null) {
                        $this->attributes[$name] = (int)$value;
                    } else {
                        $this->attributes[$name] = null;
                    }
                    break;
                default:
                    $this->attributes[$name] = $value;
                    break;
            }
        } else {
            $this->setMetadata($name, $value);
        }
    }
 
    public function set($name, $value) {
        elgg_deprecated_notice("Use -> instead of set()", 1.9);
        $this->__set($name, $value);
 
        return true;
    }
 
    public function __get($name) {
        if (array_key_exists($name, $this->attributes)) {
            if ($name === 'subtype' && $this->attributes['guid']) {
                // note: only show deprecation notice if user reads ->subtype after save/load
                elgg_deprecated_notice("Use getSubtype()", 1.9);
            }
            return $this->attributes[$name];
        }
 
        return $this->getMetadata($name);
    }
 
    public function get($name) {
        elgg_deprecated_notice("Use -> instead of get()", 1.9);
        return $this->__get($name);
    }
 
    abstract public function getDisplayName();
 
    abstract public function setDisplayName($displayName);
 
    public function getMetadata($name) {
        $guid = $this->getGUID();
 
        if (!$guid) {
            if (isset($this->temp_metadata[$name])) {
                // md is returned as an array only if more than 1 entry
                if (count($this->temp_metadata[$name]) == 1) {
                    return $this->temp_metadata[$name][0];
                } else {
                    return $this->temp_metadata[$name];
                }
            } else {
                return null;
            }
        }
 
        // upon first cache miss, just load/cache all the metadata and retry.
        // if this works, the rest of this function may not be needed!
        $cache = _elgg_services()->metadataCache;
        if ($cache->isLoaded($guid)) {
            return $cache->getSingle($guid, $name);
        } else {
            $cache->populateFromEntities(array($guid));
            // in case ignore_access was on, we have to check again...
            if ($cache->isLoaded($guid)) {
                return $cache->getSingle($guid, $name);
            }
        }
 
        $md = elgg_get_metadata(array(
            'guid' => $guid,
            'metadata_name' => $name,
            'limit' => 0,
            'distinct' => false,
        ));
 
        $value = null;
 
        if ($md && !is_array($md)) {
            $value = $md->value;
        } elseif (count($md) == 1) {
            $value = $md[0]->value;
        } else if ($md && is_array($md)) {
            $value = metadata_array_to_values($md);
        }
 
        return $value;
    }
 
    public function __unset($name) {
        if (array_key_exists($name, $this->attributes)) {
            $this->attributes[$name] = "";
        } else {
            $this->deleteMetadata($name);
        }
    }
 
    public function setMetadata($name, $value, $value_type = '', $multiple = false, $owner_guid = 0, $access_id = null) {
 
        // normalize value to an array that we will loop over
        // remove indexes if value already an array.
        if (is_array($value)) {
            $value = array_values($value);
        } else {
            $value = array($value);
        }
 
        // saved entity. persist md to db.
        if ($this->guid) {
            // if overwriting, delete first.
            if (!$multiple) {
                $options = array(
                    'guid' => $this->getGUID(),
                    'metadata_name' => $name,
                    'limit' => 0
                );
                // @todo in 1.9 make this return false if can't add metadata
                // https://github.com/elgg/elgg/issues/4520
                //
                // need to remove access restrictions right now to delete
                // because this is the expected behavior
                $ia = elgg_set_ignore_access(true);
                if (false === elgg_delete_metadata($options)) {
                    return false;
                }
                elgg_set_ignore_access($ia);
            }
 
            $owner_guid = (int)$owner_guid;
            $access_id = ($access_id === null) ? $this->getAccessId() : (int)$access_id;
            $owner_guid = $owner_guid ? $owner_guid : $this->getOwnerGUID();
 
            // add new md
            $result = true;
            foreach ($value as $value_tmp) {
                // at this point $value is appended because it was cleared above if needed.
                $md_id = create_metadata($this->getGUID(), $name, $value_tmp, $value_type,
                        $owner_guid, $access_id, true);
                if (!$md_id) {
                    return false;
                }
            }
 
            return $result;
        } else {
            // unsaved entity. store in temp array
 
            // returning single entries instead of an array of 1 element is decided in
            // getMetaData(), just like pulling from the db.
 
            if ($owner_guid != 0 || $access_id !== null) {
                $msg = "owner guid and access id cannot be used in \ElggEntity::setMetadata() until entity is saved.";
                throw new \InvalidArgumentException($msg);
            }
 
            // if overwrite, delete first
            if (!$multiple || !isset($this->temp_metadata[$name])) {
                $this->temp_metadata[$name] = array();
            }
 
            // add new md
            $this->temp_metadata[$name] = array_merge($this->temp_metadata[$name], $value);
            return true;
        }
    }
 
    public function deleteMetadata($name = null) {
 
        if (!$this->guid) {
            return false;
        }
 
        $options = array(
            'guid' => $this->guid,
            'limit' => 0
        );
        if ($name) {
            $options['metadata_name'] = $name;
        }
 
        return elgg_delete_metadata($options);
    }
 
    public function deleteOwnedMetadata($name = null) {
        // access is turned off for this because they might
        // no longer have access to an entity they created metadata on.
        $ia = elgg_set_ignore_access(true);
        $options = array(
            'metadata_owner_guid' => $this->guid,
            'limit' => 0
        );
        if ($name) {
            $options['metadata_name'] = $name;
        }
 
        $r = elgg_delete_metadata($options);
        elgg_set_ignore_access($ia);
        return $r;
    }
 
    public function clearMetadata($name = '') {
        elgg_deprecated_notice('\ElggEntity->clearMetadata() is deprecated by ->deleteMetadata()', 1.8);
        return $this->deleteMetadata($name);
    }
 
    public function disableMetadata($name = '') {
        $options = array(
            'guid' => $this->guid,
            'limit' => 0
        );
        if ($name) {
            $options['metadata_name'] = $name;
        }
 
        return elgg_disable_metadata($options);
    }
 
    public function enableMetadata($name = '') {
        $options = array(
            'guid' => $this->guid,
            'limit' => 0
        );
        if ($name) {
            $options['metadata_name'] = $name;
        }
 
        return elgg_enable_metadata($options);
    }
 
    public function getVolatileData($name) {
        if (!is_array($this->volatile)) {
            $this->volatile = array();
        }
 
        if (array_key_exists($name, $this->volatile)) {
            return $this->volatile[$name];
        } else {
            return null;
        }
    }
 
    public function setVolatileData($name, $value) {
        if (!is_array($this->volatile)) {
            $this->volatile = array();
        }
 
        $this->volatile[$name] = $value;
    }
 
    public function deleteRelationships($relationship = null) {
        $relationship = (string)$relationship;
        $result = remove_entity_relationships($this->getGUID(), $relationship);
        return $result && remove_entity_relationships($this->getGUID(), $relationship, true);
    }
 
    public function clearRelationships() {
        elgg_deprecated_notice('\ElggEntity->clearRelationships() is deprecated by ->deleteRelationships()', 1.8);
        return $this->deleteRelationships();
    }
 
    public function addRelationship($guid_two, $relationship) {
        return add_entity_relationship($this->getGUID(), $relationship, $guid_two);
    }
 
    public function removeRelationship($guid_two, $relationship) {
        return remove_entity_relationship($this->getGUID(), $relationship, $guid_two);
    }
 
    public function setPrivateSetting($name, $value) {
        if ((int) $this->guid > 0) {
            return set_private_setting($this->getGUID(), $name, $value);
        } else {
            $this->temp_private_settings[$name] = $value;
            return true;
        }
    }
 
    public function getPrivateSetting($name) {
        if ((int) ($this->guid) > 0) {
            return get_private_setting($this->getGUID(), $name);
        } else {
            if (isset($this->temp_private_settings[$name])) {
                return $this->temp_private_settings[$name];
            }
        }
        return null;
    }
 
    public function removePrivateSetting($name) {
        return remove_private_setting($this->getGUID(), $name);
    }
 
    public function deleteAnnotations($name = null) {
        $options = array(
            'guid' => $this->guid,
            'limit' => 0
        );
        if ($name) {
            $options['annotation_name'] = $name;
        }
 
        return elgg_delete_annotations($options);
    }
 
    public function deleteOwnedAnnotations($name = null) {
        // access is turned off for this because they might
        // no longer have access to an entity they created annotations on.
        $ia = elgg_set_ignore_access(true);
        $options = array(
            'annotation_owner_guid' => $this->guid,
            'limit' => 0
        );
        if ($name) {
            $options['annotation_name'] = $name;
        }
 
        $r = elgg_delete_annotations($options);
        elgg_set_ignore_access($ia);
        return $r;
    }
 
    public function disableAnnotations($name = '') {
        $options = array(
            'guid' => $this->guid,
            'limit' => 0
        );
        if ($name) {
            $options['annotation_name'] = $name;
        }
 
        return elgg_disable_annotations($options);
    }
 
    public function enableAnnotations($name = '') {
        $options = array(
            'guid' => $this->guid,
            'limit' => 0
        );
        if ($name) {
            $options['annotation_name'] = $name;
        }
 
        return elgg_enable_annotations($options);
    }
 
    private function getAnnotationCalculation($name, $calculation) {
        $options = array(
            'guid' => $this->getGUID(),
            'distinct' => false,
            'annotation_name' => $name,
            'annotation_calculation' => $calculation
        );
 
        return elgg_get_annotations($options);
    }
 
    public function annotate($name, $value, $access_id = ACCESS_PRIVATE, $owner_guid = 0, $vartype = "") {
        if ((int) $this->guid > 0) {
            return create_annotation($this->getGUID(), $name, $value, $vartype, $owner_guid, $access_id);
        } else {
            $this->temp_annotations[$name] = $value;
        }
        return true;
    }
 
    public function getAnnotations($options = array(), $limit = 50, $offset = 0, $order = "asc") {
        if (!is_array($options)) {
            elgg_deprecated_notice("\ElggEntity::getAnnotations() takes an array of options.", 1.9);
        }
 
        if ((int) ($this->guid) > 0) {
            if (!is_array($options)) {
                $options = array(
                    'guid' => $this->guid,
                    'annotation_name' => $options,
                    'limit' => $limit,
                    'offset' => $offset,
                );
 
                if ($order != 'asc') {
                    $options['reverse_order_by'] = true;
                }
            } else {
                $options['guid'] = $this->guid;
            }
 
            return elgg_get_annotations($options);
        } else {
            if (!is_array($options)) {
                $name = $options;
            } else {
                $name = elgg_extract('annotation_name', $options, '');
            }
 
            if (isset($this->temp_annotations[$name])) {
                return array($this->temp_annotations[$name]);
            }
        }
 
        return array();
    }
 
    public function clearAnnotations($name = "") {
        elgg_deprecated_notice('\ElggEntity->clearAnnotations() is deprecated by ->deleteAnnotations()', 1.8);
        return $this->deleteAnnotations($name);
    }
 
    public function countAnnotations($name = "") {
        return $this->getAnnotationCalculation($name, 'count');
    }
 
    public function getAnnotationsAvg($name) {
        return $this->getAnnotationCalculation($name, 'avg');
    }
 
    public function getAnnotationsSum($name) {
        return $this->getAnnotationCalculation($name, 'sum');
    }
 
    public function getAnnotationsMin($name) {
        return $this->getAnnotationCalculation($name, 'min');
    }
 
    public function getAnnotationsMax($name) {
        return $this->getAnnotationCalculation($name, 'max');
    }
 
    public function countComments() {
        $params = array('entity' => $this);
        $num = _elgg_services()->hooks->trigger('comments:count', $this->getType(), $params);
 
        if (is_int($num)) {
            return $num;
        } else {
            return elgg_get_entities(array(
                'type' => 'object',
                'subtype' => 'comment',
                'container_guid' => $this->getGUID(),
                'count' => true,
                'distinct' => false,
            ));
        }
    }
 
    public function getEntitiesFromRelationship($options = array(), $inverse = false, $limit = 50, $offset = 0) {
        if (is_array($options)) {
            $options['relationship_guid'] = $this->getGUID();
            return elgg_get_entities_from_relationship($options);
        } else {
            elgg_deprecated_notice("\ElggEntity::getEntitiesFromRelationship takes an options array", 1.9);
            return elgg_get_entities_from_relationship(array(
                'relationship' => $options,
                'relationship_guid' => $this->getGUID(),
                'inverse_relationship' => $inverse,
                'limit' => $limit,
                'offset' => $offset
            ));
        }
    }
 
    public function countEntitiesFromRelationship($relationship, $inverse_relationship = false) {
        return elgg_get_entities_from_relationship(array(
            'relationship' => $relationship,
            'relationship_guid' => $this->getGUID(),
            'inverse_relationship' => $inverse_relationship,
            'count' => true
        ));
    }
 
    public function canEdit($user_guid = 0) {
        $user_guid = (int)$user_guid;
        $user = get_entity($user_guid);
        if (!$user) {
            $user = _elgg_services()->session->getLoggedInUser();
        }
 
        $return = false;
 
        // Test user if possible - should default to false unless a plugin hook says otherwise
        if ($user) {
            if ($this->getOwnerGUID() == $user->getGUID()) {
                $return = true;
            }
            
            if ($this->getContainerGUID() == $user->getGUID()) {
                $return = true;
            }
            
            if ($this->getGUID() == $user->getGUID()) {
                $return = true;
            }
 
            $container = $this->getContainerEntity();
            if ($container && $container->canEdit($user->getGUID())) {
                $return = true;
            }
        }
 
        $params = array('entity' => $this, 'user' => $user);
        return _elgg_services()->hooks->trigger('permissions_check', $this->type, $params, $return);
    }
 
    public function canDelete($user_guid = 0) {
        $user_guid = (int) $user_guid;
 
        if (!$user_guid) {
            $user_guid = _elgg_services()->session->getLoggedInUserGuid();
        }
 
        // need to ignore access and show hidden entities for potential hidden/disabled users
        $ia = elgg_set_ignore_access(true);
        $show_hidden = access_show_hidden_entities(true);
        
        $user = _elgg_services()->entityTable->get($user_guid, 'user');
        
        elgg_set_ignore_access($ia);
        access_show_hidden_entities($show_hidden);
        
        if ($user_guid & !$user) {
            // requested to check access for a specific user_guid, but there is no user entity, so return false
            $message = _elgg_services()->translator->translate('entity:can_delete:invaliduser', array($user_guid));
            _elgg_services()->logger->warning($message);
            
            return false;
        }       
        
        $return = $this->canEdit($user_guid);
 
        $params = array('entity' => $this, 'user' => $user);
        return _elgg_services()->hooks->trigger('permissions_check:delete', $this->type, $params, $return);
    }
 
    public function canEditMetadata($metadata = null, $user_guid = 0) {
        if (!$this->guid) {
            // @todo cannot edit metadata on unsaved entity?
            return false;
        }
 
        if ($user_guid) {
            $user = get_user($user_guid);
            if (!$user) {
                return false;
            }
        } else {
            $user = _elgg_services()->session->getLoggedInUser();
            $user_guid = $user->guid;
        }
 
        $return = null;
 
        // if metadata is not owned or owned by the user, then can edit
        if ($metadata && ($metadata->owner_guid == 0 || $metadata->owner_guid == $user_guid)) {
            $return = true;
        }
 
        if (is_null($return)) {
            $return = $this->canEdit($user_guid);
        }
 
        // metadata and user may be null
        $params = array('entity' => $this, 'user' => $user, 'metadata' => $metadata);
        return _elgg_services()->hooks->trigger('permissions_check:metadata', $this->type, $params, $return);
    }
 
    public function canWriteToContainer($user_guid = 0, $type = 'all', $subtype = 'all') {
        return can_write_to_container($user_guid, $this->guid, $type, $subtype);
    }
 
    public function canComment($user_guid = 0) {
        if ($user_guid == 0) {
            $user_guid = _elgg_services()->session->getLoggedInUserGuid();
        }
        $user = get_entity($user_guid);
 
        // By default, we don't take a position of whether commenting is allowed
        // because it is handled by the subclasses of \ElggEntity
        $params = array('entity' => $this, 'user' => $user);
        return _elgg_services()->hooks->trigger('permissions_check:comment', $this->type, $params, null);
    }
 
    public function canAnnotate($user_guid = 0, $annotation_name = '') {
        if ($user_guid == 0) {
            $user_guid = _elgg_services()->session->getLoggedInUserGuid();
        }
        $user = get_entity($user_guid);
 
        $return = true;
        if (!$user) {
            $return = false;
        }
 
        $params = array(
            'entity' => $this,
            'user' => $user,
            'annotation_name' => $annotation_name,
        );
        return _elgg_services()->hooks->trigger('permissions_check:annotate', $this->type, $params, $return);
    }
 
    public function getAccessID() {
        return $this->access_id;
    }
 
    public function getGUID() {
        return $this->guid;
    }
 
    public function getType() {
        return $this->type;
    }
 
    public function getSubtype() {
        // If this object hasn't been saved, then return the subtype string.
        if ($this->attributes['guid']) {
            return get_subtype_from_id($this->attributes['subtype']);
        }
        return $this->attributes['subtype'];
    }
 
    public function getOwnerGUID() {
        return (int)$this->owner_guid;
    }
 
    public function getOwner() {
        elgg_deprecated_notice("\ElggEntity::getOwner deprecated for \ElggEntity::getOwnerGUID", 1.8);
        return $this->getOwnerGUID();
    }
 
    public function getOwnerEntity() {
        return get_entity($this->owner_guid);
    }
 
    public function setContainerGUID($container_guid) {
        return $this->container_guid = (int)$container_guid;
    }
 
    public function setContainer($container_guid) {
        elgg_deprecated_notice("\ElggObject::setContainer deprecated for \ElggEntity::setContainerGUID", 1.8);
        return $this->setContainerGUID('container_guid', $container_guid);
    }
 
    public function getContainerGUID() {
        return (int)$this->container_guid;
    }
 
    public function getContainer() {
        elgg_deprecated_notice("\ElggObject::getContainer deprecated for \ElggEntity::getContainerGUID", 1.8);
        return $this->getContainerGUID();
    }
 
    public function getContainerEntity() {
        return get_entity($this->getContainerGUID());
    }
 
    public function getTimeUpdated() {
        return $this->time_updated;
    }
 
    public function getURL() {
        
        $url = "";
 
        // @todo remove when elgg_register_entity_url_handler() has been removed
        if ($this->guid) {
            global $CONFIG;
            if (isset($CONFIG->entity_url_handler[$this->getType()][$this->getSubtype()])) {
                $function = $CONFIG->entity_url_handler[$this->getType()][$this->getSubtype()];
                if (is_callable($function)) {
                    $url = call_user_func($function, $this);
                }
            } elseif (isset($CONFIG->entity_url_handler[$this->getType()]['all'])) {
                $function = $CONFIG->entity_url_handler[$this->getType()]['all'];
                if (is_callable($function)) {
                    $url = call_user_func($function, $this);
                }
            } elseif (isset($CONFIG->entity_url_handler['all']['all'])) {
                $function = $CONFIG->entity_url_handler['all']['all'];
                if (is_callable($function)) {
                    $url = call_user_func($function, $this);
                }
            }
 
            if ($url) {
                $url = elgg_normalize_url($url);
            }
        }
 
        $type = $this->getType();
        $params = array('entity' => $this);
        $url = _elgg_services()->hooks->trigger('entity:url', $type, $params, $url);
 
        // @todo remove when \ElggEntity::setURL() has been removed
        if (!empty($this->url_override)) {
            $url = $this->url_override;
        }
 
        return elgg_normalize_url($url);
    }
 
    public function setURL($url) {
        elgg_deprecated_notice('\ElggEntity::setURL() has been replaced by the "entity:url" plugin hook', 1.9);
        $this->url_override = $url;
        return $url;
    }
 
    public function getIconURL($params = array()) {
        if (is_array($params)) {
            $size = elgg_extract('size', $params, 'medium');
        } else {    
            $size = is_string($params) ? $params : 'medium';
            $params = array();
        }
        $size = elgg_strtolower($size);
 
        if (isset($this->icon_override[$size])) {
            elgg_deprecated_notice("icon_override on an individual entity is deprecated", 1.8);
            return $this->icon_override[$size];
        }
 
        $params['entity'] = $this;
        $params['size'] = $size;
 
        $type = $this->getType();
 
        $url = _elgg_services()->hooks->trigger('entity:icon:url', $type, $params, null);
        if ($url == null) {
            $url = "_graphics/icons/default/$size.png";
        }
 
        return elgg_normalize_url($url);
    }
 
    public function getIcon($size = 'medium') {
        elgg_deprecated_notice("getIcon() deprecated by getIconURL()", 1.8);
        return $this->getIconURL($size);
    }
 
    public function setIcon($url, $size = 'medium') {
        elgg_deprecated_notice("icon_override on an individual entity is deprecated", 1.8);
 
        $url = sanitise_string($url);
        $size = sanitise_string($size);
 
        if (!$this->icon_override) {
            $this->icon_override = array();
        }
        $this->icon_override[$size] = $url;
 
        return true;
    }
 
    public function addToSite($site) {
        if (!elgg_instanceof($site, 'site')) {
            return false;
        }
 
        return $site->addEntity($this);
    }
 
    public function removeFromSite($site) {
        if (!elgg_instanceof($site, 'site')) {
            return false;
        }
 
        return $site->removeEntity($this);
    }
 
    public function getSites($options = array()) {
        $options['relationship'] = 'member_of_site';
        $options['relationship_guid'] = $this->guid;
        $options['inverse_relationship'] = false;
        if (!isset($options['site_guid']) || !isset($options['site_guids'])) {
            $options['site_guids'] = ELGG_ENTITIES_ANY_VALUE;
        }
 
        return elgg_get_entities_from_relationship($options);
    }
 
    public function isFullyLoaded() {
        return ! ($this->tables_loaded < $this->tables_split);
    }
 
    public function save() {
        $guid = $this->getGUID();
        if ($guid > 0) {
            return $this->update();
        } else {
            $guid = $this->create();
            if ($guid) {
                if (_elgg_services()->events->trigger('create', $this->type, $this)) {
                    return $guid;
                } else {
                    // plugins that return false to event don't need to override the access system
                    $ia = elgg_set_ignore_access(true);
                    $this->delete();
                    elgg_set_ignore_access($ia);
                }
            }
        }
        
        return false;
    }
    
    protected function create() {
        global $CONFIG;
 
        // Using attribute array directly; get function does something special!
        $type = $this->getDatabase()->sanitizeString($this->attributes['type']);
        if ($type == "") {
            throw new \InvalidParameterException("Entity type must be set.");
        }
        
        $subtype = $this->attributes['subtype'];
        $subtype_id = add_subtype($type, $subtype);
        $owner_guid = (int)$this->attributes['owner_guid'];
        $access_id = (int)$this->attributes['access_id'];
        $now = (string)time();
        $time_created = isset($this->attributes['time_created']) ? (int)$this->attributes['time_created'] : $now;
 
        $site_guid = $this->attributes['site_guid'];
        if ($site_guid == 0) {
            $site_guid = $CONFIG->site_guid;
        }
        $site_guid = (int)$site_guid;
        
        $container_guid = $this->attributes['container_guid'];
        if ($container_guid == 0) {
            $container_guid = $owner_guid;
        }
        $container_guid = (int)$container_guid;
 
        if ($access_id == ACCESS_DEFAULT) {
            throw new \InvalidParameterException('ACCESS_DEFAULT is not a valid access level. See its documentation in elgglib.h');
        }
 
        $owner = $this->getOwnerEntity();
        if ($owner && !$owner->canWriteToContainer(0, $type, $subtype)) {
            return false;
        }
        
        if ($owner_guid != $container_guid) {
            $container = $this->getContainerEntity();
            if ($container && !$container->canWriteToContainer(0, $type, $subtype)) {
                return false;
            }
        }
        
        $result = $this->getDatabase()->insertData("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_created, $now, $now)");
 
        if (!$result) {
            throw new \IOException("Unable to save new object's base entity information!");
        }
    
        // for BC with 1.8, ->subtype always returns ID, ->getSubtype() the string
        $this->attributes['subtype'] = (int)$subtype_id;
        $this->attributes['guid'] = (int)$result;
        $this->attributes['time_created'] = (int)$time_created;
        $this->attributes['time_updated'] = (int)$now;
        $this->attributes['last_action'] = (int)$now;
        $this->attributes['site_guid'] = (int)$site_guid;
        $this->attributes['container_guid'] = (int)$container_guid;
 
        // Save any unsaved metadata
        if (sizeof($this->temp_metadata) > 0) {
            foreach ($this->temp_metadata as $name => $value) {
                $this->$name = $value;
            }
            
            $this->temp_metadata = array();
        }
 
        // Save any unsaved annotations.
        if (sizeof($this->temp_annotations) > 0) {
            foreach ($this->temp_annotations as $name => $value) {
                $this->annotate($name, $value);
            }
            
            $this->temp_annotations = array();
        }
 
        // Save any unsaved private settings.
        if (sizeof($this->temp_private_settings) > 0) {
            foreach ($this->temp_private_settings as $name => $value) {
                $this->setPrivateSetting($name, $value);
            }
            
            $this->temp_private_settings = array();
        }
 
        _elgg_cache_entity($this);
        
        return $result;
    }
 
    protected function update() {
        global $CONFIG;
 
        // See #5600. This ensures canEdit() checks the BD persisted entity so it sees the
        // persisted owner_guid, container_guid, etc.
        _elgg_disable_caching_for_entity($this->guid);
        $persisted_entity = get_entity($this->guid);
        if (!$persisted_entity) {
            // Why worry about this case? If access control was off when the user fetched this object but
            // was turned back on again. Better to just bail than to turn access control off again.
            return false;
        }
 
        $allow_edit = $persisted_entity->canEdit();
        unset($persisted_entity);
 
        if ($allow_edit) {
            // give old update event a chance to stop the update
            $allow_edit = _elgg_services()->events->trigger('update', $this->type, $this);
        }
 
        _elgg_enable_caching_for_entity($this->guid);
 
        if (!$allow_edit) {
            return false;
        }
 
        // See #6225. We copy these after the update event in case a handler changed one of them.
        $guid = (int)$this->guid;
        $owner_guid = (int)$this->owner_guid;
        $access_id = (int)$this->access_id;
        $container_guid = (int)$this->container_guid;
        $time_created = (int)$this->time_created;
        $time = time();
 
        if ($access_id == ACCESS_DEFAULT) {
            throw new \InvalidParameterException('ACCESS_DEFAULT is not a valid access level. See its documentation in elgglib.php');
        }
        
        $ret = $this->getDatabase()->updateData("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");
        
        elgg_trigger_after_event('update', $this->type, $this);
 
        // TODO(evan): Move this to \ElggObject?
        if ($this 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);
        }
 
        if ($ret !== false) {
            $this->attributes['time_updated'] = $time;
        }
 
        _elgg_cache_entity($this);
 
        // Handle cases where there was no error BUT no rows were updated!
        return $ret !== false;
    }
 
    protected function load($guid) {
        if ($guid instanceof \stdClass) {
            $row = $guid;
        } else {
            $row = get_entity_as_row($guid);
        }
 
        if ($row) {
            // Create the array if necessary - all subclasses should test before creating
            if (!is_array($this->attributes)) {
                $this->attributes = array();
            }
 
            // Now put these into the attributes array as core values
            $objarray = (array) $row;
            foreach ($objarray as $key => $value) {
                $this->attributes[$key] = $value;
            }
 
            // Increment the portion counter
            if (!$this->isFullyLoaded()) {
                $this->tables_loaded++;
            }
 
            // guid needs to be an int  https://github.com/elgg/elgg/issues/4111
            $this->attributes['guid'] = (int)$this->attributes['guid'];
 
            // for BC with 1.8, ->subtype always returns ID, ->getSubtype() the string
            $this->attributes['subtype'] = (int)$this->attributes['subtype'];
 
            // Cache object handle
            if ($this->attributes['guid']) {
                _elgg_cache_entity($this);
            }
 
            return true;
        }
 
        return false;
    }
 
    protected function loadAdditionalSelectValues(array $data) {
        foreach ($data as $name => $value) {
            $this->setVolatileData("select:$name", $value);
        }
    }
    
    public function refresh(\stdClass $row) {
        if ($row instanceof \stdClass) {
            return $this->load($row);
        }
        return false;
    }
 
    public function disable($reason = "", $recursive = true) {
        if (!$this->guid) {
            return false;
        }
        
        if (!_elgg_services()->events->trigger('disable', $this->type, $this)) {
            return false;
        }
        
        if (!$this->canEdit()) {
            return false;
        }
 
        _elgg_invalidate_cache_for_entity($this->guid);
        
        if ($reason) {
            $this->disable_reason = $reason;
        }
 
        global $CONFIG;
        $guid = (int)$this->guid;
        
        if ($recursive) {
            $hidden = access_get_show_hidden_status();
            access_show_hidden_entities(true);
            $ia = elgg_set_ignore_access(true);
            
            $sub_entities = $this->getDatabase()->getData("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', $this->guid);
                    $e->disable($reason);
                }
            }
            
            access_show_hidden_entities($hidden);
            elgg_set_ignore_access($ia);
        }
 
        $this->disableMetadata();
        $this->disableAnnotations();
 
        $res = $this->getDatabase()->updateData("UPDATE {$CONFIG->dbprefix}entities
            SET enabled = 'no'
            WHERE guid = $guid");
 
        if ($res) {
            $this->attributes['enabled'] = 'no';
            _elgg_services()->events->trigger('disable:after', $this->type, $this);
        }
 
        return $res;
    }
 
    public function enable($recursive = true) {
        $guid = (int)$this->guid;
        if (!$guid) {
            return false;
        }
        
        if (!_elgg_services()->events->trigger('enable', $this->type, $this)) {
            return false;
        }
        
        if (!$this->canEdit()) {
            return false;
        }
        
        global $CONFIG;
    
        // Override access only visible entities
        $old_access_status = access_get_show_hidden_status();
        access_show_hidden_entities(true);
    
        $result = $this->getDatabase()->updateData("UPDATE {$CONFIG->dbprefix}entities
            SET enabled = 'yes'
            WHERE guid = $guid");
 
        $this->deleteMetadata('disable_reason');
        $this->enableMetadata();
        $this->enableAnnotations();
 
        if ($recursive) {
            $disabled_with_it = elgg_get_entities_from_relationship(array(
                'relationship' => 'disabled_with',
                'relationship_guid' => $guid,
                'inverse_relationship' => true,
                'limit' => 0,
            ));
 
            foreach ($disabled_with_it as $e) {
                $e->enable();
                remove_entity_relationship($e->guid, 'disabled_with', $guid);
            }
        }
    
        access_show_hidden_entities($old_access_status);
    
        if ($result) {
            $this->attributes['enabled'] = 'yes';
            _elgg_services()->events->trigger('enable:after', $this->type, $this);
        }
 
        return $result;
    }
 
    public function isEnabled() {
        return $this->enabled == 'yes';
    }
 
    public function delete($recursive = true) {
        global $CONFIG;
 
        $guid = $this->guid;
        if (!$guid) {
            return false;
        }
        
        // first check if we can delete this entity
        // NOTE: in Elgg <= 1.10.3 this was after the delete event, 
        // which could potentially remove some content if the user didn't have access
        if (!$this->canDelete()) {
            return false;
        }
 
        // now trigger an event to let others know this entity is about to be deleted
        // so they can prevent it or take their own actions
        if (!_elgg_services()->events->trigger('delete', $this->type, $this)) {
            return false;
        }
        
        _elgg_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) {
            // Temporarily overriding access controls
            $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);
            elgg_set_ignore_access($ia);
        }
 
        $entity_disable_override = access_get_show_hidden_status();
        access_show_hidden_entities(true);
        $ia = elgg_set_ignore_access(true);
        
        // Now delete the entity itself
        $this->deleteMetadata();
        $this->deleteOwnedMetadata();
        $this->deleteAnnotations();
        $this->deleteOwnedAnnotations();
        $this->deleteRelationships();
        $this->deleteAccessCollectionMemberships();
        $this->deleteOwnedAccessCollections();
 
        access_show_hidden_entities($entity_disable_override);
        elgg_set_ignore_access($ia);
 
        elgg_delete_river(array('subject_guid' => $guid));
        elgg_delete_river(array('object_guid' => $guid));
        elgg_delete_river(array('target_guid' => $guid));
        remove_all_private_settings($guid);
 
        $res = $this->getDatabase()->deleteData("DELETE FROM {$CONFIG->dbprefix}entities WHERE guid = $guid");
        if ($res) {
            $sub_table = "";
 
            // Where appropriate delete the sub table
            switch ($this->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) {
                $this->getDatabase()->deleteData("DELETE FROM $sub_table WHERE guid = $guid");
            }
        }
        
        _elgg_clear_entity_files($this);
 
        return (bool)$res;
    }
 
    public function toObject() {
        $object = $this->prepareObject(new \stdClass());
        $params = array('entity' => $this);
        $object = _elgg_services()->hooks->trigger('to:object', 'entity', $params, $object);
        return $object;
    }
 
    protected function prepareObject($object) {
        $object->guid = $this->guid;
        $object->type = $this->getType();
        $object->subtype = $this->getSubtype();
        $object->owner_guid = $this->getOwnerGUID();
        $object->container_guid = $this->getContainerGUID();
        $object->site_guid = (int)$this->site_guid;
        $object->time_created = date('c', $this->getTimeCreated());
        $object->time_updated = date('c', $this->getTimeUpdated());
        $object->url = $this->getURL();
        $object->read_access = (int)$this->access_id;
        return $object;
    }
 
    /*
     * LOCATABLE INTERFACE
     */
 
    public function getLocation() {
        return $this->location;
    }
 
    public function setLocation($location) {
        $this->location = $location;
    }
 
    public function setLatLong($lat, $long) {
        $this->{"geo:lat"} = $lat;
        $this->{"geo:long"} = $long;
    }
 
    public function getLatitude() {
        return (float)$this->{"geo:lat"};
    }
 
    public function getLongitude() {
        return (float)$this->{"geo:long"};
    }
 
    /*
     * NOTABLE INTERFACE
     */
 
    public function setCalendarTimeAndDuration($hour = null, $minute = null, $second = null,
    $day = null, $month = null, $year = null, $duration = null) {
        elgg_deprecated_notice(__METHOD__ . ' has been deprecated', 1.9);
 
        $start = mktime($hour, $minute, $second, $month, $day, $year);
        $end = $start + abs($duration);
        if (!$duration) {
            $end = get_day_end($day, $month, $year);
        }
 
        $this->calendar_start = $start;
        $this->calendar_end = $end;
 
        return true;
    }
 
    public function getCalendarStartTime() {
        elgg_deprecated_notice(__METHOD__ . ' has been deprecated', 1.9);
        return (int)$this->calendar_start;
    }
 
    public function getCalendarEndTime() {
        elgg_deprecated_notice(__METHOD__ . ' has been deprecated', 1.9);
        return (int)$this->calendar_end;
    }
 
    /*
     * EXPORTABLE INTERFACE
     */
 
    public function getExportableValues() {
        elgg_deprecated_notice(__METHOD__ . ' has been deprecated by toObject()', 1.9);
        return array(
            'guid',
            'type',
            'subtype',
            'time_created',
            'time_updated',
            'container_guid',
            'owner_guid',
            'site_guid'
        );
    }
 
    public function export() {
        elgg_deprecated_notice(__METHOD__ . ' has been deprecated', 1.9);
        $tmp = array();
 
        // Generate uuid
        $uuid = guid_to_uuid($this->getGUID());
 
        // Create entity
        $odd = new ODDEntity(
            $uuid,
            $this->attributes['type'],
            get_subtype_from_id($this->attributes['subtype'])
        );
 
        $tmp[] = $odd;
 
        $exportable_values = $this->getExportableValues();
 
        // Now add its attributes
        foreach ($this->attributes as $k => $v) {
            $meta = null;
 
            if (in_array($k, $exportable_values)) {
                switch ($k) {
                    case 'guid':            // Dont use guid in OpenDD
                    case 'type':            // Type and subtype already taken care of
                    case 'subtype':
                        break;
 
                    case 'time_created':    // Created = published
                        $odd->setAttribute('published', date("r", $v));
                        break;
 
                    case 'site_guid':   // Container
                        $k = 'site_uuid';
                        $v = guid_to_uuid($v);
                        $meta = new ODDMetaData($uuid . "attr/$k/", $uuid, $k, $v);
                        break;
 
                    case 'container_guid':  // Container
                        $k = 'container_uuid';
                        $v = guid_to_uuid($v);
                        $meta = new ODDMetaData($uuid . "attr/$k/", $uuid, $k, $v);
                        break;
 
                    case 'owner_guid':          // Convert owner guid to uuid, this will be stored in metadata
                        $k = 'owner_uuid';
                        $v = guid_to_uuid($v);
                        $meta = new ODDMetaData($uuid . "attr/$k/", $uuid, $k, $v);
                        break;
 
                    default:
                        $meta = new ODDMetaData($uuid . "attr/$k/", $uuid, $k, $v);
                }
 
                // set the time of any metadata created
                if ($meta) {
                    $meta->setAttribute('published', date("r", $this->time_created));
                    $tmp[] = $meta;
                }
            }
        }
 
        // Now we do something a bit special.
        /*
         * This provides a rendered view of the entity to foreign sites.
         */
 
        elgg_set_viewtype('default');
        $view = elgg_view_entity($this, array('full_view' => true));
        elgg_set_viewtype();
 
        $tmp[] = new ODDMetaData($uuid . "volatile/renderedentity/", $uuid,
            'renderedentity', $view, 'volatile');
 
        return $tmp;
    }
 
    /*
     * IMPORTABLE INTERFACE
     */
 
    public function import(ODD $data) {
        elgg_deprecated_notice(__METHOD__ . ' has been deprecated', 1.9);
        if (!($data instanceof ODDEntity)) {
            throw new \InvalidParameterException("import() passed an unexpected ODD class");
        }
 
        // Set type and subtype
        $this->attributes['type'] = $data->getAttribute('class');
        $this->attributes['subtype'] = $data->getAttribute('subclass');
 
        // Set owner
        $this->attributes['owner_guid'] = _elgg_services()->session->getLoggedInUserGuid(); // Import as belonging to importer.
 
        // Set time
        $this->attributes['time_created'] = strtotime($data->getAttribute('published'));
        $this->attributes['time_updated'] = time();
 
        return true;
    }
 
    /*
     * SYSTEM LOG INTERFACE
     */
 
    public function getSystemLogID() {
        return $this->getGUID();
    }
 
    public function getObjectFromID($id) {
        return get_entity($id);
    }
 
    public function getTags($tag_names = null) {
        if ($tag_names && !is_array($tag_names)) {
            $tag_names = array($tag_names);
        }
 
        $valid_tags = elgg_get_registered_tag_metadata_names();
        $entity_tags = array();
 
        foreach ($valid_tags as $tag_name) {
            if (is_array($tag_names) && !in_array($tag_name, $tag_names)) {
                continue;
            }
 
            if ($tags = $this->$tag_name) {
                // if a single tag, metadata returns a string.
                // if multiple tags, metadata returns an array.
                if (is_array($tags)) {
                    $entity_tags = array_merge($entity_tags, $tags);
                } else {
                    $entity_tags[] = $tags;
                }
            }
        }
 
        return $entity_tags;
    }
    
    public function deleteAccessCollectionMemberships() {
    
        if (!$this->guid) {
            return false;
        }
        
        if ($this->type !== 'user') {
            return true;
        }
        
        $ac = _elgg_services()->accessCollections;
        
        $collections = $ac->getCollectionsByMember($this->guid);
        if (empty($collections)) {
            return true;
        }
        
        $result = true;
        foreach ($collections as $collection) {
            $result = $result & $ac->removeUser($this->guid, $collection->id);
        }
        
        return $result;
    }
    
    public function deleteOwnedAccessCollections() {
        
        if (!$this->guid) {
            return false;
        }
        
        $ac = _elgg_services()->accessCollections;
        
        $collections = $ac->getEntityCollections($this->guid);
        if (empty($collections)) {
            return true;
        }
        
        $result = true;
        foreach ($collections as $collection) {
            $result = $result & $ac->delete($collection->id);
        }
        
        return $result;
    }
}