Refs #1523: elgg_get_entities() uses the constants for defaults and conditionals. Added some tests to check for no subtypes. Updated the documentation.

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

4 files changed, 152 insertions, 50 deletions

diff --git a/engine/lib/elgglib.php b/engine/lib/elgglib.php
index 328316686..43dba4a43 100644
--- a/engine/lib/elgglib.php
+++ b/engine/lib/elgglib.php
@@ -2327,7 +2327,10 @@ function elgg_normalise_plural_options_array($options, $singulars) {
 		$plural = $singular . 's';
 
 		// normalize the singular to plural
-		if (isset($options[$singular]) && $options[$singular] !== NULL && $options[$singular] !== FALSE) {
+		// isset() returns FALSE for array values of NULL, so they are ignored.
+		// everything else falsy is included.
+		//if (isset($options[$singular]) && $options[$singular] !== NULL && $options[$singular] !== FALSE) {
+		if (isset($options[$singular])) {
 			if (isset($options[$plural])) {
 				if (is_array($options[$plural])) {
 					$options[$plural][] = $options[$singlar];
@@ -2338,7 +2341,7 @@ function elgg_normalise_plural_options_array($options, $singulars) {
 				$options[$plural] = array($options[$singular]);
 			}
 		}
-		$options[$singular] = NULL;
+		unset($options[$singular]);
 	}
 
 	return $options;
@@ -2731,12 +2734,15 @@ function elgg_api_test($hook, $type, $value, $params) {
 /**
  * Some useful constant definitions
  */
-define('ACCESS_DEFAULT',-1);
-define('ACCESS_PRIVATE',0);
-define('ACCESS_LOGGED_IN',1);
-define('ACCESS_PUBLIC',2);
-define('ACCESS_FRIENDS',-2);
+define('ACCESS_DEFAULT', -1);
+define('ACCESS_PRIVATE', 0);
+define('ACCESS_LOGGED_IN', 1);
+define('ACCESS_PUBLIC', 2);
+define('ACCESS_FRIENDS', -2);
 
-register_elgg_event_handler('init','system','elgg_init');
-register_elgg_event_handler('boot','system','elgg_boot',1000);
+define('ELGG_ENTITIES_ANY_VALUE', NULL);
+define('ELGG_ENTITIES_NO_VALUE', 0);
+
+register_elgg_event_handler('init', 'system', 'elgg_init');
+register_elgg_event_handler('boot', 'system', 'elgg_boot', 1000);
 register_plugin_hook('unit_test', 'system', 'elgg_api_test');
\ No newline at end of file
diff --git a/engine/lib/entities.php b/engine/lib/entities.php
index 712404179..8a532b275 100644
--- a/engine/lib/entities.php
+++ b/engine/lib/entities.php
@@ -1697,7 +1697,9 @@ function get_entity($guid) {
 
 
 /**
- * Get all entities.
+ * Get all entities.  NB: Plural arguments can be written as
+ * singular if only specifying a single element.  (e.g., 'type' => 'object'
+ * vs 'types' => array('object')).
  *
  * @param array $options Array in format:
  *
@@ -1739,35 +1741,31 @@ function get_entity($guid) {
 function elgg_get_entities(array $options = array()) {
 	global $CONFIG;
 
-	//@todo allow use of singular types that rewrite to plural ones.
 	$defaults = array(
-		'type' => NULL,
-		'types' => NULL,
-		'subtypes' => NULL,
-		'subtype' => NULL,
-		'type_subtype_pairs' => NULL,
-		'owner_guids' => NULL,
-		'owner_guid' => NULL,
-		'container_guids' => NULL,
-		'container_guid' => NULL,
-		'site_guids' => $CONFIG->site_guid,
-		'site_guid' => NULL,
-
-		'modified_time_lower' => NULL,
-		'modified_time_upper' => NULL,
-		'created_time_lower' => NULL,
-		'created_time_upper' => NULL,
-
-		'order_by' => 'e.time_created desc',
-		'group_by' => NULL,
-		'limit' => 10,
-		'offset' => 0,
-		'count' => FALSE,
-		'selects' => array(),
-		'wheres' => array(),
-		'joins' => array()
+		'types'					=>	ELGG_ENTITIES_ANY_VALUE,
+		'subtypes'				=>	ELGG_ENTITIES_ANY_VALUE,
+		'type_subtype_pairs'	=>	ELGG_ENTITIES_ANY_VALUE,
+
+		'owner_guids'			=>	ELGG_ENTITIES_ANY_VALUE,
+		'container_guids'		=>	ELGG_ENTITIES_ANY_VALUE,
+		'site_guids'			=>	$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,
+
+		'order_by' 				=>	'e.time_created desc',
+		'group_by'				=>	ELGG_ENTITIES_ANY_VALUE,
+		'limit'					=>	10,
+		'offset'				=>	0,
+		'count'					=>	FALSE,
+		'selects'				=>	array(),
+		'wheres'				=>	array(),
+		'joins'					=>	array()
 	);
 
+
 	$options = array_merge($defaults, $options);
 
 	$singulars = array('type', 'subtype', 'owner_guid', 'container_guid', 'site_guid');
@@ -2019,19 +2017,18 @@ function elgg_get_entity_type_subtype_where_sql($table, $types, $subtypes, $pair
 		foreach ($types as $type) {
 			$subtype_ids = array();
 			if ($subtypes) {
-				// subtypes can be NULL or '' or 0, which means "no subtype"
 				foreach ($subtypes as $subtype) {
-					// if a subtype is sent that doesn't exist
-					if (0 === $subtype || $subtype_id = get_subtype_id($type, $subtype)) {
-						$subtype_ids[] = (0 === $subtype) ? 0 : $subtype_id;
+					// check that the subtype is valid (with ELGG_ENTITIES_NO_VALUE being a valid subtype)
+					if (ELGG_ENTITIES_NO_VALUE === $subtype || $subtype_id = get_subtype_id($type, $subtype)) {
+						$subtype_ids[] = (ELGG_ENTITIES_NO_VALUE === $subtype) ? ELGG_ENTITIES_NO_VALUE : $subtype_id;
 					} else {
 						$valid_subtypes_count--;
 						elgg_log("Type-subtype $type:$subtype' does not exist!", 'WARNING');
-						// return false if we're all invalid subtypes in the only valid type
 						continue;
 					}
 				}
 
+				// return false if we're all invalid subtypes in the only valid type
 				if ($valid_subtypes_count <= 0) {
 					return FALSE;
 				}
@@ -2073,8 +2070,8 @@ function elgg_get_entity_type_subtype_where_sql($table, $types, $subtypes, $pair
 			if (is_array($paired_subtypes)) {
 				$paired_subtype_ids = array();
 				foreach ($paired_subtypes as $paired_subtype) {
-					if ($paired_subtype && ($paired_subtype_id = get_subtype_id($paired_type, $paired_subtype))) {
-						$paired_subtype_ids[] = $paired_subtype_id;
+					if (ELGG_ENTITIES_NO_VALUE === $paired_subtype || ($paired_subtype_id = get_subtype_id($paired_type, $paired_subtype))) {
+						$paired_subtype_ids[] = (ELGG_ENTITIES_NO_VALUE === $paired_subtype) ? ELGG_ENTITIES_NO_VALUE : $paired_subtype_id;
 					} else {
 						$valid_pairs_subtypes_count--;
 						elgg_log("Type-subtype $paired_type:$paired_subtype' does not exist!", 'WARNING');
diff --git a/engine/lib/metadata.php b/engine/lib/metadata.php
index 70f582b4b..159e9187a 100644
--- a/engine/lib/metadata.php
+++ b/engine/lib/metadata.php
@@ -535,8 +535,11 @@ function find_metadata($meta_name = "", $meta_value = "", $entity_type = "", $en
 
 
 /**
- * Returns entities based upon metadata.
+ * Returns entities based upon metadata.  Also accepts all
+ * options available to elgg_get_entities().  Supports
+ * the singular option shortcut.
  *
+ * @see elgg_get_entities
  * @param array $options Array in format:
  *
  * 	metadata_names => NULL|ARR metadata names
@@ -553,12 +556,10 @@ function find_metadata($meta_name = "", $meta_value = "", $entity_type = "", $en
  */
 function elgg_get_entities_from_metadata(array $options = array()) {
 	$defaults = array(
-		'metadata_names' => NULL,
-		'metadata_name' => NULL,
-		'metadata_values' => NULL,
-		'metadata_value' => NULL,
-		'metadata_name_value_pair' => NULL,
-		'metadata_name_value_pairs' => NULL,
+		'metadata_names'			=>	ELGG_ENTITIES_ANY_VALUE,
+		'metadata_values'			=>	ELGG_ENTITIES_ANY_VALUE,
+		'metadata_name_value_pairs'	=>	ELGG_ENTITIES_ANY_VALUE,
+
 		'metadata_name_value_pairs_operator' => 'AND',
 		'metadata_case_sensitive' => TRUE
 	);
diff --git a/engine/tests/api/entity_getter_functions.php b/engine/tests/api/entity_getter_functions.php
index f3f892d79..c4706d3df 100644
--- a/engine/tests/api/entity_getter_functions.php
+++ b/engine/tests/api/entity_getter_functions.php
@@ -824,4 +824,102 @@ class ElggCoreEntityGetterFunctionsTest extends ElggCoreUnitTest {
 		$es = elgg_get_entities($options);
 		$this->assertFalse($es);
 	}
+
+
+
+
+
+
+	public function testElggApiGettersEntityNoSubtype() {
+		// create an entity we can later delete.
+		// order by time created and limit by 1 should == this entity.
+
+		$e = new ElggObject();
+		$e->save();
+
+		$options = array(
+			'type' => 'object',
+			'limit' => 1,
+			'order_by' => 'e.time_created desc'
+		);
+
+		// grab ourself again to fill out attributes.
+		$e = get_entity($e->getGUID());
+
+		$entities = elgg_get_entities($options);
+
+		$this->assertEqual(count($entities), 1);
+
+		foreach ($entities as $entity) {
+			$this->assertIdentical($e->getGUID(), $entity->getGUID());
+		}
+
+		$e->delete();
+	}
+
+	public function testElggApiGettersEntityNoValueSubtypeNotSet() {
+		// create an entity we can later delete.
+		// order by time created and limit by 1 should == this entity.
+
+		$e = new ElggObject();
+		$e->save();
+
+		$options = array(
+			'type' => 'object',
+			'subtype' => ELGG_ENTITY_NO_VALUE,
+			'limit' => 1,
+			'order_by' => 'e.time_created desc'
+		);
+
+		// grab ourself again to fill out attributes.
+		$e = get_entity($e->getGUID());
+
+		$entities = elgg_get_entities($options);
+
+		$this->assertEqual(count($entities), 1);
+
+		foreach ($entities as $entity) {
+			$this->assertIdentical($e->getGUID(), $entity->getGUID());
+		}
+
+		$e->delete();
+	}
+
+	public function testElggApiGettersEntityNoValueSubtypeSet() {
+		global $CONFIG;
+		// create an entity we can later delete.
+		// order by time created and limit by 1 should == this entity.
+
+		$subtype = 'subtype_' . rand();
+
+		$e = new ElggObject();
+		$e->subtype = $subtype;
+		$e->save();
+
+		$options = array(
+			'type' => 'object',
+			'subtype' => ELGG_ENTITIES_NO_VALUE,
+			'limit' => 1,
+			'order_by' => 'e.time_created desc'
+		);
+
+		// grab ourself again to fill out attributes.
+		$e = get_entity($e->getGUID());
+
+		$entities = elgg_get_entities($options);
+
+		$this->assertEqual(count($entities), 1);
+
+		// this entity should NOT be the entity we just created
+		// and should have no subtype
+		foreach ($entities as $entity) {
+			$this->assertNotEqual($e->getGUID(), $entity->getGUID());
+			$this->assertEqual($entity->subtype_id, 0);
+		}
+
+		$e->delete();
+
+		$q = "DELETE FROM {$CONFIG->dbprefix}entity_subtypes WHERE subtype = '$subtype'";
+		delete_data($q);
+	}
 }