Annotations.php

Go to the documentation of this file.

<?php
namespace Elgg\Database;

class Annotations {

    use \Elgg\TimeUsing;
    
    protected $db;

    protected $session;

    protected $events;

    public function __construct(\Elgg\Database $db, \ElggSession $session, \Elgg\EventsService $events) {
        $this->db = $db;
        $this->session = $session;
        $this->events = $events;
    }

    function get($id) {
        return _elgg_get_metastring_based_object_from_id($id, 'annotation');
    }
    
    function delete($id) {
        $annotation = $this->get($id);
        if (!$annotation) {
            return false;
        }
        return $annotation->delete();
    }
    
    function create($entity_guid, $name, $value, $value_type = '', $owner_guid = 0, $access_id = ACCESS_PRIVATE) {
        
    
        $result = false;
    
        $entity_guid = (int)$entity_guid;
        $value_type = \ElggExtender::detectValueType($value, $value_type);
    
        $owner_guid = (int)$owner_guid;
        if ($owner_guid == 0) {
            $owner_guid = $this->session->getLoggedInUserGuid();
        }
    
        $access_id = (int)$access_id;
        $time = $this->getCurrentTime()->getTimestamp();
    
        $value_id = elgg_get_metastring_id($value);
        if (!$value_id) {
            return false;
        }
    
        $name_id = elgg_get_metastring_id($name);
        if (!$name_id) {
            return false;
        }
    
        // @todo we don't check that the entity is loaded which means the user may
        // not have access to the entity
        $entity = get_entity($entity_guid);
    
        if ($this->events->trigger('annotate', $entity->type, $entity)) {
            $result = $this->db->insertData("INSERT INTO {$this->db->prefix}annotations
                (entity_guid, name_id, value_id, value_type, owner_guid, time_created, access_id) VALUES
                ($entity_guid, $name_id, $value_id, '$value_type', $owner_guid, $time, $access_id)");
    
            if ($result !== false) {
                $obj = elgg_get_annotation_from_id($result);
                if ($this->events->trigger('create', 'annotation', $obj)) {
                    return $result;
                } else {
                    // plugin returned false to reject annotation
                    elgg_delete_annotation_by_id($result);
                    return false;
                }
            }
        }
    
        return $result;
    }
    
    function update($annotation_id, $name, $value, $value_type, $owner_guid, $access_id) {
        
    
        $annotation_id = (int)$annotation_id;
    
        $annotation = $this->get($annotation_id);
        if (!$annotation) {
            return false;
        }
        if (!$annotation->canEdit()) {
            return false;
        }
    
        $name = trim($name);
        $value_type = \ElggExtender::detectValueType($value, $value_type);
    
        $owner_guid = (int)$owner_guid;
        if ($owner_guid == 0) {
            $owner_guid = $this->session->getLoggedInUserGuid();
        }
    
        $access_id = (int)$access_id;
    
        $value_id = elgg_get_metastring_id($value);
        if (!$value_id) {
            return false;
        }
    
        $name_id = elgg_get_metastring_id($name);
        if (!$name_id) {
            return false;
        }
    
        $result = $this->db->updateData("UPDATE {$this->db->prefix}annotations
            SET name_id = $name_id, value_id = $value_id, value_type = '$value_type',
            access_id = $access_id, owner_guid = $owner_guid
            WHERE id = $annotation_id");
    
        if ($result !== false) {
            // @todo add plugin hook that sends old and new annotation information before db access
            $obj = $this->get($annotation_id);
            $this->events->trigger('update', 'annotation', $obj);
        }
    
        return $result;
    }
    
    function find(array $options = array()) {

        // support shortcut of 'count' => true for 'annotation_calculation' => 'count'
        if (isset($options['count']) && $options['count']) {
            $options['annotation_calculation'] = 'count';
            unset($options['count']);
        }
        
        $options['metastring_type'] = 'annotations';
        return _elgg_get_metastring_based_objects($options);
    }
    
    function deleteAll(array $options) {
        if (!_elgg_is_valid_options_for_batch_operation($options, 'annotation')) {
            return false;
        }
    
        $options['metastring_type'] = 'annotations';
        return _elgg_batch_metastring_based_objects($options, 'elgg_batch_delete_callback', false);
    }
    
    function disableAll(array $options) {
        if (!_elgg_is_valid_options_for_batch_operation($options, 'annotation')) {
            return false;
        }
        
        // if we can see hidden (disabled) we need to use the offset
        // otherwise we risk an infinite loop if there are more than 50
        $inc_offset = access_get_show_hidden_status();
    
        $options['metastring_type'] = 'annotations';
        return _elgg_batch_metastring_based_objects($options, 'elgg_batch_disable_callback', $inc_offset);
    }
    
    function enableAll(array $options) {
        if (!$options || !is_array($options)) {
            return false;
        }
    
        $options['metastring_type'] = 'annotations';
        return _elgg_batch_metastring_based_objects($options, 'elgg_batch_enable_callback');
    }
    
    function getEntities(array $options = array()) {
        $defaults = array(
            'annotation_names'                      => ELGG_ENTITIES_ANY_VALUE,
            'annotation_values'                     => ELGG_ENTITIES_ANY_VALUE,
            'annotation_name_value_pairs'           => ELGG_ENTITIES_ANY_VALUE,
    
            'annotation_name_value_pairs_operator'  => 'AND',
            'annotation_case_sensitive'             => true,
            'order_by_annotation'                   => array(),
    
            'annotation_created_time_lower'         => ELGG_ENTITIES_ANY_VALUE,
            'annotation_created_time_upper'         => ELGG_ENTITIES_ANY_VALUE,
    
            'annotation_owner_guids'                => ELGG_ENTITIES_ANY_VALUE,
        );
    
        $options = array_merge($defaults, $options);
    
        $singulars = array('annotation_name', 'annotation_value',
        'annotation_name_value_pair', 'annotation_owner_guid');
    
        $options = _elgg_normalize_plural_options_array($options, $singulars);
        $options = _elgg_entities_get_metastrings_options('annotation', $options);
    
        if (!$options) {
            return false;
        }
    
        // because of performance issues support for ordering by maxtime has been dropped
        // @see https://github.com/Elgg/Elgg/issues/6638
        if (isset($options['order_by']) && preg_match('~\bmaxtime\b~i', $options['order_by'])) {
            // check if the user provided maxtime
            $deprecated = true;
            if (isset($options['selects'])) {
                $selects = $options['selects'];
                if (!is_array($selects)) {
                    $selects = array($selects);
                }
                    
                foreach ($selects as $select) {
                    if (preg_match('~\bmaxtime\b~i', $options['order_by'])) {
                        $deprecated = false;
                        break;
                    }
                }
            }
        
            // the user didn't provide maxtime
            if ($deprecated) {
                // special sorting for annotations
                elgg_deprecated_notice(__FUNCTION__ . ": no longer orders by annotations by default. If you order"
                    . " by maxtime, you must provide that column via \$options['selects']. See"
                    . " https://github.com/Elgg/Elgg/issues/6638#issuecomment-41562034", "1.10");
                    
                $options['selects'][] = "MAX(n_table.time_created) AS maxtime";
                $options['group_by'] = 'n_table.entity_guid';
            }
        }
        
        $time_wheres = _elgg_get_entity_time_where_sql('n_table', $options['annotation_created_time_upper'],
            $options['annotation_created_time_lower']);

        if ($time_wheres) {
            $options['wheres'][] = $time_wheres;
        }
    
        return elgg_get_entities_from_metadata($options);
    }
    
    function getEntitiesFromCalculation($options) {
        
        if (isset($options['count']) && $options['count']) {
            return elgg_get_entities_from_annotations($options);
        }
        
        $db_prefix = $this->db->prefix;
        $defaults = array(
            'calculation' => 'sum',
            'order_by' => 'annotation_calculation desc'
        );
    
        $options = array_merge($defaults, $options);
    
        $function = sanitize_string(elgg_extract('calculation', $options, 'sum', false));
    
        // you must cast this as an int or it sorts wrong.
        $options['selects'][] = 'e.*';
        $options['selects'][] = "$function(CAST(a_msv.string AS signed)) AS annotation_calculation";
    
        // need our own join to get the values because the lower level functions don't
        // add all the joins if it's a different callback.
        $options['joins'][] = "JOIN {$db_prefix}metastrings a_msv ON n_table.value_id = a_msv.id";
    
        // don't need access control because it's taken care of by elgg_get_annotations.
        $options['group_by'] = 'n_table.entity_guid';

        // do not default to a callback function used in elgg_get_annotation()
        if (!isset($options['callback'])) {
            $options['callback'] = 'entity_row_to_elggstar';
        }

        return elgg_get_annotations($options);
    }
    
    function exists($entity_guid, $annotation_type, $owner_guid = null) {
        
    
        if (!$owner_guid && !($owner_guid = $this->session->getLoggedInUserGuid())) {
            return false;
        }
    
        $entity_guid = sanitize_int($entity_guid);
        $owner_guid = sanitize_int($owner_guid);
        $annotation_type = sanitize_string($annotation_type);
    
        $sql = "SELECT a.id FROM {$this->db->prefix}annotations a" .
                " JOIN {$this->db->prefix}metastrings m ON a.name_id = m.id" .
                " WHERE a.owner_guid = $owner_guid AND a.entity_guid = $entity_guid" .
                " AND m.string = '$annotation_type'";
    
        if ($this->db->getDataRow($sql)) {
            return true;
        }
    
        return false;
    }
}