Refs #650: Deprecated find_metadata() with elgg_get_metadata(). Deprecated get_metadata_for_entity() and get_metadata_byname() <twitch>. Added elgg_get_metastrings_based_objects() to deal with the commonalities between the metadata and annotation getter functions.

git-svn-id: http://code.elgg.org/elgg/trunk@8174 36083f99-b078-4883-b0ff-0f9b5a30f544

1 files changed, 17 insertions, 288 deletions

diff --git a/engine/lib/annotations.php b/engine/lib/annotations.php
index d61173ef6..a3f8f0bb9 100644
--- a/engine/lib/annotations.php
+++ b/engine/lib/annotations.php
@@ -183,7 +183,7 @@ function update_annotation($annotation_id, $name, $value, $value_type, $owner_gu
  *
  * 	annotation_case_sensitive => BOOL Overall Case sensitive
  *
- *  annotation_owner_guids => NULL|ARR guids for metadata owners
+ *  annotation_owner_guids => NULL|ARR guids for annotation owners
  *
  *  annotation_created_time_lower => INT Lower limit for created time.
  *
@@ -191,302 +191,31 @@ function update_annotation($annotation_id, $name, $value, $value_type, $owner_gu
  *
  *  annotation_calculation => STR Perform the MySQL function on the annotation values returned.
  *
- * @return array
+ * @return mixed
  * @since 1.8.0
  */
-function elgg_get_annotations($options = array()) {
-	$defaults = array(
-		// entities
-		'types'					=>	ELGG_ENTITIES_ANY_VALUE,
-		'subtypes'				=>	ELGG_ENTITIES_ANY_VALUE,
-		'type_subtype_pairs'	=>	ELGG_ENTITIES_ANY_VALUE,
-
-		'guids'					=>	ELGG_ENTITIES_ANY_VALUE,
-		'owner_guids'			=>	ELGG_ENTITIES_ANY_VALUE,
-		'container_guids'		=>	ELGG_ENTITIES_ANY_VALUE,
-		'site_guids'			=>	get_config('site_guid'),
-
-		'modified_time_lower'	=>	ELGG_ENTITIES_ANY_VALUE,
-		'modified_time_upper'	=>	ELGG_ENTITIES_ANY_VALUE,
-		'created_time_lower'	=>	ELGG_ENTITIES_ANY_VALUE,
-		'created_time_upper'	=>	ELGG_ENTITIES_ANY_VALUE,
-
-		// annotations
-		// options are normalized to the plural in case we ever add support for them.
-		'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_calculation'				=>	ELGG_ENTITIES_NO_VALUE,
-
-		'annotation_created_time_lower'			=>	ELGG_ENTITIES_ANY_VALUE,
-		'annotation_created_time_upper'			=>	ELGG_ENTITIES_ANY_VALUE,
-
-		'annotation_owner_guids'				=>	ELGG_ENTITIES_ANY_VALUE,
-
-		// sql
-		'order_by'	=>	'a.time_created asc',
-		'limit'		=>	10,
-		'offset'	=>	0,
-		'count'		=>	FALSE,
-		'selects'	=>	array(),
-		'wheres'	=>	array(),
-		'joins'		=>	array(),
-
-		'callback'	=> 'row_to_elggannotation',
+function elgg_get_annotations(array $options = array()) {
+	// map the annotation_* options to metastring_* options
+	$map = array(
+		'annotation_names' => 'metastring_names',
+		'annotation_values' => 'metastring_values',
+		'annotation_case_sensitive' => 'metastring_case_sensitive',
+		'annotation_owner_guids' => 'metastring_owner_guids',
+		'annotation_created_time_lower' => 'metastring_created_time_lower',
+		'annotation_created_time_upper' => 'metastring_created_time_upper',
+		'annotation_calculation' => 'metastring_calculation'
 	);
 
-	$options = array_merge($defaults, $options);
-
-	// can't use helper function with type_subtype_pair because
-	// it's already an array...just need to merge it
-	if (isset($options['type_subtype_pair'])) {
-		if (isset($options['type_subtype_pairs'])) {
-			$options['type_subtype_pairs'] = array_merge($options['type_subtype_pairs'],
-				$options['type_subtype_pair']);
-		} else {
-			$options['type_subtype_pairs'] = $options['type_subtype_pair'];
-		}
-	}
-
-	$singulars = array('type', 'subtype', 'guid', 'owner_guid', 'container_guid', 'site_guid',
-						'annotation_name', 'annotation_value'
-					);
+	$singulars = array('annotation_name', 'annotation_value');
 	$options = elgg_normalise_plural_options_array($options, $singulars);
 
-	if (!$options) {
-		return false;
-	}
-
-	$db_prefix = elgg_get_config('dbprefix');
-
-	// evaluate where clauses
-	if (!is_array($options['wheres'])) {
-		$options['wheres'] = array($options['wheres']);
-	}
-
-	$wheres = $options['wheres'];
-
-	// entities
-	$wheres[] = elgg_get_entity_type_subtype_where_sql('e', $options['types'],
-		$options['subtypes'], $options['type_subtype_pairs']);
-
-	$wheres[] = elgg_get_guid_based_where_sql('e.guid', $options['guids']);
-	$wheres[] = elgg_get_guid_based_where_sql('e.owner_guid', $options['owner_guids']);
-	$wheres[] = elgg_get_guid_based_where_sql('e.container_guid', $options['container_guids']);
-	$wheres[] = elgg_get_guid_based_where_sql('e.site_guid', $options['site_guids']);
-
-	$wheres[] = elgg_get_entity_time_where_sql('e', $options['created_time_upper'],
-		$options['created_time_lower'], $options['modified_time_upper'], $options['modified_time_lower']);
-
-	// annotations
-	$annotation_clauses = elgg_get_annotation_sql('a', $options['annotation_names'],
-		$options['annotation_values'], $options['annotation_case_sensitive']);
-
-	$wheres = array_merge($wheres, $annotation_clauses['wheres']);
-
-	$wheres[] = elgg_get_entity_time_where_sql('a', $options['annotation_created_time_upper'],
-		$options['annotation_created_time_lower'], null, null);
-
-	$wheres[] = elgg_get_guid_based_where_sql('a.owner_guid', $options['annotation_owner_guids']);
-
-	// remove identical where clauses
-	$wheres = array_unique($wheres);
-
-	// see if any functions failed
-	// remove empty strings on successful functions
-	foreach ($wheres as $i => $where) {
-		if ($where === FALSE) {
-			return FALSE;
-		} elseif (empty($where)) {
-			unset($wheres[$i]);
-		}
-	}
-
-	// evaluate join clauses
-	if (!is_array($options['joins'])) {
-		$options['joins'] = array($options['joins']);
-	}
-
-	$joins = $options['joins'];
-
-	$joins = array_merge($joins, $annotation_clauses['joins']);
-	$joins[] = "JOIN {$db_prefix}entities e ON a.entity_guid = e.guid";
-	$joins[] = "JOIN {$db_prefix}metastrings n on a.name_id = n.id";
-	$joins[] = "JOIN {$db_prefix}metastrings v on a.value_id = v.id";
-
-
-	// remove identical join clauses
-	$joins = array_unique($joins);
-
-	foreach ($joins as $i => $join) {
-		if ($join === FALSE) {
-			return FALSE;
-		} elseif (empty($join)) {
-			unset($joins[$i]);
-		}
-	}
-
-	// evalutate selects
-	if ($options['selects']) {
-		$selects = '';
-		foreach ($options['selects'] as $select) {
-			$selects .= ", $select";
-		}
-	} else {
-		$selects = '';
-	}
-
-	// check for calculations
-	if ($options['count']) {
-		$options['annotation_calculation'] = 'count';
-	}
-
-	if ($options['annotation_calculation'] === ELGG_ENTITIES_NO_VALUE) {
-		$query = "SELECT DISTINCT a.*, n.string as name, v.string as value FROM {$db_prefix}annotations a";
-	} else {
-		$query = "SELECT DISTINCT v.string as value, {$options['annotation_calculation']}(v.string) as calculation FROM {$db_prefix}annotations a";
-	}
-
-	// add joins
-	foreach ($joins as $j) {
-		$query .= " $j ";
-	}
-
-	// add wheres
-	$query .= ' WHERE ';
-
-	foreach ($wheres as $w) {
-		$query .= " $w AND ";
-	}
-
-	// Add access controls
-	$query .= get_access_sql_suffix('e');
-	if ($options['annotation_calculation'] === ELGG_ENTITIES_NO_VALUE) {
-		if ($options['group_by'] = sanitise_string($options['group_by'])) {
-			$query .= " GROUP BY {$options['group_by']}";
-		}
-
-		if ($options['order_by'] = sanitise_string($options['order_by'])) {
-			$query .= " ORDER BY {$options['order_by']}";
+	foreach ($map as $ann => $ms) {
+		if (isset($options[$ann])) {
+			$options[$ms] = $options[$ann];
 		}
-
-		if ($options['limit']) {
-			$limit = sanitise_int($options['limit']);
-			$offset = sanitise_int($options['offset']);
-			$query .= " LIMIT $offset, $limit";
-		}
-
-		$dt = get_data($query, $options['callback']);
-		return $dt;
-	} else {
-		$result = get_data_row($query);
-		return $result->calculation;
-	}
-}
-
-/**
- * Returns an array of joins and wheres for use in annotations.
- *
- * @note The $pairs is reserved for name/value pairs if we want to implement those.
- *
- * @param string $table          The annotation table name or alias
- * @param array  $names          An array of names
- * @param array  $values         An array of values
- * @param array  $pairs          Name / value pairs. Not currently used.
- * @param bool   $case_sensitive Should name and values be case sensitive?
- *
- * @return array
- */
-function elgg_get_annotation_sql($table, $names = null, $values = null,
-	$pairs = null, $case_sensitive = false) {
-
-	if ((!$names && $names !== 0)
-		&& (!$values && $values !== 0)
-		&& (!$pairs && $pairs !== 0)) {
-
-		return '';
-	}
-
-	$db_prefix = elgg_get_config('dbprefix');
-
-	// join counter for incremental joins.
-	$i = 1;
-
-	// binary forces byte-to-byte comparision of strings, making
-	// it case- and diacritical-mark- sensitive.
-	// only supported on values.
-	$binary = ($case_sensitive) ? ' BINARY ' : '';
-
-	$access = get_access_sql_suffix($table);
-
-	$return = array (
-		'joins' => array (),
-		'wheres' => array()
-	);
-
-	$wheres = array();
-
-	// get names wheres and joins
-	$names_where = '';
-	if ($names !== NULL) {
-		if (!is_array($names)) {
-			$names = array($names);
-		}
-
-		$sanitised_names = array();
-		foreach ($names as $name) {
-			// normalise to 0.
-			if (!$name) {
-				$name = '0';
-			}
-			$sanitised_names[] = '\'' . sanitise_string($name) . '\'';
-		}
-
-		if ($names_str = implode(',', $sanitised_names)) {
-			$return['joins'][] = "JOIN {$db_prefix}metastrings msn on $table.name_id = msn.id";
-			$names_where = "(msn.string IN ($names_str))";
-		}
-	}
-
-	// get values wheres and joins
-	$values_where = '';
-	if ($values !== NULL) {
-		if (!is_array($values)) {
-			$values = array($values);
-		}
-
-		$sanitised_values = array();
-		foreach ($values as $value) {
-			// normalize to 0
-			if (!$value) {
-				$value = 0;
-			}
-			$sanitised_values[] = '\'' . sanitise_string($value) . '\'';
-		}
-
-		if ($values_str = implode(',', $sanitised_values)) {
-			$return['joins'][] = "JOIN {$db_prefix}metastrings msv on $table.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)";
-	}
-
-	if ($where = implode(' AND ', $wheres)) {
-		$return['wheres'][] = "($where)";
 	}
 
-	return $return;
+	return elgg_get_metastring_based_objects($options, 'annotations');
 }