ElggEntity.php

Go to the documentation of this file.

<?php

use Elgg\EntityIcon;
use Elgg\Database\QueryBuilder;
use Elgg\Exceptions\DatabaseException;
use Elgg\Exceptions\Filesystem\IOException;
use Elgg\Exceptions\DomainException as ElggDomainException;
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 $volatile = [];

    protected $orig_attributes = [];

    protected $_is_cacheable = true;

    protected $_cached_metadata;

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

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

    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_manager->getLoggedInUserGuid();
        $this->attributes['container_guid'] = _elgg_services()->session_manager->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(): array {
        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(): string {
        return (string) $this->name;
    }

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

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

    public function getAllMetadata(): array {
        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(string $name, $value, string $value_type = '', bool $multiple = false): bool {

        if ($value === null || $value === '') {
            return $this->deleteMetadata($name);
        }
        
        // 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 ($delete_result === false) {
                    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(string $name, $value, bool $multiple = false): bool {
        // 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(string $name = null): bool {

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

        return elgg_delete_metadata([
            'guid' => $this->guid,
            'limit' => false,
            'metadata_name' => $name,
        ]);
    }

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

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

    public function addRelationship(int $guid_two, string $relationship): bool {
        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(string $relationship, bool $inverse_relationship = false): int {
        return elgg_count_entities([
            'relationship' => $relationship,
            'relationship_guid' => $this->guid,
            'inverse_relationship' => $inverse_relationship,
        ]);
    }

    public function removeRelationship(int $guid_two, string $relationship): bool {
        return _elgg_services()->relationshipsTable->remove($this->guid, (string) $relationship, (int) $guid_two);
    }
    
    public function removeAllRelationships(string $relationship = '', bool $inverse_relationship = false): bool {
        return _elgg_services()->relationshipsTable->removeAll($this->guid, $relationship, $inverse_relationship);
    }

    public function removeAllRelatedRiverItems(): void {
        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(string $name = null): bool {
        if ($this->guid) {
            return elgg_delete_annotations([
                'guid' => $this->guid,
                'limit' => false,
                'annotation_name' => $name,
            ]);
        }
        
        if ($name) {
            unset($this->temp_annotations[$name]);
        } else {
            $this->temp_annotations = [];
        }
        
        return true;
    }

    public function deleteOwnedAnnotations(string $name = null): bool {
        // 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(string $name = null): bool {
        return elgg_disable_annotations([
            'guid' => $this->guid,
            'limit' => false,
            'annotation_name' => $name,
        ]);
    }

    public function enableAnnotations(string $name = null) {
        return elgg_enable_annotations([
            'guid' => $this->guid,
            'limit' => false,
            'annotation_name' => $name,
        ]);
    }

    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_manager->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(string $name = ''): int {
        return $this->getAnnotationCalculation($name, 'count');
    }

    public function getAnnotationsAvg(string $name) {
        return $this->getAnnotationCalculation($name, 'avg');
    }

    public function getAnnotationsSum(string $name) {
        return $this->getAnnotationCalculation($name, 'sum');
    }

    public function getAnnotationsMin(string $name) {
        return $this->getAnnotationCalculation($name, 'min');
    }

    public function getAnnotationsMax(string $name) {
        return $this->getAnnotationCalculation($name, 'max');
    }

    public function countComments(): int {
        if (!$this->hasCapability('commentable')) {
            return 0;
        }
        
        $params = ['entity' => $this];
        $num = _elgg_services()->events->triggerResults('comments:count', $this->getType(), $params);

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

    public function getOwnedAccessCollections(array $options = []): array {
        $options['owner_guid'] = $this->guid;
        return _elgg_services()->accessCollections->getEntityCollections($options);
    }
    
    public function getOwnedAccessCollection(string $subtype): ?\ElggAccessCollection {
        if ($subtype === '') {
            throw new ElggInvalidArgumentException(__METHOD__ . ' requires $subtype to be non empty');
        }
        
        $acls = $this->getOwnedAccessCollections([
            'subtype' => $subtype,
        ]);
        
        return elgg_extract(0, $acls);
    }
    
    public function hasAccess(int $user_guid = 0): bool {
        return _elgg_services()->accessCollections->hasAccessToEntity($this, $user_guid);
    }

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

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

    public function canWriteToContainer(int $user_guid = 0, string $type = '', string $subtype = ''): bool {
        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(int $user_guid = 0): bool {
        return _elgg_services()->userCapabilities->canComment($this, $user_guid);
    }

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

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

    public function getType(): string {
        // this is just for the PHPUnit mocking framework
        return (string) $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(): string {
        return (string) $this->attributes['subtype'];
    }

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

    public function getOwnerEntity(): ?\ElggEntity {
        return $this->owner_guid ? get_entity($this->owner_guid) : null;
    }

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

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

    public function getContainerEntity(): ?\ElggEntity {
        return $this->container_guid ? get_entity($this->getContainerGUID()) : null;
    }

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

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

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

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

        return elgg_normalize_url($url);
    }

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

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

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

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

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

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

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

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

    public function save(): bool {
        if ($this->guid > 0) {
            $result = $this->update();
        } else {
            $result = $this->create() !== false;
        }

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

        return $result;
    }

    protected function create() {

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

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

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

        // If given an owner, verify it can be loaded
        if (!empty($owner_guid)) {
            $owner = $this->getOwnerEntity();
            if (!$owner instanceof \ElggEntity) {
                $error = "User {$user_guid} tried to create a ({$type}, {$subtype}),";
                $error .= " but the given owner {$owner_guid} could not be loaded.";
                throw new ElggInvalidArgumentException($error);
            }

            // If different owner than logged in, verify can write to container.
            if ($user_guid !== $owner_guid && !$owner->canEdit() && !$owner->canWriteToContainer($user_guid, $type, $subtype)) {
                $error = "User {$user_guid} tried to create a ({$type}, {$subtype}) with owner {$owner_guid},";
                $error .= " but the user wasn't permitted to write to the owner's container.";
                throw new ElggInvalidArgumentException($error);
            }
        }

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

            if (!$container->canWriteToContainer($user_guid, $type, $subtype)) {
                $error = "User {$user_guid} tried to create a ({$type}, {$subtype}),";
                $error .= " but was not permitted to write to container {$container_guid}.";
                throw new ElggInvalidArgumentException($error);
            }
        }
        
        if (!_elgg_services()->events->triggerBefore('create', $this->type, $this)) {
            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 (count($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 (count($this->temp_annotations) > 0) {
            foreach ($this->temp_annotations as $name => $value) {
                $this->annotate($name, $value);
            }

            $this->temp_annotations = [];
        }
        
        if (isset($container) && !$container instanceof \ElggUser) {
            // users have their own logic for setting last action
            $container->updateLastAction();
        }
        
        // for BC reasons this event is still needed (for example for notifications)
        _elgg_services()->events->trigger('create', $this->type, $this);
        
        _elgg_services()->events->triggerAfter('create', $this->type, $this);

        return $guid;
    }

    protected function update(): bool {

        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 ElggInvalidArgumentException('ACCESS_DEFAULT is not a valid access level. See its documentation in constants.php');
        }
    
        if ($access_id == ACCESS_FRIENDS) {
            throw new ElggInvalidArgumentException('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): bool {
        $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(string $reason = '', bool $recursive = true): bool {
        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 (!empty($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);
                    /* @var $subentity \ElggEntity */
                    foreach ($subentities as $subentity) {
                        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(bool $recursive = true): bool {
        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(): bool {
        return $this->enabled == 'yes';
    }

    public function delete(bool $recursive = true): bool {
        // 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()->events->triggerResults('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): void {
        $this->{'geo:lat'} = $lat;
        $this->{'geo:long'} = $long;
    }

    public function getLatitude(): float {
        return (float) $this->{'geo:lat'};
    }

    public function getLongitude(): float {
        return (float) $this->{'geo:long'};
    }

    /*
     * SYSTEM LOG INTERFACE
     */

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

    public function getObjectFromID(int $id): ?\ElggEntity {
        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(int $posted = null): int {
        $posted = _elgg_services()->entityTable->updateLastAction($this, $posted);
        
        $this->attributes['last_action'] = $posted;
        $this->cache();
    
        return $posted;
    }

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

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

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

    public function cache(bool $persist = true): void {
        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(): void {
        if (!$this->guid) {
            return;
        }

        _elgg_services()->entityCache->delete($this->guid);
        _elgg_services()->dataCache->get('metadata')->delete($this->guid);
    }
    
    public function hasCapability(string $capability): bool {
        return _elgg_services()->entity_capabilities->hasCapability($this->getType(), $this->getSubtype(), $capability);
    }
}