Merge branch 'master' of github.com:Elgg/Elgg

1 files changed, 348 insertions, 88 deletions

diff --git a/engine/lib/deprecated-1.8.php b/engine/lib/deprecated-1.8.php
index bb52881cd..d92257a09 100644
--- a/engine/lib/deprecated-1.8.php
+++ b/engine/lib/deprecated-1.8.php
@@ -1,7 +1,83 @@
 <?php
 /**
- * @return str
+ * ***************************************************************************
+ * NOTE: If this is ever removed from Elgg, sites lose the ability to upgrade
+ * from 1.7.x and earlier to the latest version of Elgg without upgrading to
+ * 1.8 first.
+ * ***************************************************************************
+ *
+ * Upgrade the database schema in an ordered sequence.
+ *
+ * Executes all upgrade files in elgg/engine/schema/upgrades/ in sequential order.
+ * Upgrade files must be in the standard Elgg release format of YYYYMMDDII.sql
+ * where II is an incrementor starting from 01.
+ *
+ * Files that are < $version will be ignored.
+ *
+ * @warning Plugin authors should not call this function directly.
+ *
+ * @param int    $version The version you are upgrading from in the format YYYYMMDDII.
+ * @param string $fromdir Optional directory to load upgrades from. default: engine/schema/upgrades/
+ * @param bool   $quiet   If true, suppress all error messages. Only use for the upgrade from <=1.6.
+ *
+ * @return bool
+ * @see upgrade.php
+ * @see version.php
+ * @deprecated 1.8 Use PHP upgrades for sql changes.
+ */
+function db_upgrade($version, $fromdir = "", $quiet = FALSE) {
+	global $CONFIG;
+
+	elgg_deprecated_notice('db_upgrade() is deprecated by using PHP upgrades.', 1.8);
+
+	$version = (int) $version;
+
+	if (!$fromdir) {
+		$fromdir = $CONFIG->path . 'engine/schema/upgrades/';
+	}
+
+	if ($handle = opendir($fromdir)) {
+		$sqlupgrades = array();
+
+		while ($sqlfile = readdir($handle)) {
+			if (!is_dir($fromdir . $sqlfile)) {
+				if (preg_match('/^([0-9]{10})\.(sql)$/', $sqlfile, $matches)) {
+					$sql_version = (int) $matches[1];
+					if ($sql_version > $version) {
+						$sqlupgrades[] = $sqlfile;
+					}
+				}
+			}
+		}
+
+		asort($sqlupgrades);
+
+		if (sizeof($sqlupgrades) > 0) {
+			foreach ($sqlupgrades as $sqlfile) {
+
+				// hide all errors.
+				if ($quiet) {
+					try {
+						run_sql_script($fromdir . $sqlfile);
+					} catch (DatabaseException $e) {
+						error_log($e->getmessage());
+					}
+				} else {
+					run_sql_script($fromdir . $sqlfile);
+				}
+			}
+		}
+	}
+
+	return TRUE;
+}
+
+/**
+ * Lists entities from an access collection
+ *
  * @deprecated 1.8 Use elgg_list_entities_from_access_id()
+ *
+ * @return str
  */
 function list_entities_from_access_id($access_id, $entity_type = "", $entity_subtype = "", $owner_guid = 0, $limit = 10, $fullview = true, $listtypetoggle = true, $pagination = true) {
 
@@ -14,7 +90,14 @@ function list_entities_from_access_id($access_id, $entity_type = "", $entity_sub
 }
 
 /**
+ * Registers a particular action in memory
+ *
  * @deprecated 1.8 Use {@link elgg_register_action()} instead
+ *
+ * @param string $action The name of the action (eg "register", "account/settings/save")
+ * @param boolean $public Can this action be accessed by people not logged into the system?
+ * @param string $filename Optionally, the filename where this action is located
+ * @param boolean $admin_only Whether this action is only available to admin users.
  */
 function register_action($action, $public = false, $filename = "", $admin_only = false) {
 	elgg_deprecated_notice("register_action() was deprecated by elgg_register_action()", 1.8);
@@ -35,6 +118,8 @@ function register_action($action, $public = false, $filename = "", $admin_only =
  * This function extends the view "admin/main" with the provided view.
  * This view should provide a description and either a control or a link to.
  *
+ * @deprecated 1.8 Extend admin views manually
+ *
  * Usage:
  * 	- To add a control to the main admin panel then extend admin/main
  *  - To add a control to a new page create a page which renders a view admin/subpage
@@ -48,8 +133,6 @@ function register_action($action, $public = false, $filename = "", $admin_only =
  * @param string $view           The view to extend, by default this is 'admin/main'.
  * @param int    $priority       Optional priority to govern the appearance in the list.
  *
- * @deprecated 1.8 Extend admin views manually
- *
  * @return void
  */
 function extend_elgg_admin_page($new_admin_view, $view = 'admin/main', $priority = 500) {
@@ -115,7 +198,7 @@ function get_entities_from_annotations_calculate_x($sum = "sum", $entity_type =
 	$options['limit'] = $limit;
 	$options['offset'] = $offset;
 
-	$options['order_by'] = "calculation $orderdir";
+	$options['order_by'] = "annotation_calculation $orderdir";
 
 	$options['count'] = $count;
 
@@ -125,6 +208,12 @@ function get_entities_from_annotations_calculate_x($sum = "sum", $entity_type =
 /**
  * Returns entities ordered by the sum of an annotation
  *
+ * @warning This is function uses sum instead of count. THIS IS SLOW. See #3366.
+ *          This should be used when you have annotations with different values and you
+ *          want a list of entities ordered by the sum of all of those values.
+ *          If you want a list of entities ordered by the number of annotations on each entity,
+ *          use __get_entities_from_annotations_calculate_x() and pass 'count' as the first param.
+ *
  * @deprecated 1.8 Use elgg_get_entities_from_annotation_calculation()
  *
  * @param string $entity_type    Type of Entity
@@ -179,7 +268,7 @@ function get_entities_from_annotation_count($entity_type = "", $entity_subtype =
 	$options['limit'] = $limit;
 	$options['offset'] = $offset;
 
-	$options['order_by'] = "calculation $orderdir";
+	$options['order_by'] = "annotation_calculation $orderdir";
 
 	$options['count'] = $count;
 
@@ -241,7 +330,7 @@ function list_entities_from_annotation_count($entity_type = "", $entity_subtype
 
 	$options['limit'] = $limit;
 
-	$options['order_by'] = "calculation $orderdir";
+	$options['order_by'] = "annotation_calculation $orderdir";
 
 	return elgg_get_entities_from_annotation_calculation($options);
 }
@@ -249,6 +338,8 @@ function list_entities_from_annotation_count($entity_type = "", $entity_subtype
 /**
  * Adds an entry in $CONFIG[$register_name][$subregister_name].
  *
+ * @deprecated 1.8 Use the new menu system.
+ * 
  * This is only used for the site-wide menu.  See {@link add_menu()}.
  *
  * @param string $register_name     The name of the top-level register
@@ -257,7 +348,6 @@ function list_entities_from_annotation_count($entity_type = "", $entity_subtype
  * @param array  $children_array    Optionally, an array of children
  *
  * @return true|false Depending on success
- * @deprecated 1.8
  */
 function add_to_register($register_name, $subregister_name, $subregister_value, $children_array = array()) {
 	elgg_deprecated_notice("add_to_register() has been deprecated", 1.8);
@@ -290,6 +380,8 @@ function add_to_register($register_name, $subregister_name, $subregister_value,
 /**
  * Removes a register entry from $CONFIG[register_name][subregister_name]
  *
+ * @deprecated 1.8 Use the new menu system.
+ *
  * This is used to by {@link remove_menu()} to remove site-wide menu items.
  *
  * @param string $register_name    The name of the top-level register
@@ -297,7 +389,6 @@ function add_to_register($register_name, $subregister_name, $subregister_value,
  *
  * @return true|false Depending on success
  * @since 1.7.0
- * @deprecated 1.8
  */
 function remove_from_register($register_name, $subregister_name) {
 	elgg_deprecated_notice("remove_from_register() has been deprecated", 1.8);
@@ -326,10 +417,11 @@ function remove_from_register($register_name, $subregister_name) {
 /**
  * If it exists, returns a particular register as an array
  *
+ * @deprecated 1.8 Use the new menu system
+ *
  * @param string $register_name The name of the register
  *
  * @return array|false Depending on success
- * @deprecated 1.8
  */
 function get_register($register_name) {
 	elgg_deprecated_notice("get_register() has been deprecated", 1.8);
@@ -363,6 +455,8 @@ function get_register($register_name) {
  * Deprecated events core function. Code divided between elgg_register_event_handler()
  * and trigger_elgg_event().
  *
+ * @deprecated 1.8 Use explicit register/trigger event functions
+ *
  * @param string  $event       The type of event (eg 'init', 'update', 'delete')
  * @param string  $object_type The type of object (eg 'system', 'blog', 'user')
  * @param string  $function    The name of the function that will handle the event
@@ -371,7 +465,6 @@ function get_register($register_name) {
  * @param mixed   $object      Optionally, the object the event is being performed on (eg a user)
  *
  * @return true|false Depending on success
- * @deprecated 1.8 Use explicit register/trigger event functions
  */
 function events($event = "", $object_type = "", $function = "", $priority = 500, $call = false, $object = null) {
 
@@ -386,7 +479,14 @@ function events($event = "", $object_type = "", $function = "", $priority = 500,
 }
 
 /**
+ * Alias function for events, that registers a function to a particular kind of event
+ *
  * @deprecated 1.8 Use elgg_register_event_handler() instead
+ * 
+ * @param string $event The event type
+ * @param string $object_type The object type
+ * @param string $function The function name
+ * @return true|false Depending on success
  */
 function register_elgg_event_handler($event, $object_type, $callback, $priority = 500) {
 	elgg_deprecated_notice("register_elgg_event_handler() was deprecated by elgg_register_event_handler()", 1.8);
@@ -394,7 +494,14 @@ function register_elgg_event_handler($event, $object_type, $callback, $priority
 }
 
 /**
+ * Unregisters a function to a particular kind of event
+ * 
  * @deprecated 1.8 Use elgg_unregister_event_handler instead
+ *
+ * @param string $event The event type
+ * @param string $object_type The object type
+ * @param string $function The function name
+ * @since 1.7.0
  */
 function unregister_elgg_event_handler($event, $object_type, $callback) {
 	elgg_deprecated_notice('unregister_elgg_event_handler => elgg_unregister_event_handler', 1.8);
@@ -402,7 +509,14 @@ function unregister_elgg_event_handler($event, $object_type, $callback) {
 }
 
 /**
+ * Alias function for events, that triggers a particular kind of event
+ *
  * @deprecated 1.8 Use elgg_trigger_event() instead
+ * 
+ * @param string $event The event type
+ * @param string $object_type The object type
+ * @param string $function The function name
+ * @return true|false Depending on success
  */
 function trigger_elgg_event($event, $object_type, $object = null) {
 	elgg_deprecated_notice('trigger_elgg_event() was deprecated by elgg_trigger_event()', 1.8);
@@ -410,7 +524,29 @@ function trigger_elgg_event($event, $object_type, $object = null) {
 }
 
 /**
+ * Register a function to a plugin hook for a particular entity type, with a given priority.
+ *
  * @deprecated 1.8 Use elgg_register_plugin_hook_handler() instead
+ * 
+ * eg if you want the function "export_user" to be called when the hook "export" for "user" entities
+ * is run, use:
+ *
+ * 		register_plugin_hook("export", "user", "export_user");
+ *
+ * "all" is a valid value for both $hook and $entity_type. "none" is a valid value for $entity_type.
+ *
+ * The export_user function would then be defined as:
+ *
+ * 		function export_user($hook, $entity_type, $returnvalue, $params);
+ *
+ * Where $returnvalue is the return value returned by the last function returned by the hook, and
+ * $params is an array containing a set of parameters (or nothing).
+ *
+ * @param string $hook The name of the hook
+ * @param string $entity_type The name of the type of entity (eg "user", "object" etc)
+ * @param string $function The name of a valid function to be run
+ * @param string $priority The priority - 0 is first, 1000 last, default is 500
+ * @return true|false Depending on success
  */
 function register_plugin_hook($hook, $type, $callback, $priority = 500) {
 	elgg_deprecated_notice("register_plugin_hook() was deprecated by elgg_register_plugin_hook_handler()", 1.8);
@@ -418,7 +554,14 @@ function register_plugin_hook($hook, $type, $callback, $priority = 500) {
 }
 
 /**
+ * Unregister a function to a plugin hook for a particular entity type
+ *
  * @deprecated 1.8 Use elgg_unregister_plugin_hook_handler() instead
+ * 
+ * @param string $hook The name of the hook
+ * @param string $entity_type The name of the type of entity (eg "user", "object" etc)
+ * @param string $function The name of a valid function to be run
+ * @since 1.7.0
  */
 function unregister_plugin_hook($hook, $entity_type, $callback) {
 	elgg_deprecated_notice("unregister_plugin_hook() was deprecated by elgg_unregister_plugin_hook_handler()", 1.8);
@@ -426,7 +569,20 @@ function unregister_plugin_hook($hook, $entity_type, $callback) {
 }
 
 /**
+ * Triggers a plugin hook, with various parameters as an array. For example, to provide
+ * a 'foo' hook that concerns an entity of type 'bar', with a parameter called 'param1'
+ * with value 'value1', that by default returns true, you'd call:
+ *
  * @deprecated 1.8 Use elgg_trigger_plugin_hook() instead
+ *
+ * trigger_plugin_hook('foo', 'bar', array('param1' => 'value1'), true);
+ *
+ * @see register_plugin_hook
+ * @param string $hook The name of the hook to trigger
+ * @param string $entity_type The name of the entity type to trigger it for (or "all", or "none")
+ * @param array $params Any parameters. It's good practice to name the keys, i.e. by using array('name' => 'value', 'name2' => 'value2')
+ * @param mixed $returnvalue An initial return value
+ * @return mixed|null The cumulative return value for the plugin hook functions
  */
 function trigger_plugin_hook($hook, $type, $params = null, $returnvalue = null) {
 	elgg_deprecated_notice("trigger_plugin_hook() was deprecated by elgg_trigger_plugin_hook()", 1.8);
@@ -1667,7 +1823,7 @@ function get_installed_plugins($status = 'all') {
 		if ($include) {
 			$installed_plugins[$plugin->getID()] = array(
 				'active' => $plugin->isActive(),
-				'manifest' => $plugin->manifest->getManifest()
+				'manifest' => $plugin->getManifest()->getManifest()
 			);
 		}
 	}
@@ -2844,6 +3000,13 @@ $priority = 500) {
 }
 
 /**
+ * Returns a representation of a full 'page' (which might be an HTML page,
+ * RSS file, etc, depending on the current viewtype)
+ *
+ * @param string $title
+ * @param string $body
+ * @return string
+ *
  * @deprecated 1.8 Use elgg_view_page()
  */
 function page_draw($title, $body, $sidebar = "") {
@@ -3504,14 +3667,18 @@ $asc = false, $fullview = true, $listtypetoggle = false, $pagination = true, $or
 
 	$options['limit'] = $limit;
 
-	$options['order_by'] = "calculation $orderdir";
+	$options['order_by'] = "annotation_calculation $orderdir";
 
 	return elgg_get_entities_from_annotation_calculation($options);
 }
 
 /**
- * @deprecated 1.8
- * @see elgg_set_view_location()
+ * Set an alternative base location for a view (as opposed to the default of $CONFIG->viewpath)
+ *
+ * @param string $view The name of the view
+ * @param string $location The base location path
+ *
+ * @deprecated 1.8 Use elgg_set_view_location()
  */
 function set_view_location($view, $location, $viewtype = '') {
 	elgg_deprecated_notice("set_view_location() was deprecated by elgg_set_view_location()", 1.8);
@@ -3519,8 +3686,14 @@ function set_view_location($view, $location, $viewtype = '') {
 }
 
 /**
- * @deprecated 1.8
- * @see elgg_register_entity_url_handler()
+ * Sets the URL handler for a particular entity type and subtype
+ *
+ * @param string $function_name The function to register
+ * @param string $entity_type The entity type
+ * @param string $entity_subtype The entity subtype
+ * @return true|false Depending on success
+ *
+ * @deprecated 1.8 Use elgg_register_entity_url_handler()
  */
 function register_entity_url_handler($function_name, $entity_type = "all", $entity_subtype = "all") {
 	elgg_deprecated_notice("register_entity_url_handler() was deprecated by elgg_register_entity_url_handler()", 1.8);
@@ -3807,6 +3980,27 @@ function clear_annotations_by_owner($owner_guid) {
 }
 
 /**
+ * Registers a page handler for a particular identifier
+ *
+ * For example, you can register a function called 'blog_page_handler' for handler type 'blog'
+ * Now for all URLs of type http://yoururl/pg/blog/*, the blog_page_handler() function will be called.
+ * The part of the URL marked with * above will be exploded on '/' characters and passed as an
+ * array to that function.
+ * For example, the URL http://yoururl/blog/username/friends/ would result in the call:
+ * blog_page_handler(array('username','friends'), blog);
+ *
+ * Page handler functions should return true or the default page handler will be called.
+ *
+ * A request to register a page handler with the same identifier as previously registered
+ * handler will replace the previous one.
+ *
+ * The context is set to the page handler identifier before the registered
+ * page handler function is called. For the above example, the context is set to 'blog'.
+ *
+ * @param string $handler The page type to handle
+ * @param string $function Your function name
+ * @return true|false Depending on success
+ *
  * @deprecated 1.8 Use {@link elgg_register_page_handler()}
  */
 function register_page_handler($handler, $function){
@@ -3815,6 +4009,13 @@ function register_page_handler($handler, $function){
 }
 
 /**
+ * Unregister a page handler for an identifier
+ *
+ * Note: to replace a page handler, call register_page_handler()
+ *
+ * @param string $handler The page type identifier
+ * @since 1.7.2
+ * 
  * @deprecated 1.8 Use {@link elgg_unregister_page_handler()}
  */
 function unregister_page_handler($handler) {
@@ -3823,6 +4024,11 @@ function unregister_page_handler($handler) {
 }
 
 /**
+ * Register an annotation url handler.
+ *
+ * @param string $function_name The function.
+ * @param string $extender_name The name, default 'all'.
+ *
  * @deprecated 1.8 Use {@link elgg_register_annotation_url_handler()}
  */
 function register_annotation_url_handler($function, $extender_name) {
@@ -3831,6 +4037,15 @@ function register_annotation_url_handler($function, $extender_name) {
 }
 
 /**
+ * Sets the URL handler for a particular extender type and name.
+ * It is recommended that you do not call this directly, instead use one of the wrapper functions in the
+ * subtype files.
+ *
+ * @param string $function_name The function to register
+ * @param string $extender_type Extender type
+ * @param string $extender_name The name of the extender
+ * @return true|false Depending on success
+ *
  * @deprecated 1.8 Use {@link elgg_register_extender_url_handler()}
  */
 function register_extender_url_handler($function, $type = "all", $name = "all") {
@@ -3839,6 +4054,14 @@ function register_extender_url_handler($function, $type = "all", $name = "all")
 }
 
 /**
+ * Registers and entity type and subtype to return in search and other places.
+ * A description in the elgg_echo languages file of the form item:type:subtype
+ * is also expected.
+ *
+ * @param string $type The type of entity (object, site, user, group)
+ * @param string $subtype The subtype to register (may be blank)
+ * @return true|false Depending on success
+ * 
  * @deprecated 1.8 Use {@link elgg_register_entity_type()}
  */
 function register_entity_type($type, $subtype = null) {
@@ -3847,6 +4070,11 @@ function register_entity_type($type, $subtype = null) {
 }
 
 /**
+ * Register a metadata url handler.
+ *
+ * @param string $function_name The function.
+ * @param string $extender_name The name, default 'all'.
+ * 
  * @deprecated 1.8 Use {@link elgg_register_metadata_url_handler()}
  */
 function register_metadata_url_handler($function, $extender_name = "all") {
@@ -3854,7 +4082,12 @@ function register_metadata_url_handler($function, $extender_name = "all") {
 }
 
 /**
+ * Sets the URL handler for a particular relationship type
  *
+ * @param string $function_name The function to register
+ * @param string $relationship_type The relationship type.
+ * @return true|false Depending on success
+ * 
  * @deprecated 1.8 Use {@link elgg_register_relationship_url_handler()}
  */
 function register_relationship_url_handler($function_name, $relationship_type = "all") {
@@ -3863,6 +4096,15 @@ function register_relationship_url_handler($function_name, $relationship_type =
 }
 
 /**
+ * Registers a view to be simply cached
+ *
+ * Views cached in this manner must take no parameters and be login agnostic -
+ * that is to say, they look the same no matter who is logged in (or logged out).
+ *
+ * CSS and the basic jS views are automatically cached like this.
+ *
+ * @param string $viewname View name
+ *
  * @deprecated 1.8 Use {@link elgg_register_simplecache_view()}
  */
 function elgg_view_register_simplecache($viewname) {
@@ -3871,6 +4113,11 @@ function elgg_view_register_simplecache($viewname) {
 }
 
 /**
+ * Regenerates the simple cache.
+ *
+ * @param string $viewtype Optional viewtype to regenerate
+ * @see elgg_view_register_simplecache()
+ *
  * @deprecated 1.8 Use {@link elgg_regenerate_simplecache()}
  */
 function elgg_view_regenerate_simplecache($viewtype = NULL) {
@@ -3879,6 +4126,10 @@ function elgg_view_regenerate_simplecache($viewtype = NULL) {
 }
 
 /**
+ * Enables the simple cache.
+ *
+ * @see elgg_view_register_simplecache()
+ * 
  * @deprecated 1.8 Use {@link elgg_enable_simplecache()}
  */
 function elgg_view_enable_simplecache() {
@@ -3887,6 +4138,10 @@ function elgg_view_enable_simplecache() {
 }
 
 /**
+ * Disables the simple cache.
+ *
+ * @see elgg_view_register_simplecache()
+ * 
  * @deprecated 1.8 Use {@link elgg_disable_simplecache()}
  */
 function elgg_view_disable_simplecache() {
@@ -3912,6 +4167,22 @@ function is_installed() {
 }
 
 /**
+ * Attempt to authenticate.
+ * This function will process all registered PAM handlers or stop when the first
+ * handler fails. A handler fails by either returning false or throwing an
+ * exception. The advantage of throwing an exception is that it returns a message
+ * through the global $_PAM_HANDLERS_MSG which can be used in communication with
+ * a user. The order that handlers are processed is determined by the order that
+ * they were registered.
+ *
+ * If $credentials are provided the PAM handler should authenticate using the
+ * provided credentials, if not then credentials should be prompted for or
+ * otherwise retrieved (eg from the HTTP header or $_SESSION).
+ *
+ * @param mixed $credentials Mixed PAM handler specific credentials (e.g. username, password)
+ * @param string $policy - the policy type, default is "user"
+ * @return bool true if authenticated, false if not.
+ *
  * @deprecated 1.8 See {@link ElggPAM}
  */
 function pam_authenticate($credentials = NULL, $policy = "user") {
@@ -4375,6 +4646,11 @@ function using_widgets() {
 }
 
 /**
+ * Displays a particular widget
+ *
+ * @param ElggObject $widget The widget to display
+ * @return string The HTML for the widget, including JavaScript wrapper
+ * 
  * @deprecated 1.8
  */
 function display_widget(ElggObject $widget) {
@@ -4382,92 +4658,76 @@ function display_widget(ElggObject $widget) {
 	return elgg_view_entity($widget);
 }
 
-
 /**
- * ***************************************************************************
- * NOTE: If this is ever removed from Elgg, sites lose the ability to upgrade
- * from 1.7.x and earlier to the latest version of Elgg without upgrading to
- * 1.8 first.
- * ***************************************************************************
- *
- * Upgrade the database schema in an ordered sequence.
- *
- * Executes all upgrade files in elgg/engine/schema/upgrades/ in sequential order.
- * Upgrade files must be in the standard Elgg release format of YYYYMMDDII.sql
- * where II is an incrementor starting from 01.
- *
- * Files that are < $version will be ignored.
- *
- * @warning Plugin authors should not call this function directly.
- *
- * @param int    $version The version you are upgrading from in the format YYYYMMDDII.
- * @param string $fromdir Optional directory to load upgrades from. default: engine/schema/upgrades/
- * @param bool   $quiet   If true, suppress all error messages. Only use for the upgrade from <=1.6.
+ * Count the number of comments attached to an entity
  *
- * @return bool
- * @see upgrade.php
- * @see version.php
- * @deprecated 1.8 Use PHP upgrades for sql changes.
+ * @param ElggEntity $entity
+ * @return int Number of comments
  */
-function db_upgrade($version, $fromdir = "", $quiet = FALSE) {
-	global $CONFIG;
-
-	elgg_deprecated_notice('db_upgrade() is deprecated by using PHP upgrades.', 1.8);
-
-	$version = (int) $version;
+function elgg_count_comments($entity) {
+	elgg_deprecated_notice('elgg_count_comments() is deprecated by ElggEntity->countComments()', 1.8);
 
-	if (!$fromdir) {
-		$fromdir = $CONFIG->path . 'engine/schema/upgrades/';
+	if ($entity instanceof ElggEntity) {
+		return $entity->countComments();
 	}
 
-	if ($handle = opendir($fromdir)) {
-		$sqlupgrades = array();
-
-		while ($sqlfile = readdir($handle)) {
-			if (!is_dir($fromdir . $sqlfile)) {
-				if (preg_match('/^([0-9]{10})\.(sql)$/', $sqlfile, $matches)) {
-					$sql_version = (int) $matches[1];
-					if ($sql_version > $version) {
-						$sqlupgrades[] = $sqlfile;
-					}
-				}
-			}
-		}
+	return 0;
+}
 
-		asort($sqlupgrades);
+/**
+ * Removes all items relating to a particular acting entity from the river
+ *
+ * @param int $subject_guid The GUID of the entity
+ *
+ * @return bool Depending on success
+ * @deprecated 1.8 Use elgg_delete_river()
+ */
+function remove_from_river_by_subject($subject_guid) {
+	elgg_deprecated_notice("remove_from_river_by_subject() deprecated by elgg_delete_river()", 1.8);
 
-		if (sizeof($sqlupgrades) > 0) {
-			foreach ($sqlupgrades as $sqlfile) {
+	return elgg_delete_river(array('subject_guid' => $subject_guid));
+}
 
-				// hide all errors.
-				if ($quiet) {
-					try {
-						run_sql_script($fromdir . $sqlfile);
-					} catch (DatabaseException $e) {
-						error_log($e->getmessage());
-					}
-				} else {
-					run_sql_script($fromdir . $sqlfile);
-				}
-			}
-		}
-	}
+/**
+ * Removes all items relating to a particular entity being acted upon from the river
+ *
+ * @param int $object_guid The GUID of the entity
+ *
+ * @return bool Depending on success
+ * @deprecated 1.8 Use elgg_delete_river()
+ */
+function remove_from_river_by_object($object_guid) {
+	elgg_deprecated_notice("remove_from_river_by_object() deprecated by elgg_delete_river()", 1.8);
 
-	return TRUE;
+	return elgg_delete_river(array('object_guid' => $object_guid));
 }
 
 /**
- * Count the number of comments attached to an entity
+ * Removes all items relating to a particular annotation being acted upon from the river
  *
- * @param ElggEntity $entity
- * @return int Number of comments
+ * @param int $annotation_id The ID of the annotation
+ *
+ * @return bool Depending on success
+ * @since 1.7.0
+ * @deprecated 1.8 Use elgg_delete_river()
  */
-function elgg_count_comments($entity) {
-	elgg_deprecated_notice('elgg_count_comments() is deprecated by ElggEntity->countComments()', 1.8);
+function remove_from_river_by_annotation($annotation_id) {
+	elgg_deprecated_notice("remove_from_river_by_annotation() deprecated by elgg_delete_river()", 1.8);
 
-	if ($entity instanceof ElggEntity) {
-		return $entity->countComments();
-	}
+	return elgg_delete_river(array('annotation_id' => $annotation_id));
+}
 
-	return 0;
-}
\ No newline at end of file
+/**
+ * Removes a single river entry
+ *
+ * @param int $id The ID of the river entry
+ *
+ * @return bool Depending on success
+ * @since 1.7.2
+ * @deprecated 1.8 Use elgg_delete_river()
+ */
+function remove_from_river_by_id($id) {
+	elgg_deprecated_notice("remove_from_river_by_id() deprecated by elgg_delete_river()", 1.8);
+
+	return elgg_delete_river(array('id' => $id));
+}