Standardized code in all of core, not including language files, tests, or core mods.

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

1 files changed, 97 insertions, 46 deletions

diff --git a/engine/classes/ElggUser.php b/engine/classes/ElggUser.php
index 3bd93bba2..380fc4e8b 100644
--- a/engine/classes/ElggUser.php
+++ b/engine/classes/ElggUser.php
@@ -4,8 +4,8 @@
  *
  * Representation of a "user" in the system.
  *
- * @package Elgg
- * @subpackage Core
+ * @package    Elgg.Core
+ * @subpackage DataModel.User
  */
 class ElggUser extends ElggEntity
 	implements Friendable {
@@ -14,9 +14,27 @@ class ElggUser extends ElggEntity
 	 * This is vital to distinguish between metadata and base parameters.
 	 *
 	 * Place your base parameters here.
+	 *
+	 * @deprecated 1.8 Use ElggUser::initializeAttributes()
+	 *
+	 * @return void
 	 */
 	protected function initialise_attributes() {
-		parent::initialise_attributes();
+		elgg_deprecated_notice('ElggUser::initialise_attributes() is deprecated by ::initializeAttributes()', 1.8);
+
+		return $this->initializeAttributes();
+	}
+
+		/**
+	 * Initialise the attributes array.
+	 * This is vital to distinguish between metadata and base parameters.
+	 *
+	 * Place your base parameters here.
+	 *
+	 * @return void
+	 */
+	protected function initializeAttributes() {
+		parent::initializeAttributes();
 
 		$this->attributes['type'] = "user";
 		$this->attributes['name'] = "";
@@ -36,6 +54,7 @@ class ElggUser extends ElggEntity
 	 *
 	 * @param mixed $guid If an int, load that GUID.
 	 * 	If a db row then will attempt to load the rest of the data.
+	 *
 	 * @throws Exception if there was a problem creating the user.
 	 */
 	function __construct($guid = null) {
@@ -46,40 +65,35 @@ class ElggUser extends ElggEntity
 			if ($guid instanceof stdClass) {
 				// Load the rest
 				if (!$this->load($guid->guid)) {
-					throw new IOException(sprintf(elgg_echo('IOException:FailedToLoadGUID'), get_class(), $guid->guid));
+					$msg = sprintf(elgg_echo('IOException:FailedToLoadGUID'), get_class(), $guid->guid);
+					throw new IOException($msg);
 				}
-			}
 
-			// See if this is a username
-			else if (is_string($guid)) {
+				// See if this is a username
+			} else if (is_string($guid)) {
 				$guid = get_user_by_username($guid);
 				foreach ($guid->attributes as $key => $value) {
 					$this->attributes[$key] = $value;
 				}
-			}
 
-			// Is $guid is an ElggUser? Use a copy constructor
-			else if ($guid instanceof ElggUser) {
+				// Is $guid is an ElggUser? Use a copy constructor
+			} else if ($guid instanceof ElggUser) {
 				elgg_deprecated_notice('This type of usage of the ElggUser constructor was deprecated. Please use the clone method.', 1.7);
 
 				foreach ($guid->attributes as $key => $value) {
 					$this->attributes[$key] = $value;
 				}
-			}
 
-			// Is this is an ElggEntity but not an ElggUser = ERROR!
-			else if ($guid instanceof ElggEntity) {
+				// Is this is an ElggEntity but not an ElggUser = ERROR!
+			} else if ($guid instanceof ElggEntity) {
 				throw new InvalidParameterException(elgg_echo('InvalidParameterException:NonElggUser'));
-			}
 
-			// We assume if we have got this far, $guid is an int
-			else if (is_numeric($guid)) {
+				// We assume if we have got this far, $guid is an int
+			} else if (is_numeric($guid)) {
 				if (!$this->load($guid)) {
 					throw new IOException(sprintf(elgg_echo('IOException:FailedToLoadGUID'), get_class(), $guid));
 				}
-			}
-
-			else {
+			} else {
 				throw new InvalidParameterException(elgg_echo('InvalidParameterException:UnrecognisedValue'));
 			}
 		}
@@ -90,7 +104,8 @@ class ElggUser extends ElggEntity
 	 * This function will ensure that all data is loaded (were possible), so
 	 * if only part of the ElggUser is loaded, it'll load the rest.
 	 *
-	 * @param int $guid
+	 * @param int $guid ElggUser GUID
+	 *
 	 * @return true|false
 	 */
 	protected function load($guid) {
@@ -100,8 +115,9 @@ class ElggUser extends ElggEntity
 		}
 
 		// Check the type
-		if ($this->attributes['type']!='user') {
-			throw new InvalidClassException(sprintf(elgg_echo('InvalidClassException:NotValidElggStar'), $guid, get_class()));
+		if ($this->attributes['type'] != 'user') {
+			$msg = sprintf(elgg_echo('InvalidClassException:NotValidElggStar'), $guid, get_class());
+			throw new InvalidClassException($msg);
 		}
 
 		// Load missing data
@@ -113,7 +129,7 @@ class ElggUser extends ElggEntity
 
 		// Now put these into the attributes array as core values
 		$objarray = (array) $row;
-		foreach($objarray as $key => $value) {
+		foreach ($objarray as $key => $value) {
 			$this->attributes[$key] = $value;
 		}
 
@@ -122,6 +138,7 @@ class ElggUser extends ElggEntity
 
 	/**
 	 * Saves this user to the database.
+	 *
 	 * @return true|false
 	 */
 	public function save() {
@@ -131,7 +148,9 @@ class ElggUser extends ElggEntity
 		}
 
 		// Now save specific stuff
-		return create_user_entity($this->get('guid'), $this->get('name'), $this->get('username'), $this->get('password'), $this->get('salt'), $this->get('email'), $this->get('language'), $this->get('code'));
+		return create_user_entity($this->get('guid'), $this->get('name'), $this->get('username'),
+			$this->get('password'), $this->get('salt'), $this->get('email'), $this->get('language'),
+			$this->get('code'));
 	}
 
 	/**
@@ -163,6 +182,8 @@ class ElggUser extends ElggEntity
 	 * Ban this user.
 	 *
 	 * @param string $reason Optional reason
+	 *
+	 * @return bool
 	 */
 	public function ban($reason = "") {
 		return ban_user($this->guid, $reason);
@@ -170,8 +191,10 @@ class ElggUser extends ElggEntity
 
 	/**
 	 * Unban this user.
+	 *
+	 * @return bool
 	 */
-	public function unban()	{
+	public function unban() {
 		return unban_user($this->guid);
 	}
 
@@ -236,11 +259,12 @@ class ElggUser extends ElggEntity
 	 * Get sites that this user is a member of
 	 *
 	 * @param string $subtype Optionally, the subtype of result we want to limit to
-	 * @param int $limit The number of results to return
-	 * @param int $offset Any indexing offset
+	 * @param int    $limit   The number of results to return
+	 * @param int    $offset  Any indexing offset
+	 *
+	 * @return bool
 	 */
-	function getSites($subtype="", $limit = 10, $offset = 0) {
-		// return get_site_users($this->getGUID(), $subtype, $limit, $offset);
+	function getSites($subtype = "", $limit = 10, $offset = 0) {
 		return get_user_sites($this->getGUID(), $subtype, $limit, $offset);
 	}
 
@@ -248,10 +272,10 @@ class ElggUser extends ElggEntity
 	 * Add this user to a particular site
 	 *
 	 * @param int $site_guid The guid of the site to add it to
+	 *
 	 * @return true|false
 	 */
 	function addToSite($site_guid) {
-		// return add_site_user($this->getGUID(), $site_guid);
 		return add_site_user($site_guid, $this->getGUID());
 	}
 
@@ -259,10 +283,10 @@ class ElggUser extends ElggEntity
 	 * Remove this user from a particular site
 	 *
 	 * @param int $site_guid The guid of the site to remove it from
+	 *
 	 * @return true|false
 	 */
 	function removeFromSite($site_guid) {
-		//return remove_site_user($this->getGUID(), $site_guid);
 		return remove_site_user($site_guid, $this->getGUID());
 	}
 
@@ -270,6 +294,7 @@ class ElggUser extends ElggEntity
 	 * Adds a user to this user's friends list
 	 *
 	 * @param int $friend_guid The GUID of the user to add
+	 *
 	 * @return true|false Depending on success
 	 */
 	function addFriend($friend_guid) {
@@ -280,6 +305,7 @@ class ElggUser extends ElggEntity
 	 * Removes a user from this user's friends list
 	 *
 	 * @param int $friend_guid The GUID of the user to remove
+	 *
 	 * @return true|false Depending on success
 	 */
 	function removeFriend($friend_guid) {
@@ -299,6 +325,7 @@ class ElggUser extends ElggEntity
 	 * Determines whether this user is friends with another user
 	 *
 	 * @param int $user_guid The GUID of the user to check is on this user's friends list
+	 *
 	 * @return true|false
 	 */
 	function isFriendsWith($user_guid) {
@@ -309,6 +336,7 @@ class ElggUser extends ElggEntity
 	 * Determines whether or not this user is on another user's friends list
 	 *
 	 * @param int $user_guid The GUID of the user to check against
+	 *
 	 * @return true|false
 	 */
 	function isFriendOf($user_guid) {
@@ -319,8 +347,9 @@ class ElggUser extends ElggEntity
 	 * Retrieves a list of this user's friends
 	 *
 	 * @param string $subtype Optionally, the subtype of user to filter to (leave blank for all)
-	 * @param int $limit The number of users to retrieve
-	 * @param int $offset Indexing offset, if any
+	 * @param int    $limit   The number of users to retrieve
+	 * @param int    $offset  Indexing offset, if any
+	 *
 	 * @return array|false Array of ElggUsers, or false, depending on success
 	 */
 	function getFriends($subtype = "", $limit = 10, $offset = 0) {
@@ -331,8 +360,9 @@ class ElggUser extends ElggEntity
 	 * Retrieves a list of people who have made this user a friend
 	 *
 	 * @param string $subtype Optionally, the subtype of user to filter to (leave blank for all)
-	 * @param int $limit The number of users to retrieve
-	 * @param int $offset Indexing offset, if any
+	 * @param int    $limit   The number of users to retrieve
+	 * @param int    $offset  Indexing offset, if any
+	 *
 	 * @return array|false Array of ElggUsers, or false, depending on success
 	 */
 	function getFriendsOf($subtype = "", $limit = 10, $offset = 0) {
@@ -343,10 +373,12 @@ class ElggUser extends ElggEntity
 	 * Get an array of ElggObjects owned by this user.
 	 *
 	 * @param string $subtype The subtype of the objects, if any
-	 * @param int $limit Number of results to return
-	 * @param int $offset Any indexing offset
+	 * @param int    $limit   Number of results to return
+	 * @param int    $offset  Any indexing offset
+	 *
+	 * @return array|false
 	 */
-	public function getObjects($subtype="", $limit = 10, $offset = 0) {
+	public function getObjects($subtype = "", $limit = 10, $offset = 0) {
 		return get_user_objects($this->getGUID(), $subtype, $limit, $offset);
 	}
 
@@ -354,8 +386,10 @@ class ElggUser extends ElggEntity
 	 * Get an array of ElggObjects owned by this user's friends.
 	 *
 	 * @param string $subtype The subtype of the objects, if any
-	 * @param int $limit Number of results to return
-	 * @param int $offset Any indexing offset
+	 * @param int    $limit   Number of results to return
+	 * @param int    $offset  Any indexing offset
+	 *
+	 * @return array|false
 	 */
 	public function getFriendsObjects($subtype = "", $limit = 10, $offset = 0) {
 		return get_user_friends_objects($this->getGUID(), $subtype, $limit, $offset);
@@ -365,6 +399,7 @@ class ElggUser extends ElggEntity
 	 * Counts the number of ElggObjects owned by this user
 	 *
 	 * @param string $subtype The subtypes of the objects, if any
+	 *
 	 * @return int The number of ElggObjects
 	 */
 	public function countObjects($subtype = "") {
@@ -375,11 +410,12 @@ class ElggUser extends ElggEntity
 	 * Get the collections associated with a user.
 	 *
 	 * @param string $subtype Optionally, the subtype of result we want to limit to
-	 * @param int $limit The number of results to return
-	 * @param int $offset Any indexing offset
-	 * @return unknown
+	 * @param int    $limit   The number of results to return
+	 * @param int    $offset  Any indexing offset
+	 *
+	 * @return array|false
 	 */
-	public function getCollections($subtype="", $limit = 10, $offset = 0) {
+	public function getCollections($subtype = "", $limit = 10, $offset = 0) {
 		return get_user_collections($this->getGUID(), $subtype, $limit, $offset);
 	}
 
@@ -400,6 +436,8 @@ class ElggUser extends ElggEntity
 
 	/**
 	 * Return an array of fields which can be exported.
+	 *
+	 * @return array
 	 */
 	public function getExportableValues() {
 		return array_merge(parent::getExportableValues(), array(
@@ -409,8 +447,14 @@ class ElggUser extends ElggEntity
 		));
 	}
 
-	// backward compatibility with admin flag
-	// remove for 1.9
+	/**
+	 * Need to catch attempts to make a user an admin.  Remove for 1.9
+	 *
+	 * @param string $name  Name
+	 * @param mixed  $value Value
+	 *
+	 * @return bool
+	 */
 	public function __set($name, $value) {
 		if ($name == 'admin' || $name == 'siteadmin') {
 			elgg_deprecated_notice('The admin/siteadmin metadata are not longer used.  Use ElggUser->makeAdmin() and ElggUser->removeAdmin().', '1.7.1');
@@ -424,6 +468,13 @@ class ElggUser extends ElggEntity
 		return parent::__set($name, $value);
 	}
 
+	/**
+	 * Need to catch attempts to test user for admin.  Remove for 1.9
+	 *
+	 * @param string $name Name
+	 *
+	 * @return bool
+	 */
 	public function __get($name) {
 		if ($name == 'admin' || $name == 'siteadmin') {
 			elgg_deprecated_notice('The admin/siteadmin metadata are not longer used.  Use ElggUser->isAdmin().', '1.7.1');