Refs #2869, #2874. Renamed ElggPlugin::remove* functions to unset*. Added ElggPlugin::getAllUserSettings() and getAllSettings(). Deprecated all plugin settings and user setting functions with correctly named functions.

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

3 files changed, 277 insertions, 76 deletions

diff --git a/engine/classes/ElggPlugin.php b/engine/classes/ElggPlugin.php
index c57171eff..5ecdfdfd0 100644
--- a/engine/classes/ElggPlugin.php
+++ b/engine/classes/ElggPlugin.php
@@ -259,6 +259,46 @@ class ElggPlugin extends ElggObject {
 		return $this->$name;
 	}
 
+	/**
+	 * Returns an array of all settings saved for this plugin.
+	 *
+	 * @note Unlike user settings, plugin settings are not namespaced.
+	 *
+	 * @return array An array of key/value pairs.
+	 */
+	public function getAllSettings() {
+		if (!$this->guid) {
+			return false;
+		}
+
+		$db_prefix = elgg_get_config('dbprefix');
+		// need to remove all namespaced private settings.
+		$us_prefix = elgg_namespace_plugin_private_setting('user_setting', '', $this->getID());
+		$is_prefix = elgg_namespace_plugin_private_setting('internal', '', $this->getID());
+
+		// Get private settings for user
+		$q = "SELECT * FROM {$db_prefix}private_settings
+			WHERE entity_guid = $this->guid
+			AND name NOT LIKE '$us_prefix%'
+			AND name NOT LIKE '$is_prefix%'";
+
+		$private_settings = get_data($q);
+
+		if ($private_settings) {
+			$return = array();
+
+			foreach ($private_settings as $setting) {
+				$name = substr($setting->name, $ps_prefix_len);
+				$value = $setting->value;
+
+				$return[$name] = $value;
+			}
+
+			return $return;
+		}
+
+		return false;
+	}
 
 	/**
 	 * Set a plugin setting for the plugin
@@ -294,7 +334,7 @@ class ElggPlugin extends ElggObject {
 	 *
 	 * @return bool
 	 */
-	public function removeSetting($name) {
+	public function unsetSetting($name) {
 		return remove_private_setting($this->guid, $name);
 	}
 
@@ -306,7 +346,7 @@ class ElggPlugin extends ElggObject {
 	 * @todo If we could namespace the plugin settings this would be cleaner.
 	 * @return bool
 	 */
-	public function removeAllSettings() {
+	public function unsetAllSettings() {
 		$db_prefix = get_config('dbprefix');
 		$ps_prefix = elgg_namespace_plugin_private_setting('setting', '');
 
@@ -346,6 +386,55 @@ class ElggPlugin extends ElggObject {
 	}
 
 	/**
+	 * Returns an array of all user settings saved for this plugin for the user.
+	 *
+	 * @note Plugin settings are saved with a prefix. This removes that prefix.
+	 *
+	 * @param int $user_guid The user GUID. Defaults to logged in.
+	 * @return array An array of key/value pairs.
+	 */
+	public function getAllUserSettings($user_guid = null) {
+		$user_guid = (int)$user_guid;
+
+		if ($user_guid) {
+			$user = get_entity($user_guid);
+		} else {
+			$user = elgg_get_logged_in_user_entity();
+		}
+
+		if (!($user instanceof ElggUser)) {
+			return false;
+		}
+
+		$db_prefix = elgg_get_config('dbprefix');
+		// send an empty name so we just get the first part of the namespace
+		$ps_prefix = elgg_namespace_plugin_private_setting('user_setting', '', $this->getID());
+		$ps_prefix_len = strlen($ps_prefix);
+
+		// Get private settings for user
+		$q = "SELECT * FROM {$db_prefix}private_settings
+			WHERE entity_guid = {$user->guid}
+			AND name LIKE '$ps_prefix%'";
+
+		$private_settings = get_data($q);
+
+		if ($private_settings) {
+			$return = array();
+
+			foreach ($private_settings as $setting) {
+				$name = substr($setting->name, $ps_prefix_len);
+				$value = $setting->value;
+
+				$return[$name] = $value;
+			}
+
+			return $return;
+		}
+
+		return false;
+	}
+
+	/**
 	 * Sets a user setting for a plugin
 	 *
 	 * @param string $name      The setting name
@@ -390,7 +479,7 @@ class ElggPlugin extends ElggObject {
 	 * @param int    $user_guid The user GUID
 	 * @return bool
 	 */
-	public function removeUserSetting($name, $user_guid = null) {
+	public function unsetUserSetting($name, $user_guid = null) {
 		$user_guid = (int)$user_guid;
 
 		if ($user_guid) {
@@ -419,7 +508,7 @@ class ElggPlugin extends ElggObject {
 	 * @param int $user_guid The user GUID to remove user settings.
 	 * @return bool
 	 */
-	public function removeAllUserSettings($user_guid) {
+	public function unsetAllUserSettings($user_guid) {
 		$db_prefix = get_config('dbprefix');
 		$ps_prefix = elgg_namespace_plugin_private_setting('user_setting', '', $this->getID());
 
@@ -439,7 +528,7 @@ class ElggPlugin extends ElggObject {
 	 *
 	 * @return bool
 	 */
-	public function removeAllUsersSettings() {
+	public function unsetAllUsersSettings() {
 		$db_prefix = get_config('dbprefix');
 		$ps_prefix = elgg_namespace_plugin_private_setting('user_setting', '', $this->getID());
 
diff --git a/engine/lib/deprecated-1.8.php b/engine/lib/deprecated-1.8.php
index 67e150173..684e8f9b3 100644
--- a/engine/lib/deprecated-1.8.php
+++ b/engine/lib/deprecated-1.8.php
@@ -2946,4 +2946,154 @@ function isloggedin() {
 function isadminloggedin() {
 	elgg_deprecated_notice('isadminloggedin() is deprecated by elgg_is_admin_logged_in()', 1.8);
 	return elgg_is_admin_logged_in();
+}
+
+
+/**
+ * Loads plugins
+ *
+ * @deprecate 1.8 Use elgg_load_plugins()
+ *
+ * @return bool
+ */
+function load_plugins() {
+	elgg_deprecated_notice('load_plugins() is deprecated by elgg_load_plugins()', 1.8);
+	return elgg_load_plugins();
+}
+
+/**
+ * Find the plugin settings for a user.
+ *
+ * @param string $plugin_id Plugin name.
+ * @param int    $user_guid The guid who's settings to retrieve.
+ *
+ * @deprecated 1.8 Use elgg_get_all_plugin_user_settings() or ElggPlugin->getAllUserSettings()
+ * @return StdClass Object with all user settings.
+ */
+function find_plugin_usersettings($plugin_id = null, $user_guid = 0) {
+	elgg_deprecated_notice('find_plugin_usersettings() is deprecated by elgg_get_all_plugin_user_settings()', 1.8);
+
+	$settings = elgg_get_all_plugin_user_settings($user_guid, $plugin_id);
+	$return = false;
+
+	if ($settings) {
+		$return = new stdClass;
+
+		foreach ($settings as $k => $v) {
+			$return->$k = $v;
+		}
+	}
+
+	return $return;
+}
+
+/**
+ * Set a user specific setting for a plugin.
+ *
+ * @param string $name      The name - note, can't be "title".
+ * @param mixed  $value     The value.
+ * @param int    $user_guid Optional user.
+ * @param string $plugin_id Optional plugin name, if not specified then it
+ *                          is detected from where you are calling from.
+ *
+ * @return bool
+ * @deprecated 1.8 Use elgg_set_plugin_user_setting() or ElggPlugin->setUserSetting()
+ */
+function set_plugin_usersetting($name, $value, $user_guid = 0, $plugin_id = "") {
+	elgg_deprecated_notice('find_plugin_usersettings() is deprecated by elgg_get_all_plugin_user_settings()', 1.8);
+	return elgg_set_plugin_user_setting($name, $value, $user_guid, $plugin_id);
+}
+
+/**
+ * Clears a user-specific plugin setting
+ *
+ * @param str $name      Name of the plugin setting
+ * @param int $user_guid Defaults to logged in user
+ * @param str $plugin_id Defaults to contextual plugin name
+ *
+ * @deprecated 1.8 Use elgg_unset_plugin_user_setting or ElggPlugin->unsetUserSetting().
+ * @return bool Success
+ */
+function clear_plugin_usersetting($name, $user_guid = 0, $plugin_id = '') {
+	elgg_deprecated_notice('clear_plugin_usersetting() is deprecated by elgg_unset_plugin_usersetting()', 1.8);
+	return elgg_unset_plugin_user_setting($name, $user_guid, $plugin_id);
+}
+
+/**
+ * Get a user specific setting for a plugin.
+ *
+ * @param string $name      The name.
+ * @param int    $user_guid Guid of owning user
+ * @param string $plugin_id Optional plugin name, if not specified
+ *                          it is detected from where you are calling.
+ *
+ * @deprecated 1.8 Use elgg_get_plugin_user_setting() or ElggPlugin->getUserSetting()
+ * @return mixed
+ */
+function get_plugin_usersetting($name, $user_guid = 0, $plugin_id = "") {
+	elgg_deprecated_notice('get_plugin_usersetting() is deprecated by elgg_get_plugin_user_setting()', 1.8);
+	return elgg_get_plugin_user_setting($name, $user_guid, $plugin_id);
+}
+
+
+/**
+ * Set a setting for a plugin.
+ *
+ * @param string $name      The name - note, can't be "title".
+ * @param mixed  $value     The value.
+ * @param string $plugin_id Optional plugin name, if not specified
+ *                          then it is detected from where you are calling from.
+ *
+ * @deprecated 1.8 Use elgg_set_plugin_setting() or ElggPlugin->setSetting()
+ * @return int|false
+ */
+function set_plugin_setting($name, $value, $plugin_id = null) {
+	elgg_deprecated_notice('set_plugin_setting() is deprecated by elgg_set_plugin_setting()', 1.8);
+	return elgg_set_plugin_setting($name, $value, $plugin_id);
+}
+
+/**
+ * Get setting for a plugin.
+ *
+ * @param string $name      The name.
+ * @param string $plugin_id Optional plugin name, if not specified
+ *                          then it is detected from where you are calling from.
+ *
+ * @deprecated 1.8 Use elgg_get_plugin_setting() or ElggPlugin->getSetting()
+ * @return mixed
+ */
+function get_plugin_setting($name, $plugin_id = "") {
+	elgg_deprecated_notice('get_plugin_setting() is deprecated by elgg_get_plugin_setting()', 1.8);
+	return elgg_get_plugin_setting($name, $plugin_id);
+}
+
+/**
+ * Clear a plugin setting.
+ *
+ * @param string $name      The name.
+ * @param string $plugin_id Optional plugin name, if not specified
+ *                          then it is detected from where you are calling from.
+ *
+ * @deprecated 1.8 Use elgg_unset_plugin_setting() or ElggPlugin->unsetSetting()
+ * @return bool
+ */
+function clear_plugin_setting($name, $plugin_id = "") {
+	elgg_deprecated_notice('clear_plugin_setting() is deprecated by elgg_unset_plugin_setting()', 1.8);
+	return elgg_unset_plugin_setting($name, $plugin_id);
+}
+
+
+/**
+ * Unsets all plugin settings for a plugin.
+ *
+ * @param string $plugin_id Optional plugin name, if not specified
+ *                          then it is detected from where you are calling from.
+ *
+ * @return bool
+ * @deprecated 1.8 Use elgg_unset_all_plugin_settings() or ElggPlugin->unsetAllSettings()
+ * @since 1.7.0
+ */
+function clear_all_plugin_settings($plugin_id = "") {
+	elgg_deprecated_notice('clear_all_plugin_settings() is deprecated by elgg_unset_all_plugin_setting()', 1.8);
+	return elgg_unset_all_plugin_settings($plugin_id);
 }
\ No newline at end of file
diff --git a/engine/lib/plugins.php b/engine/lib/plugins.php
index 1605ed76f..fc3dc8006 100644
--- a/engine/lib/plugins.php
+++ b/engine/lib/plugins.php
@@ -177,18 +177,18 @@ function elgg_generate_plugin_entities() {
 /**
  * Returns an ElggPlugin object with the path $path.
  *
- * @param string $id The id (dir name) of the plugin. NOT the guid.
+ * @param string $plugin_id The id (dir name) of the plugin. NOT the guid.
  * @return mixed ElggPlugin or false.
  */
-function elgg_get_plugin_from_id($id) {
-	$id = sanitize_string($id);
+function elgg_get_plugin_from_id($plugin_id) {
+	$plugin_id = sanitize_string($plugin_id);
 	$db_prefix = get_config('dbprefix');
 
 	$options = array(
 		'type' => 'object',
 		'subtype' => 'plugin',
 		'joins' => array("JOIN {$db_prefix}objects_entity oe on oe.guid = e.guid"),
-		'wheres' => array("oe.title = '$id'"),
+		'wheres' => array("oe.title = '$plugin_id'"),
 		'limit' => 1
 	);
 
@@ -476,19 +476,6 @@ function elgg_reindex_plugin_priorities() {
 }
 
 /**
- * Loads plugins
- *
- * @deprecate 1.8
- *
- * @return bool
- */
-function load_plugins() {
-	elgg_deprecated_notice('load_plugins() is deprecated by elgg_load_plugins()', 1.8);
-
-	return elgg_load_plugins();
-}
-
-/**
  * Namespaces a string to be used as a private setting for a plugin.
  *
  * @param string $type The type of value: user_setting or internal.
@@ -783,51 +770,26 @@ function elgg_get_calling_plugin_entity() {
 }
 
 /**
- * Find the plugin settings for a user.
+ * Returns an array of all plugin settings for a user.
  *
- * @param string $plugin_id Plugin name.
- * @param int    $user_guid The guid who's settings to retrieve.
+ * @param mixed  $user_guid The user GUID or null for the currently logged in user.
+ * @param string $plugin_id The plugin ID
+ * @return array
  *
- * @return StdClass Object with all user settings.
+ * @since 1.8
  */
-function find_plugin_usersettings($plugin_id = null, $user_guid = 0) {
-	$plugin_id = sanitise_string($plugin_id);
-	$user_guid = (int)$user_guid;
-	$db_prefix = elgg_get_config('dbprefix');
-	$ps_prefix = elgg_namespace_plugin_private_setting('user_setting', "$plugin_id:");
-	$ps_prefix_len = strlen($ps_prefix);
-
-	if (!$plugin_id) {
-		$plugin_id = elgg_get_calling_plugin_id();
-	}
-
-	if ($user_guid == 0) {
-		$user_guid = elgg_get_logged_in_user_guid();
+function elgg_get_all_plugin_user_settings($user_guid = null, $plugin_id = null) {
+	if ($plugin_id) {
+		$plugin = elgg_get_plugin_from_id($plugin_id);
+	} else {
+		$plugin = elgg_get_calling_plugin_entity();
 	}
 
-	// Get private settings for user
-	$q = "SELECT * FROM {$db_prefix}private_settings
-		WHERE entity_guid = $user_guid
-		AND name LIKE '$ps_prefix$plugin_id'";
-
-	$private_settings = get_data($q);
-	if ($private_settings) {
-		$return = new stdClass;
-
-		foreach ($private_settings as $setting) {
-			$name = substr($setting->name, $ps_prefix_len);
-			$value = $setting->value;
-
-			// @todo why?
-			if (strpos($key, $ps_prefix) === 0) {
-				$return->$name = $value;
-			}
-		}
-
-		return $return;
+	if (!$plugin instanceof ElggPlugin) {
+		return false;
 	}
 
-	return false;
+	return $plugin->getAllUserSettings($user_guid);
 }
 
 /**
@@ -841,7 +803,7 @@ function find_plugin_usersettings($plugin_id = null, $user_guid = 0) {
  *
  * @return bool
  */
-function set_plugin_usersetting($name, $value, $user_guid = 0, $plugin_id = "") {
+function elgg_set_plugin_user_setting($name, $value, $user_guid = null, $plugin_id = null) {
 	if ($plugin_id) {
 		$plugin = elgg_get_plugin_from_id($plugin_id);
 	} else {
@@ -856,7 +818,7 @@ function set_plugin_usersetting($name, $value, $user_guid = 0, $plugin_id = "")
 }
 
 /**
- * Clears a user-specific plugin setting
+ * Unsets a user-specific plugin setting
  *
  * @param str $name      Name of the plugin setting
  * @param int $user_guid Defaults to logged in user
@@ -864,7 +826,7 @@ function set_plugin_usersetting($name, $value, $user_guid = 0, $plugin_id = "")
  *
  * @return bool Success
  */
-function clear_plugin_usersetting($name, $user_guid = 0, $plugin_id = '') {
+function elgg_unset_plugin_user_setting($name, $user_guid = null, $plugin_id = null) {
 	if ($plugin_id) {
 		$plugin = elgg_get_plugin_from_id($plugin_id);
 	} else {
@@ -875,7 +837,7 @@ function clear_plugin_usersetting($name, $user_guid = 0, $plugin_id = '') {
 		return false;
 	}
 
-	return $plugin->removeUserSetting($name, $user_guid);
+	return $plugin->unsetUserSetting($name, $user_guid);
 }
 
 /**
@@ -888,7 +850,7 @@ function clear_plugin_usersetting($name, $user_guid = 0, $plugin_id = '') {
  *
  * @return mixed
  */
-function get_plugin_usersetting($name, $user_guid = 0, $plugin_id = "") {
+function elgg_get_plugin_user_setting($name, $user_guid = null, $plugin_id = null) {
 	if ($plugin_id) {
 		$plugin = elgg_get_plugin_from_id($plugin_id);
 	} else {
@@ -912,7 +874,7 @@ function get_plugin_usersetting($name, $user_guid = 0, $plugin_id = "") {
  *
  * @return int|false
  */
-function set_plugin_setting($name, $value, $plugin_id = null) {
+function elgg_set_plugin_setting($name, $value, $plugin_id = null) {
 	if ($plugin_id) {
 		$plugin = elgg_get_plugin_from_id($plugin_id);
 	} else {
@@ -935,7 +897,7 @@ function set_plugin_setting($name, $value, $plugin_id = null) {
  *
  * @return mixed
  */
-function get_plugin_setting($name, $plugin_id = "") {
+function elgg_get_plugin_setting($name, $plugin_id = null) {
 	if ($plugin_id) {
 		$plugin = elgg_get_plugin_from_id($plugin_id);
 	} else {
@@ -950,7 +912,7 @@ function get_plugin_setting($name, $plugin_id = "") {
 }
 
 /**
- * Clear a plugin setting.
+ * Unsets a plugin setting.
  *
  * @param string $name      The name.
  * @param string $plugin_id Optional plugin name, if not specified
@@ -958,7 +920,7 @@ function get_plugin_setting($name, $plugin_id = "") {
  *
  * @return bool
  */
-function clear_plugin_setting($name, $plugin_id = "") {
+function elgg_unset_plugin_setting($name, $plugin_id = null) {
 	if ($plugin_id) {
 		$plugin = elgg_get_plugin_from_id($plugin_id);
 	} else {
@@ -969,30 +931,30 @@ function clear_plugin_setting($name, $plugin_id = "") {
 		return false;
 	}
 
-	return $plugin->removeSetting($name);
+	return $plugin->unsetSetting($name);
 }
 
 /**
- * Clear all plugin settings.
+ * Unsets all plugin settings for a plugin.
  *
  * @param string $plugin_id Optional plugin name, if not specified
  *                          then it is detected from where you are calling from.
  *
  * @return bool
- * @since 1.7.0
+ * @since 1.8
  */
-function clear_all_plugin_settings($plugin_id = "") {
+function elgg_unset_all_plugin_settings($plugin_id = null) {
 	if ($plugin_id) {
 		$plugin = elgg_get_plugin_from_id($plugin_id);
 	} else {
 		$plugin = elgg_get_calling_plugin_entity();
 	}
 
-	if ($plugin) {
-		$plugin->removeAllSettings();
+	if (!$plugin) {
+		return false;
 	}
 
-	return false;
+	return $plugin->unsetAllSettings();
 }
 
 /**