ElggEntity.php

Go to the documentation of this file.

<?php

use Elgg\EntityIcon;
use Elgg\Database\QueryBuilder;
use Elgg\Exceptions\InvalidParameterException;
use Elgg\Exceptions\DatabaseException;
use Elgg\Exceptions\Filesystem\IOException;
use Elgg\Exceptions\InvalidArgumentException as ElggInvalidArgumentException;
use Elgg\Traits\Entity\Subscriptions;

abstract class ElggEntity extends \ElggData implements EntityIcon {

    use Subscriptions;
    
    public const PRIMARY_ATTR_NAMES = [
        'guid',
        'type',
        'subtype',
        'owner_guid',
        'container_guid',
        'access_id',
        'time_created',
        'time_updated',
        'last_action',
        'enabled',
    ];

    protected const INTEGER_ATTR_NAMES = [
        'guid',
        'owner_guid',
        'container_guid',
        'access_id',
        'time_created',
        'time_updated',
        'last_action',
    ];

    protected $temp_metadata = [];

    protected $temp_annotations = [];

    protected $temp_private_settings = [];

    protected $volatile = [];

    protected $orig_attributes = [];

    protected $_is_cacheable = true;

    protected $_cached_metadata;

    public function __construct(stdClass $row = null) {
        $this->initializeAttributes();

        if ($row && !$this->load($row)) {
            $msg = "Failed to load new " . get_class() . " for GUID:" . $row->guid;
            throw new IOException($msg);
        }
    }

    protected function initializeAttributes() {
        parent::initializeAttributes();

        $this->attributes['guid'] = null;
        $this->attributes['type'] = $this->getType();
        $this->attributes['subtype'] = null;

        $this->attributes['owner_guid'] = _elgg_services()->session->getLoggedInUserGuid();
        $this->attributes['container_guid'] = _elgg_services()->session->getLoggedInUserGuid();

        $this->attributes['access_id'] = ACCESS_PRIVATE;
        $this->attributes['time_updated'] = null;
        $this->attributes['last_action'] = null;
        $this->attributes['enabled'] = "yes";
    }

    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([
            'guid' => $this->guid,
            'limit' => false,
        ]);

        $this->attributes['guid'] = null;
        $this->attributes['time_created'] = null;
        $this->attributes['time_updated'] = null;
        $this->attributes['last_action'] = null;

        $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 = [];
            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 ($this->$name === $value) {
            // quick return if value is not changing
            return;
        }

        if (array_key_exists($name, $this->attributes)) {
            // if an attribute is 1 (integer) and it's set to "1" (string), don't consider that a change.
            if (is_int($this->attributes[$name])
                    && is_string($value)
                    && ((string) $this->attributes[$name] === $value)) {
                return;
            }

            // keep original values
            if ($this->guid && !array_key_exists($name, $this->orig_attributes)) {
                $this->orig_attributes[$name] = $this->attributes[$name];
            }

            // Certain properties should not be manually changed!
            switch ($name) {
                case 'guid':
                case 'last_action':
                case 'time_updated':
                case 'type':
                    return;
                case 'subtype':
                    throw new ElggInvalidArgumentException(elgg_echo('ElggEntity:Error:SetSubtype', ['setSubtype()']));
                case 'enabled':
                    throw new ElggInvalidArgumentException(elgg_echo('ElggEntity:Error:SetEnabled', ['enable() / disable()']));
                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;
            }
            return;
        }

        $this->setMetadata($name, $value);
    }

    public function getOriginalAttributes() {
        return $this->orig_attributes;
    }

    public function __get($name) {
        if (array_key_exists($name, $this->attributes)) {
            return $this->attributes[$name];
        }

        return $this->getMetadata($name);
    }

    public function getDisplayName() {
        return (string) $this->name;
    }

    public function setDisplayName($display_name) {
        $this->name = $display_name;
    }

    public function getMetadata($name) {
        $metadata = $this->getAllMetadata();
        return elgg_extract($name, $metadata);
    }

    public function getAllMetadata() {
        if (!$this->guid) {
            return array_map(function($values) {
                return count($values) > 1 ? $values : $values[0];
            }, $this->temp_metadata);
        }

        $this->_cached_metadata = _elgg_services()->metadataCache->getAll($this->guid);

        return $this->_cached_metadata;
    }

    public function setMetadata($name, $value, $value_type = '', $multiple = false) {

        if ($value === null || $value === '') {
            $result = $this->deleteMetadata($name);
            if (is_null($result)) {
                // null result means no metadata found to be deleted
                return true;
            }
            
            return $result;
        }
        
        // 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 = [$value];
        }

        // strip null values from array
        $value = array_filter($value, function($var) {
            return !is_null($var);
        });

        if (empty($this->guid)) {
            // unsaved entity. store in temp array
            return $this->setTempMetadata($name, $value, $multiple);
        }

        // saved entity. persist md to db.
        if (!$multiple) {
            $current_metadata = $this->getMetadata($name);

            if ((is_array($current_metadata) || count($value) > 1 || $value === []) && isset($current_metadata)) {
                // remove current metadata if needed
                // need to remove access restrictions right now to delete
                // because this is the expected behavior
                $delete_result = elgg_call(ELGG_IGNORE_ACCESS, function() use ($name) {
                    return elgg_delete_metadata([
                        'guid' => $this->guid,
                        'metadata_name' => $name,
                        'limit' => false,
                    ]);
                });

                if (false === $delete_result) {
                    return false;
                }
            }

            if (count($value) > 1) {
                // new value is a multiple valued metadata
                $multiple = true;
            }
        }

        // create new metadata
        foreach ($value as $value_tmp) {
            $metadata = new ElggMetadata();
            $metadata->entity_guid = $this->guid;
            $metadata->name = $name;
            $metadata->value = $value_tmp;
            
            if (!empty($value_type)) {
                $metadata->value_type = $value_type;
            }
            
            $md_id = _elgg_services()->metadataTable->create($metadata, $multiple);
            if ($md_id === false) {
                return false;
            }
        }

        return true;
    }

    protected function setTempMetadata($name, $value, $multiple = false) {
        // if overwrite, delete first
        if (!$multiple) {
            unset($this->temp_metadata[$name]);
            if (count($value)) {
                // only save if value array contains data
                $this->temp_metadata[$name] = $value;
            }
            return true;
        }

        if (!isset($this->temp_metadata[$name])) {
            $this->temp_metadata[$name] = [];
        }

        $this->temp_metadata[$name] = array_merge($this->temp_metadata[$name], $value);

        return true;
    }



    public function deleteMetadata($name = null) {

        if (!$this->guid) {
            // remove from temp_metadata
            if ($name) {
                if (!isset($this->temp_metadata[$name])) {
                    return null;
                } else {
                    unset($this->temp_metadata[$name]);
                    return true;
                }
            } else {
                $this->temp_metadata = [];
                return true;
            }
        }

        $options = [
            'guid' => $this->guid,
            'limit' => false,
        ];
        if ($name) {
            $options['metadata_name'] = $name;
        }

        return elgg_delete_metadata($options);
    }

    public function getVolatileData($name) {
        return array_key_exists($name, $this->volatile) ? $this->volatile[$name] : null;
    }

    public function setVolatileData($name, $value) {
        $this->volatile[$name] = $value;
    }

    public function addRelationship($guid_two, $relationship) {
        return _elgg_services()->relationshipsTable->add($this->guid, (string) $relationship, (int) $guid_two);
    }
    
    public function hasRelationship(int $guid_two, string $relationship): bool {
        return (bool) _elgg_services()->relationshipsTable->check($this->guid, $relationship, $guid_two);
    }
    
    public function getRelationship(int $guid_two, string $relationship): ?\ElggRelationship {
        return _elgg_services()->relationshipsTable->check($this->guid, $relationship, $guid_two) ?: null;
    }
    
    public function getEntitiesFromRelationship(array $options = []) {
        $options['relationship_guid'] = $this->guid;
        return elgg_get_entities($options);
    }
    
    public function countEntitiesFromRelationship($relationship, $inverse_relationship = false) {
        return elgg_count_entities([
            'relationship' => $relationship,
            'relationship_guid' => $this->guid,
            'inverse_relationship' => $inverse_relationship,
        ]);
    }

    public function removeRelationship($guid_two, $relationship) {
        return _elgg_services()->relationshipsTable->remove($this->guid, (string) $relationship, (int) $guid_two);
    }
    
    public function removeAllRelationships(string $relationship = null, bool $inverse_relationship = false): bool {
        return _elgg_services()->relationshipsTable->removeAll($this->guid, $relationship, $inverse_relationship);
    }
    
    public function deleteRelationships($relationship = null) {
        elgg_deprecated_notice(__METHOD__ . ' has been deprecated. Use \ElggEntity->removeAllRelationships()', '4.3');
        
        $result = $this->removeAllRelationships($relationship);
        return $result && $this->removeAllRelationships($relationship, true);
    }

    public function setPrivateSetting($name, $value) {
        
        if ($value === null || $value === '') {
            $this->removePrivateSetting($name);
            
            // do not check result of removePrivateSetting as it returns false if private setting does not exist
            return true;
        }
        
        if (is_bool($value)) {
            $value = (int) $value;
        }
        
        // checking if string value matches saved value (as get privatesettings does not know value type) and db column is a string
        if (strval($value) === $this->getPrivateSetting($name)) {
            // no need to update value
            return true;
        }

        if (!$this->guid) {
            $this->temp_private_settings[$name] = $value;

            return true;
        }

        return _elgg_services()->privateSettings->set($this, $name, $value);
    }

    public function getPrivateSetting($name) {
        if (!$this->guid) {
            return elgg_extract($name, $this->temp_private_settings);
        }

        return _elgg_services()->privateSettings->get($this, $name);
    }

    public function getAllPrivateSettings() {
        if (!$this->guid) {
            return $this->temp_private_settings;
        }

        return _elgg_services()->privateSettings->getAllForEntity($this);
    }

    public function removePrivateSetting($name) {
        if (!$this->guid) {
            unset($this->temp_private_settings[$name]);
            return true;
        }

        return _elgg_services()->privateSettings->remove($this, $name);
    }

    public function removeAllPrivateSettings() {
        if (!$this->guid) {
            $this->temp_private_settings = [];
            return true;
        }

        return _elgg_services()->privateSettings->removeAllForEntity($this);
    }

    public function removeAllRelatedRiverItems() {
        elgg_delete_river(['subject_guid' => $this->guid, 'limit' => false]);
        elgg_delete_river(['object_guid' => $this->guid, 'limit' => false]);
        elgg_delete_river(['target_guid' => $this->guid, 'limit' => false]);
    }

    public function deleteAnnotations($name = null) {
        if ($this->guid) {
            $options = [
                'guid' => $this->guid,
                'limit' => false,
            ];
            if ($name) {
                $options['annotation_name'] = $name;
            }
    
            return elgg_delete_annotations($options);
        }
        
        if ($name) {
            unset($this->temp_annotations[$name]);
        } else {
            $this->temp_annotations = [];
        }
        
        return true;
    }

    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
        return elgg_call(ELGG_IGNORE_ACCESS, function() use ($name) {
            return elgg_delete_annotations([
                'annotation_owner_guid' => $this->guid,
                'limit' => false,
                'annotation_name' => $name,
            ]);
        });
    }

    public function disableAnnotations($name = '') {
        $options = [
            'guid' => $this->guid,
            'limit' => false,
        ];
        if ($name) {
            $options['annotation_name'] = $name;
        }

        return elgg_disable_annotations($options);
    }

    public function enableAnnotations($name = '') {
        $options = [
            'guid' => $this->guid,
            'limit' => false,
        ];
        if ($name) {
            $options['annotation_name'] = $name;
        }

        return elgg_enable_annotations($options);
    }

    private function getAnnotationCalculation($name, $calculation) {
        $options = [
            '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, $value_type = "") {
        if (!$this->guid) {
            $this->temp_annotations[$name] = $value;
            return true;
        }
        
        if (!$owner_guid) {
            $owner_guid = _elgg_services()->session->getLoggedInUserGuid();
        }
        
        $annotation = new ElggAnnotation();
        $annotation->entity_guid = $this->guid;
        $annotation->name = $name;
        $annotation->value = $value;
        $annotation->owner_guid = $owner_guid;
        $annotation->access_id = $access_id;
        
        if (!empty($value_type)) {
            $annotation->value_type = $value_type;
        }
        
        if ($annotation->save()) {
            return $annotation->id;
        }
        
        return false;
    }

    public function getAnnotations(array $options = []) {
        if ($this->guid) {
            $options['guid'] = $this->guid;

            return elgg_get_annotations($options);
        } else {
            $name = elgg_extract('annotation_name', $options, '');

            if (isset($this->temp_annotations[$name])) {
                return [$this->temp_annotations[$name]];
            }
        }

        return [];
    }

    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() {
        if (!$this->hasCapability('commentable')) {
            return 0;
        }
        
        $params = ['entity' => $this];
        $num = _elgg_services()->hooks->trigger('comments:count', $this->getType(), $params);

        if (is_int($num)) {
            return $num;
        }
        
        return \Elgg\Comments\DataService::instance()->getCommentsCount($this);
    }

    public function getOwnedAccessCollections($options = []) {
        $options['owner_guid'] = $this->guid;
        return _elgg_services()->accessCollections->getEntityCollections($options);
    }
    
    public function getOwnedAccessCollection($subtype) {
        if (!is_string($subtype) || $subtype === '') {
            return false;
        }
        
        $acls = $this->getOwnedAccessCollections([
            'subtype' => $subtype,
        ]);
        
        return elgg_extract(0, $acls, false);
    }
    
    public function hasAccess(int $user_guid = 0): bool {
        return _elgg_services()->accessCollections->hasAccessToEntity($this, $user_guid);
    }

    

    public function canEdit($user_guid = 0) {
        return _elgg_services()->userCapabilities->canEdit($this, $user_guid);
    }

    public function canDelete($user_guid = 0) {
        return _elgg_services()->userCapabilities->canDelete($this, $user_guid);
    }

    public function canWriteToContainer($user_guid = 0, $type = '', $subtype = '') {
        if (empty($type) || empty($subtype)) {
            throw new ElggInvalidArgumentException(__METHOD__ . ' requires $type and $subtype to be set');
        }
        
        return _elgg_services()->userCapabilities->canWriteToContainer($this, $type, $subtype, $user_guid);
    }

    public function canComment($user_guid = 0, $default = null) {
        return _elgg_services()->userCapabilities->canComment($this, $user_guid, $default);
    }

    public function canAnnotate($user_guid = 0, $annotation_name = '') {
        return _elgg_services()->userCapabilities->canAnnotate($this, $user_guid, $annotation_name);
    }

    public function getAccessID() {
        elgg_deprecated_notice(__METHOD__ . ' is deprecated. Use the attribute "access_id" directly.', '4.1');
        return $this->access_id;
    }

    public function getGUID() {
        return $this->guid;
    }

    public function getType() {
        // this is just for the PHPUnit mocking framework
        return $this->type;
    }

    public function setSubtype(string $subtype) : void {
        // keep original values
        if ($this->guid && !array_key_exists('subtype', $this->orig_attributes)) {
            $this->orig_attributes['subtype'] = $this->attributes['subtype'];
        }
        
        $this->attributes['subtype'] = $subtype;
    }

    public function getSubtype() {
        return $this->attributes['subtype'];
    }

    public function getOwnerGUID() {
        return (int) $this->owner_guid;
    }

    public function getOwnerEntity() {
        return get_entity($this->owner_guid);
    }

    public function setContainerGUID($container_guid) {
        return $this->container_guid = (int) $container_guid;
    }

    public function getContainerGUID() {
        return (int) $this->container_guid;
    }

    public function getContainerEntity() {
        return get_entity($this->getContainerGUID());
    }

    public function getTimeUpdated() {
        return $this->time_updated;
    }

    public function getURL() {
        $url = elgg_generate_entity_url($this, 'view');

        $url = _elgg_services()->hooks->trigger('entity:url', $this->getType(), ['entity' => $this], $url);

        if (empty($url)) {
            return '';
        }

        return elgg_normalize_url($url);
    }

    public function saveIconFromUploadedFile($input_name, $type = 'icon', array $coords = []) {
        return _elgg_services()->iconService->saveIconFromUploadedFile($this, $input_name, $type, $coords);
    }

    public function saveIconFromLocalFile($filename, $type = 'icon', array $coords = []) {
        return _elgg_services()->iconService->saveIconFromLocalFile($this, $filename, $type, $coords);
    }

    public function saveIconFromElggFile(\ElggFile $file, $type = 'icon', array $coords = []) {
        return _elgg_services()->iconService->saveIconFromElggFile($this, $file, $type, $coords);
    }

    public function getIcon($size, $type = 'icon') {
        return _elgg_services()->iconService->getIcon($this, $size, $type);
    }

    public function deleteIcon($type = 'icon') {
        return _elgg_services()->iconService->deleteIcon($this, $type);
    }

    public function getIconLastChange($size, $type = 'icon') {
        return _elgg_services()->iconService->getIconLastChange($this, $size, $type);
    }

    public function hasIcon($size, $type = 'icon') {
        return _elgg_services()->iconService->hasIcon($this, $size, $type);
    }

    public function getIconURL($params = []) {
        return _elgg_services()->iconService->getIconURL($this, $params);
    }

    public function save() : bool {
        $result = false;
        
        if ($this->guid > 0) {
            $result = $this->update();
        } else {
            $guid = $this->create();
            if ($guid === false) {
                return false;
            }
            
            if (!_elgg_services()->events->trigger('create', $this->type, $this)) {
                // plugins that return false to event don't need to override the access system
                elgg_call(ELGG_IGNORE_ACCESS, function() {
                    return $this->delete();
                });
                return false;
            }
            
            $result = true;
        }

        if ($result) {
            $this->cache();
        }

        return $result;
    }

    protected function create() {

        $type = $this->attributes['type'];
        if (!in_array($type, \Elgg\Config::ENTITY_TYPES)) {
            throw new InvalidParameterException('Entity type must be one of the allowed types: '
                . implode(', ', \Elgg\Config::ENTITY_TYPES));
        }

        $subtype = $this->attributes['subtype'];
        if (!$subtype) {
            throw new InvalidParameterException("All entities must have a subtype");
        }

        $owner_guid = (int) $this->attributes['owner_guid'];
        $access_id = (int) $this->attributes['access_id'];
        $now = $this->getCurrentTime()->getTimestamp();
        $time_created = isset($this->attributes['time_created']) ? (int) $this->attributes['time_created'] : $now;

        $container_guid = $this->attributes['container_guid'];
        if ($container_guid == 0) {
            $container_guid = $owner_guid;
            $this->attributes['container_guid'] = $container_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 constants.php');
        }
        
        if ($access_id == ACCESS_FRIENDS) {
            throw new InvalidParameterException('ACCESS_FRIENDS is not a valid access level. See its documentation in constants.php');
        }

        $user_guid = _elgg_services()->session->getLoggedInUserGuid();

        // If given an owner, verify it can be loaded
        if ($owner_guid) {
            $owner = $this->getOwnerEntity();
            if (!$owner) {
                _elgg_services()->logger->error("User $user_guid tried to create a ($type, $subtype), but the given"
                    . " owner $owner_guid could not be loaded.");
                return false;
            }

            // If different owner than logged in, verify can write to container.

            if ($user_guid != $owner_guid && !$owner->canEdit() && !$owner->canWriteToContainer($user_guid, $type, $subtype)) {
                _elgg_services()->logger->error("User $user_guid tried to create a ($type, $subtype) with owner"
                    . " $owner_guid, but the user wasn't permitted to write to the owner's container.");
                return false;
            }
        }

        // If given a container, verify it can be loaded and that the current user can write to it
        if ($container_guid) {
            $container = $this->getContainerEntity();
            if (!$container) {
                _elgg_services()->logger->error("User $user_guid tried to create a ($type, $subtype), but the given"
                    . " container $container_guid could not be loaded.");
                return false;
            }

            if (!$container->canWriteToContainer($user_guid, $type, $subtype)) {
                _elgg_services()->logger->error("User $user_guid tried to create a ($type, $subtype), but was not"
                    . " permitted to write to container $container_guid.");
                return false;
            }
        }

        // Create primary table row
        $guid = _elgg_services()->entityTable->insertRow((object) [
            'type' => $type,
            'subtype' => $subtype,
            'owner_guid' => $owner_guid,
            'container_guid' => $container_guid,
            'access_id' => $access_id,
            'time_created' => $time_created,
            'time_updated' => $now,
            'last_action' => $now,
        ], $this->attributes);

        if (!$guid) {
            throw new IOException("Unable to save new object's base entity information!");
        }

        $this->attributes['subtype'] = $subtype;
        $this->attributes['guid'] = (int) $guid;
        $this->attributes['time_created'] = (int) $time_created;
        $this->attributes['time_updated'] = (int) $now;
        $this->attributes['last_action'] = (int) $now;
        $this->attributes['container_guid'] = (int) $container_guid;

        // We are writing this new entity to cache to make sure subsequent calls
        // to get_entity() load the entity from cache and not from the DB. This
        // MUST come before the metadata and annotation writes below!
        $this->cache();

        // Save any unsaved metadata
        if (sizeof($this->temp_metadata) > 0) {
            foreach ($this->temp_metadata as $name => $value) {
                // temp metadata is always an array, but if there is only one value return just the value
                $this->setMetadata($name, $value, '', count($value) > 1);
            }

            $this->temp_metadata = [];
        }

        // Save any unsaved annotations.
        if (sizeof($this->temp_annotations) > 0) {
            foreach ($this->temp_annotations as $name => $value) {
                $this->annotate($name, $value);
            }

            $this->temp_annotations = [];
        }

        // 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 = [];
        }
        
        if (isset($container) && !$container instanceof ElggUser) {
            // users have their own logic for setting last action
            $container->updateLastAction();
        }

        return $guid;
    }

    protected function update() {

        if (!$this->canEdit()) {
            return false;
        }

        // give old update event a chance to stop the update
        if (!_elgg_services()->events->trigger('update', $this->type, $this)) {
            return false;
        }

        $this->invalidateCache();

        // 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 = $this->getCurrentTime()->getTimestamp();

        if ($access_id == ACCESS_DEFAULT) {
            throw new InvalidParameterException('ACCESS_DEFAULT is not a valid access level. See its documentation in constants.php');
        }
    
        if ($access_id == ACCESS_FRIENDS) {
            throw new InvalidParameterException('ACCESS_FRIENDS is not a valid access level. See its documentation in constants.php');
        }

        // Update primary table
        $ret = _elgg_services()->entityTable->updateRow($guid, (object) [
            'owner_guid' => $owner_guid,
            'container_guid' => $container_guid,
            'access_id' => $access_id,
            'time_created' => $time_created,
            'time_updated' => $time,
            'guid' => $guid,
        ]);
        if ($ret === false) {
            return false;
        }

        $this->attributes['time_updated'] = $time;

        _elgg_services()->events->triggerAfter('update', $this->type, $this);

        $this->orig_attributes = [];

        $this->cache();

        // Handle cases where there was no error BUT no rows were updated!
        return true;
    }

    protected function load(stdClass $row) {
        $attributes = array_merge($this->attributes, (array) $row);

        if (array_diff(self::PRIMARY_ATTR_NAMES, array_keys($attributes)) !== []) {
            // Some primary attributes are missing
            return false;
        }

        foreach ($attributes as $name => $value) {
            if (!in_array($name, self::PRIMARY_ATTR_NAMES)) {
                $this->setVolatileData("select:$name", $value);
                unset($attributes[$name]);
                continue;
            }

            if (in_array($name, static::INTEGER_ATTR_NAMES)) {
                $attributes[$name] = (int) $value;
            }
        }

        $this->attributes = $attributes;

        $this->cache();

        return true;
    }

    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;
        }

        if ($this instanceof ElggUser && !$this->isBanned()) {
            // temporarily ban to prevent using the site during disable
            $this->ban();
            $unban_after = true;
        } else {
            $unban_after = false;
        }

        if ($reason) {
            $this->disable_reason = $reason;
        }

        $guid = (int) $this->guid;

        if ($recursive) {
            elgg_call(ELGG_IGNORE_ACCESS | ELGG_HIDE_DISABLED_ENTITIES, function () use ($guid, $reason) {
                $base_options = [
                    'wheres' => [
                        function(QueryBuilder $qb, $main_alias) use ($guid) {
                            return $qb->compare("{$main_alias}.guid", '!=', $guid, ELGG_VALUE_GUID);
                        },
                    ],
                    'limit' => false,
                    'batch' => true,
                    'batch_inc_offset' => false,
                ];

                foreach (['owner_guid', 'container_guid'] as $db_column) {
                    $options = $base_options;
                    $options[$db_column] = $guid;

                    $subentities = elgg_get_entities($options);

                    foreach ($subentities as $subentity) {
                        /* @var $subentity \ElggEntity */
                        if (!$subentity->isEnabled()) {
                            continue;
                        }
                        $subentity->addRelationship($guid, 'disabled_with');
                        $subentity->disable($reason, true);
                    }
                }
            });
        }

        $this->disableAnnotations();

        $disabled = _elgg_services()->entityTable->disable($this);

        if ($unban_after) {
            $this->unban();
        }

        if ($disabled) {
            $this->invalidateCache();

            $this->attributes['enabled'] = 'no';
            _elgg_services()->events->triggerAfter('disable', $this->type, $this);
        }

        return $disabled;
    }

    public function enable($recursive = true) {
        if (empty($this->guid)) {
            return false;
        }

        if (!_elgg_services()->events->trigger('enable', $this->type, $this)) {
            return false;
        }

        if (!$this->canEdit()) {
            return false;
        }

        $result = elgg_call(ELGG_IGNORE_ACCESS | ELGG_SHOW_DISABLED_ENTITIES, function() use ($recursive) {
            $result = _elgg_services()->entityTable->enable($this);
                
            $this->deleteMetadata('disable_reason');
            $this->enableAnnotations();

            if ($recursive) {
                $disabled_with_it = elgg_get_entities([
                    'relationship' => 'disabled_with',
                    'relationship_guid' => $this->guid,
                    'inverse_relationship' => true,
                    'limit' => false,
                    'batch' => true,
                    'batch_inc_offset' => false,
                ]);

                foreach ($disabled_with_it as $e) {
                    $e->enable($recursive);
                    $e->removeRelationship($this->guid, 'disabled_with');
                }
            }

            return $result;
        });

        if ($result) {
            $this->attributes['enabled'] = 'yes';
            _elgg_services()->events->triggerAfter('enable', $this->type, $this);
        }

        return $result;
    }

    public function isEnabled() {
        return $this->enabled == 'yes';
    }

    public function delete($recursive = true) {
        // 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;
        }

        try {
            return _elgg_services()->entityTable->delete($this, $recursive);
        } catch (DatabaseException $ex) {
            elgg_log($ex, 'ERROR');
            return false;
        }
    }

    public function toObject(array $params = []) {
        $object = $this->prepareObject(new \Elgg\Export\Entity());

        $params['entity'] = $this;

        return _elgg_services()->hooks->trigger('to:object', 'entity', $params, $object);
    }

    protected function prepareObject(\Elgg\Export\Entity $object) {
        $object->guid = $this->guid;
        $object->type = $this->getType();
        $object->subtype = $this->getSubtype();
        $object->owner_guid = $this->getOwnerGUID();
        $object->container_guid = $this->getContainerGUID();
        $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;
    }

    public function setLatLong(float $lat, float $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"};
    }

    /*
     * SYSTEM LOG INTERFACE
     */

    public function getSystemLogID() {
        return $this->getGUID();
    }

    public function getObjectFromID($id) {
        return get_entity($id);
    }

    public function getTags($tag_names = null) {
        if (!isset($tag_names)) {
            $tag_names = ['tags'];
        }
        
        if ($tag_names && !is_array($tag_names)) {
            $tag_names = [$tag_names];
        }

        $entity_tags = [];
        foreach ($tag_names as $tag_name) {
            $tags = $this->$tag_name;
            if (elgg_is_empty($tags)) {
                continue;
            }
            
            // 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 &= $ac->removeUser($this->guid, $collection->id);
        }

        return $result;
    }

    public function deleteOwnedAccessCollections() {

        if (!$this->guid) {
            return false;
        }

        $collections = $this->getOwnedAccessCollections();
        if (empty($collections)) {
            return true;
        }

        $result = true;
        foreach ($collections as $collection) {
            $result = $result & $collection->delete();
        }

        return $result;
    }

    public function updateLastAction($posted = null) {
        $posted = _elgg_services()->entityTable->updateLastAction($this, $posted);
        if ($posted) {
            $this->attributes['last_action'] = $posted;
            $this->cache();
        }
        return $posted;
    }

    public function disableCaching() {
        $this->_is_cacheable = false;
        if ($this->guid) {
            _elgg_services()->entityCache->delete($this->guid);
        }
    }

    public function enableCaching() {
        $this->_is_cacheable = true;
    }

    public function isCacheable() {
        if (!$this->guid) {
            return false;
        }
        
        if (_elgg_services()->session->getIgnoreAccess()) {
            return false;
        }
        return $this->_is_cacheable;
    }

    public function cache($persist = true) {
        if (!$this->isCacheable()) {
            return;
        }

        _elgg_services()->entityCache->save($this);

        if (!$persist) {
            return;
        }
        
        $tmp = $this->volatile;

        // don't store volatile data
        $this->volatile = [];

        _elgg_services()->sessionCache->entities->save($this->guid, $this);

        $this->volatile = $tmp;
    }

    public function invalidateCache() {
        if (!$this->guid) {
            return;
        }

        _elgg_services()->entityCache->delete($this->guid);

        $namespaces = [
            'metadata',
            'private_settings',
        ];

        foreach ($namespaces as $namespace) {
            _elgg_services()->dataCache->get($namespace)->delete($this->guid);
        }
    }
    
    public function hasCapability(string $capability): bool {
        return _elgg_services()->entity_capabilities->hasCapability($this->getType(), $this->getSubtype(), $capability);
    }
}