aboutsummaryrefslogtreecommitdiff
path: root/engine/lib/annotations.php
diff options
context:
space:
mode:
Diffstat (limited to 'engine/lib/annotations.php')
-rw-r--r--engine/lib/annotations.php292
1 files changed, 40 insertions, 252 deletions
diff --git a/engine/lib/annotations.php b/engine/lib/annotations.php
index c545682d5..6fdb69dc0 100644
--- a/engine/lib/annotations.php
+++ b/engine/lib/annotations.php
@@ -409,274 +409,62 @@ $value = "", $owner_guid = 0, $limit = 10, $offset = 0, $order_by = "asc", $time
/**
+ * Returns entities based upon annotations. Accepts the same values as
+ * elgg_get_entities_from_metadata() but uses the annotations table.
*
- * @todo Add support for arrays of names and values
+ * @see elgg_get_entities
+ * @see elgg_get_entities_from_metadata
+ * @param array $options Array in format:
*
- * @param $options
- * @return unknown_type
+ * annotation_names => NULL|ARR annotations names
+ *
+ * annotation_values => NULL|ARR annotations values
+ *
+ * annotation_name_value_pairs => NULL|ARR (name = 'name', value => 'value', 'operand' => '=', 'case_sensitive' => TRUE) entries.
+ * Currently if multiple values are sent via an array (value => array('value1', 'value2') the pair's operand will be forced to "IN".
+ *
+ * annotation_name_value_pairs_operator => NULL|STR The operator to use for combining (name = value) OPERATOR (name = value); default AND
+ *
+ * annotation_case_sensitive => BOOL Overall Case sensitive
+ *
+ * order_by_annotation => NULL|ARR (array('name' => 'annotation_text1', 'direction' => ASC|DESC, 'as' => text|integer),
+ * Also supports array('name' => 'annotation_text1')
+ *
+ * annotation_owner_guids => NULL|ARR guids for annotaiton owners
+ *
+ * @return array
*/
function elgg_get_entities_from_annotations(array $options = array()) {
$defaults = array(
- 'annotation_names' => NULL,
- 'annotation_name' => NULL,
- 'annotation_values' => NULL,
- 'annotation_value' => NULL,
- 'annotation_name_value_pair' => NULL,
- 'annotation_name_value_pairs' => NULL,
- 'annotation_name_value_pairs_operator' => 'AND',
- 'annotation_case_sensitive' => TRUE,
- 'order_by' => 'maxtime desc',
- 'group_by' => 'a.entity_guid'
- );
-
- $options = array_merge($defaults, $options);
-
- $singulars = array('annotation_name', 'annotation_value', 'annotation_name_value_pair');
- $options = elgg_normalise_plural_options_array($options, $singulars);
-
- $clauses = elgg_get_entity_annotation_where_sql('e', $options['annotation_names'], $options['annotation_values'],
- $options['annotation_name_value_pairs'], $options['annotation_name_value_pairs_operator'], $options['annotation_case_sensitive']);
-
- if ($clauses) {
- // merge wheres to pass to get_entities()
- if (isset($options['wheres']) && !is_array($options['wheres'])) {
- $options['wheres'] = array($options['wheres']);
- } elseif (!isset($options['wheres'])) {
- $options['wheres'] = array();
- }
-
- $options['wheres'] = array_merge($options['wheres'], $clauses['wheres']);
-
- // merge joins to pass to get_entities()
- if (isset($options['joins']) && !is_array($options['joins'])) {
- $options['joins'] = array($options['joins']);
- } elseif (!isset($options['joins'])) {
- $options['joins'] = array();
- }
-
- $options['joins'] = array_merge($options['joins'], $clauses['joins']);
-
- // merge selects to pass to get_entities()
- if (isset($options['selects']) && !is_array($options['selects'])) {
- $options['selects'] = array($options['selects']);
- } elseif (!isset($options['selects'])) {
- $options['selects'] = array();
- }
-
- $options['selects'] = array_merge($options['selects'], $clauses['selects']);
-
- /* @todo overwrites the current order and group bys
- if ($clauses['order_by']) {
- $options['order_by'] = $clauses['order_by'];
- }
- if ($clauses['group_by']) {
- $options['group_by'] = $clauses['group_by'];
- }
- */
- }
-
- return elgg_get_entities($options);
-}
+ 'annotation_names' => ELGG_ENTITIES_ANY_VALUE,
+ 'annotation_values' => ELGG_ENTITIES_ANY_VALUE,
+ 'annotation_name_value_pairs' => ELGG_ENTITIES_ANY_VALUE,
-/**
- * Returns annotation name and value SQL where for entities.
- * nb: $names and $values are not paired. Use $pairs for this.
- * Pairs default to '=' operand.
- *
- * @param $prefix
- * @param ARR|NULL $names
- * @param ARR|NULL $values
- * @param ARR|NULL $pairs array of names / values / operands
- * @param AND|OR $pair_operator Operator to use to join the where clauses for pairs
- * @param BOOL $case_sensitive
- * @return FALSE|array False on fail, array('joins', 'wheres')
- */
-function elgg_get_entity_annotation_where_sql($table, $names = NULL, $values = NULL, $pairs = NULL, $pair_operator = 'AND', $case_sensitive = TRUE) {
- global $CONFIG;
-
- // short circuit if nothing requested
- // 0 is a valid (if not ill-conceived) annotation name.
- // 0 is also a valid annotation value for FALSE, NULL, or 0
- if ((!$names && $names !== 0)
- && (!$values && $values !== 0)
- && (!$pairs && $pairs !== 0)) {
- return '';
- }
+ 'annotation_name_value_pairs_operator' => 'AND',
+ 'annotation_case_sensitive' => TRUE,
+ 'order_by_annotation' => array(),
- // binary forces byte-to-byte comparision of strings, making
- // it case- and diacritical-mark- sensitive.
- // only supported on values.
- $binary = ($case_sensitive) ? ' BINARY ' : '';
+ 'annotation_owner_guids' => ELGG_ENTITIES_ANY_VALUE,
- $access = get_access_sql_suffix('a');
-
- $return = array (
- 'joins' => array (),
- 'wheres' => array(),
- 'selects' => array()
+ 'order_by' => 'maxtime desc',
+ 'group_by' => 'a.entity_guid'
);
- $wheres = array();
-
- // get names wheres and joins
- $names_where = '';
- if ($names !== NULL) {
- $return['joins'][] = "JOIN {$CONFIG->dbprefix}annotations a on {$table}.guid = a.entity_guid";
- if (!is_array($names)) {
- $names = array($names);
- }
-
- $sanitised_names = array();
- foreach ($names as $name) {
- // normalise to 0.
- if (!$name) {
- $name = '0';
- }
- $sanitised_names[] = "'$name'";
- }
-
- if ($names_str = implode(',', $sanitised_names)) {
- $return['joins'][] = "JOIN {$CONFIG->dbprefix}metastrings msn on a.name_id = msn.id";
- $names_where = "(msn.string IN ($names_str))";
- }
- }
-
- // get values wheres and joins
- $values_where = '';
- if ($values !== NULL) {
- $return['joins'][] = "JOIN {$CONFIG->dbprefix}annotations a on {$table}.guid = a.entity_guid";
-
- if (!is_array($values)) {
- $values = array($values);
- }
-
- $sanitised_values = array();
- foreach ($values as $value) {
- // normalize to 0
- if (!$value) {
- $value = 0;
- }
- $sanitised_values[] = "'$value'";
- }
-
- if ($values_str = implode(',', $sanitised_values)) {
- $return['joins'][] = "JOIN {$CONFIG->dbprefix}metastrings msv on a.value_id = msv.id";
- $values_where = "({$binary}msv.string IN ($values_str))";
- }
- }
-
- if ($names_where && $values_where) {
- $wheres[] = "($names_where AND $values_where AND $access)";
- } elseif ($names_where) {
- $wheres[] = "($names_where AND $access)";
- } elseif ($values_where) {
- $wheres[] = "($values_where AND $access)";
- }
-
- // add pairs
- // pairs must be in arrays.
- if (is_array($pairs)) {
- $array = array(
- 'name' => 'test',
- 'value' => 5
- );
-
- $array = array('test' => 5);
-
- // check if this is an array of pairs or just a single pair.
- if (isset($pairs['name']) || isset($pairs['value'])) {
- $pairs = array($pairs);
- }
-
- $pair_wheres = array();
-
- // @todo when the pairs are > 3 should probably split the query up to
- // denormalize the strings table.
- $i = 1;
- foreach ($pairs as $index => $pair) {
- // @todo move this elsewhere?
- // support shortcut 'n' => 'v' method.
- if (!is_array($pair)) {
- $pair = array(
- 'name' => $index,
- 'value' => $pair
- );
- }
-
- // @todo The multiple joins are only needed when the operator is AND
- $return['joins'][] = "JOIN {$CONFIG->dbprefix}annotations a{$i} on {$table}.guid = a{$i}.entity_guid";
- $return['joins'][] = "JOIN {$CONFIG->dbprefix}metastrings msn{$i} on a{$i}.name_id = msn{$i}.id";
- $return['joins'][] = "JOIN {$CONFIG->dbprefix}metastrings msv{$i} on a{$i}.value_id = msv{$i}.id";
-
- // must have at least a name and value
- if (!isset($pair['name']) || !isset($pair['value'])) {
- // @todo should probably return false.
- continue;
- }
-
- // case sensitivity can be specified per pair.
- // default to higher level setting.
- if (isset($pair['case_sensitive'])) {
- $pair_binary = ($pair['case_sensitive']) ? ' BINARY ' : '';
- } else {
- $pair_binary = $binary;
- }
-
- if (isset($pair['operand'])) {
- $operand = sanitise_string($pair['operand']);
- } else {
- $operand = ' = ';
- }
-
- // if the value is an int, don't quote it because str '15' < str '5'
- // if the operand is IN don't quote it because quoting should be done already.
- //$value = trim(strtolower($operand)) == 'in' ? $pair['value'] : "'{$pair['value']}'";
- if (trim(strtolower($operand)) == 'in' || sanitise_int($pair['value'])) {
- $value = $pair['value'];
- } else {
- $value = "'{$pair['value']}'";
- }
-
- $access = get_access_sql_suffix("a{$i}");
- $pair_wheres[] = "(msn{$i}.string = '{$pair['name']}' AND {$pair_binary}msv{$i}.string $operand $value AND $access)";
- $i++;
- }
+ $options = array_merge($defaults, $options);
- if ($where = implode (" $pair_operator ", $pair_wheres)) {
- $wheres[] = "($where)";
- }
+ if (!$options = elgg_entities_get_metastrings_options('annotation', $options)) {
+ return FALSE;
}
- if ($where = implode(' OR ', $wheres)) {
- $return['selects'][] = "max(a.time_created) as maxtime";
- $return['wheres'][] = "($where)";
- $return['group_by'] = 'a.entity_guid';
- $return['order_by'] = 'maxtime asc';
- }
+ // special sorting for annotations
+ //@todo overrides other sorting
+ $options['selects'][] = "max(n_table.time_created) as maxtime";
+ $options['group_by'] = 'n_table.entity_guid';
- return $return;
+ return elgg_get_entities($options);
}
/**
- * Return a list of entities which are annotated with a specific annotation.
- * These can be ordered by when the annotation was created/updated.
- *
- * @param string $entity_type Type of entity.
- * @param string $entity_subtype Subtype of entity.
- * @param string $name Name of annotation.
- * @param string $value Value of annotation.
- * @param int $owner_guid Owner.
- * @param int $group_guid Group container. Currently this is only supported if $entity_type == 'object'
- * @param int $limit Maximum number of results to return.
- * @param int $offset Place to start.
- * @param string $order_by How to order results.
- * @param boolean $count Whether to count entities rather than return them
- * @param int $timelower The earliest time the annotation can have been created. Default: all
- * @param int $timeupper The latest time the annotation can have been created. Default: all
- */
-
-
-/**
* @deprecated 1.7 Use elgg_get_entities_from_annotations()
* @param $entity_type
* @param $entity_subtype
@@ -714,7 +502,7 @@ $timelower = 0, $timeupper = 0) {
}
if ($owner_guid) {
- $options['owner_guid'] = $owner_guid;
+ $options['annotation_owner_guid'] = $owner_guid;
}
if ($group_guid) {