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, 132 insertions, 72 deletions

diff --git a/engine/lib/sites.php b/engine/lib/sites.php
index 378a2cfe1..d5984a75f 100644
--- a/engine/lib/sites.php
+++ b/engine/lib/sites.php
@@ -3,14 +3,16 @@
  * Elgg sites
  * Functions to manage multiple or single sites in an Elgg install
  *
- * @package Elgg
- * @subpackage Core
+ * @package Elgg.Core
+ * @subpackage DataModel.Site
  */
 
 /**
  * Return the site specific details of a site by a row.
  *
- * @param int $guid
+ * @param int $guid The site GUID
+ *
+ * @return mixed
  */
 function get_site_entity_as_row($guid) {
 	global $CONFIG;
@@ -23,10 +25,12 @@ function get_site_entity_as_row($guid) {
  * Create or update the extras table for a given site.
  * Call create_entity first.
  *
- * @param int $guid
- * @param string $name
- * @param string $description
- * @param string $url
+ * @param int    $guid        Site GUID
+ * @param string $name        Site name
+ * @param string $description Site Description
+ * @param string $url         URL of the site
+ *
+ * @return bool
  */
 function create_site_entity($guid, $name, $description, $url) {
 	global $CONFIG;
@@ -40,12 +44,16 @@ function create_site_entity($guid, $name, $description, $url) {
 
 	if ($row) {
 		// Exists and you have access to it
-		if ($exists = get_data_row("SELECT guid from {$CONFIG->dbprefix}sites_entity where guid = {$guid}")) {
-			$result = update_data("UPDATE {$CONFIG->dbprefix}sites_entity set name='$name', description='$description', url='$url' where guid=$guid");
-			if ($result!=false) {
+		$query = "SELECT guid from {$CONFIG->dbprefix}sites_entity where guid = {$guid}";
+		if ($exists = get_data_row($query)) {
+			$query = "UPDATE {$CONFIG->dbprefix}sites_entity
+				set name='$name', description='$description', url='$url' where guid=$guid";
+			$result = update_data($query);
+
+			if ($result != false) {
 				// Update succeeded, continue
 				$entity = get_entity($guid);
-				if (trigger_elgg_event('update',$entity->type,$entity)) {
+				if (trigger_elgg_event('update', $entity->type, $entity)) {
 					return $guid;
 				} else {
 					$entity->delete();
@@ -54,10 +62,13 @@ function create_site_entity($guid, $name, $description, $url) {
 			}
 		} else {
 			// Update failed, attempt an insert.
-			$result = insert_data("INSERT into {$CONFIG->dbprefix}sites_entity (guid, name, description, url) values ($guid, '$name','$description','$url')");
-			if ($result!==false) {
+			$query = "INSERT into {$CONFIG->dbprefix}sites_entity
+				(guid, name, description, url) values ($guid, '$name', '$description', '$url')";
+			$result = insert_data($query);
+
+			if ($result !== false) {
 				$entity = get_entity($guid);
-				if (trigger_elgg_event('create',$entity->type,$entity)) {
+				if (trigger_elgg_event('create', $entity->type, $entity)) {
 					return $guid;
 				} else {
 					$entity->delete();
@@ -74,8 +85,13 @@ function create_site_entity($guid, $name, $description, $url) {
  * THIS FUNCTION IS DEPRECATED.
  *
  * Delete a site's extra data.
+ *
  * @todo remove
- * @param int $guid
+ *
+ * @param int $guid Site guid
+ *
+ * @deprecated 1.5 Or so?
+ * @return 1
  */
 function delete_site_entity($guid) {
 	system_message(sprintf(elgg_echo('deprecatedfunction'), 'delete_user_entity'));
@@ -86,8 +102,10 @@ function delete_site_entity($guid) {
 /**
  * Add a user to a site.
  *
- * @param int $site_guid
- * @param int $user_guid
+ * @param int $site_guid Site guid
+ * @param int $user_guid User guid
+ *
+ * @return bool
  */
 function add_site_user($site_guid, $user_guid) {
 	global $CONFIG;
@@ -101,8 +119,10 @@ function add_site_user($site_guid, $user_guid) {
 /**
  * Remove a user from a site.
  *
- * @param int $site_guid
- * @param int $user_guid
+ * @param int $site_guid Site GUID
+ * @param int $user_guid User GUID
+ *
+ * @return bool
  */
 function remove_site_user($site_guid, $user_guid) {
 	$site_guid = (int)$site_guid;
@@ -114,9 +134,11 @@ function remove_site_user($site_guid, $user_guid) {
 /**
  * Get the members of a site.
  *
- * @param int $site_guid
- * @param int $limit
- * @param int $offset
+ * @param int $site_guid Site GUID
+ * @param int $limit     User GUID
+ * @param int $offset    Offset
+ *
+ * @return mixed
  */
 function get_site_members($site_guid, $limit = 10, $offset = 0) {
 	$site_guid = (int)$site_guid;
@@ -124,10 +146,10 @@ function get_site_members($site_guid, $limit = 10, $offset = 0) {
 	$offset = (int)$offset;
 
 	return elgg_get_entities_from_relationship(array(
-		'relationship' => 'member_of_site', 
-		'relationship_guid' => $site_guid, 
-		'inverse_relationship' => TRUE, 
-		'types' => 'user', 
+		'relationship' => 'member_of_site',
+		'relationship_guid' => $site_guid,
+		'inverse_relationship' => TRUE,
+		'types' => 'user',
 		'limit' => $limit, 'offset' => $offset
 	));
 }
@@ -135,21 +157,22 @@ function get_site_members($site_guid, $limit = 10, $offset = 0) {
 /**
  * Display a list of site members
  *
- * @param int $site_guid The GUID of the site
- * @param int $limit The number of members to display on a page
- * @param true|false $fullview Whether or not to display the full view (default: true)
+ * @param int  $site_guid The GUID of the site
+ * @param int  $limit     The number of members to display on a page
+ * @param bool $fullview  Whether or not to display the full view (default: true)
+ *
  * @return string A displayable list of members
  */
 function list_site_members($site_guid, $limit = 10, $fullview = true) {
 	$offset = (int) get_input('offset');
 	$limit = (int) $limit;
 	$options = array(
-		'relationship' => 'member_of_site', 
-		'relationship_guid' => $site_guid, 
-		'inverse_relationship' => TRUE, 
+		'relationship' => 'member_of_site',
+		'relationship_guid' => $site_guid,
+		'inverse_relationship' => TRUE,
 		'types' => 'user',
-		'limit' => $limit, 
-		'offset' => $offset, 
+		'limit' => $limit,
+		'offset' => $offset,
 		'count' => TRUE
 	);
 	$count = (int) elgg_get_entities_from_relationship($options);
@@ -162,8 +185,10 @@ function list_site_members($site_guid, $limit = 10, $fullview = true) {
 /**
  * Add an object to a site.
  *
- * @param int $site_guid
- * @param int $object_guid
+ * @param int $site_guid   Site GUID
+ * @param int $object_guid Object GUID
+ *
+ * @return mixed
  */
 function add_site_object($site_guid, $object_guid) {
 	global $CONFIG;
@@ -177,8 +202,10 @@ function add_site_object($site_guid, $object_guid) {
 /**
  * Remove an object from a site.
  *
- * @param int $site_guid
- * @param int $object_guid
+ * @param int $site_guid   Site GUID
+ * @param int $object_guid Object GUID
+ *
+ * @return bool
  */
 function remove_site_object($site_guid, $object_guid) {
 	$site_guid = (int)$site_guid;
@@ -190,10 +217,12 @@ function remove_site_object($site_guid, $object_guid) {
 /**
  * Get the objects belonging to a site.
  *
- * @param int $site_guid
- * @param string $subtype
- * @param int $limit
- * @param int $offset
+ * @param int    $site_guid Site GUID
+ * @param string $subtype   Subtype
+ * @param int    $limit     Limit
+ * @param int    $offset    Offset
+ *
+ * @return mixed
  */
 function get_site_objects($site_guid, $subtype = "", $limit = 10, $offset = 0) {
 	$site_guid = (int)$site_guid;
@@ -203,11 +232,11 @@ function get_site_objects($site_guid, $subtype = "", $limit = 10, $offset = 0) {
 
 	return elgg_get_entities_from_relationship(array(
 		'relationship' => 'member_of_site',
-		'relationship_guid' => $site_guid, 
-		'inverse_relationship' => TRUE, 
-		'types' => 'object', 
-		'subtypes' => $subtype, 
-		'limit' => $limit, 
+		'relationship_guid' => $site_guid,
+		'inverse_relationship' => TRUE,
+		'types' => 'object',
+		'subtypes' => $subtype,
+		'limit' => $limit,
 		'offset' => $offset
 	));
 }
@@ -215,8 +244,10 @@ function get_site_objects($site_guid, $subtype = "", $limit = 10, $offset = 0) {
 /**
  * Add a collection to a site.
  *
- * @param int $site_guid
- * @param int $collection_guid
+ * @param int $site_guid       Site GUID
+ * @param int $collection_guid Collection GUID
+ *
+ * @return mixed
  */
 function add_site_collection($site_guid, $collection_guid) {
 	global $CONFIG;
@@ -230,8 +261,11 @@ function add_site_collection($site_guid, $collection_guid) {
 /**
  * Remove a collection from a site.
  *
- * @param int $site_guid
- * @param int $collection_guid
+ * @param int $site_guid       Site GUID
+ * @param int $collection_guid Collection GUID
+ *
+ * @todo probably remove.
+ * @return mixed
  */
 function remove_site_collection($site_guid, $collection_guid) {
 	$site_guid = (int)$site_guid;
@@ -243,10 +277,12 @@ function remove_site_collection($site_guid, $collection_guid) {
 /**
  * Get the collections belonging to a site.
  *
- * @param int $site_guid
- * @param string $subtype
- * @param int $limit
- * @param int $offset
+ * @param int    $site_guid Site GUID
+ * @param string $subtype   Subtype
+ * @param int    $limit     Limit
+ * @param int    $offset    Offset
+ *
+ * @return mixed
  */
 function get_site_collections($site_guid, $subtype = "", $limit = 10, $offset = 0) {
 	$site_guid = (int)$site_guid;
@@ -256,11 +292,11 @@ function get_site_collections($site_guid, $subtype = "", $limit = 10, $offset =
 
 	// collection isn't a valid type.  This won't work.
 	return elgg_get_entities_from_relationship(array(
-		'relationship' => 'member_of_site', 
-		'relationship_guid' => $site_guid, 
-		'inverse_relationship' => TRUE, 
-		'types' => 'collection', 
-		'subtypes' => $subtype, 
+		'relationship' => 'member_of_site',
+		'relationship_guid' => $site_guid,
+		'inverse_relationship' => TRUE,
+		'types' => 'collection',
+		'subtypes' => $subtype,
 		'limit' => $limit,
 		'offset' => $offset
 	));
@@ -268,6 +304,10 @@ function get_site_collections($site_guid, $subtype = "", $limit = 10, $offset =
 
 /**
  * Return the site via a url.
+ *
+ * @param string $url The URL of a site
+ *
+ * @return mixed
  */
 function get_site_by_url($url) {
 	global $CONFIG;
@@ -284,17 +324,20 @@ function get_site_by_url($url) {
 }
 
 /**
- * Searches for a site based on a complete or partial name or description or url using full text searching.
+ * Searches for a site based on a complete or partial name
+ * or description or url using full text searching.
  *
  * IMPORTANT NOTE: With MySQL's default setup:
  * 1) $criteria must be 4 or more characters long
  * 2) If $criteria matches greater than 50% of results NO RESULTS ARE RETURNED!
  *
- * @param string $criteria The partial or full name or username.
- * @param int $limit Limit of the search.
- * @param int $offset Offset.
- * @param string $order_by The order.
- * @param boolean $count Whether to return the count of results or just the results.
+ * @param string  $criteria The partial or full name or username.
+ * @param int     $limit    Limit of the search.
+ * @param int     $offset   Offset.
+ * @param string  $order_by The order.
+ * @param boolean $count    Whether to return the count of results or just the results.
+ *
+ * @return mixed
  * @deprecated 1.7
  */
 function search_for_site($criteria, $limit = 10, $offset = 0, $order_by = "", $count = false) {
@@ -317,7 +360,9 @@ function search_for_site($criteria, $limit = 10, $offset = 0, $order_by = "", $c
 	} else {
 		$query = "SELECT e.* ";
 	}
-	$query .= "from {$CONFIG->dbprefix}entities e join {$CONFIG->dbprefix}sites_entity s on e.guid=s.guid where match(s.name,s.description,s.url) against ('$criteria') and $access";
+	$query .= "from {$CONFIG->dbprefix}entities e
+		join {$CONFIG->dbprefix}sites_entity s on e.guid=s.guid
+		where match(s.name, s.description, s.url) against ('$criteria') and $access";
 
 	if (!$count) {
 		$query .= " order by $order_by limit $offset, $limit"; // Add order and limit
@@ -333,7 +378,9 @@ function search_for_site($criteria, $limit = 10, $offset = 0, $order_by = "", $c
 /**
  * Retrieve a site and return the domain portion of its url.
  *
- * @param int $guid
+ * @param int $guid ElggSite GUID
+ *
+ * @return string
  */
 function get_site_domain($guid) {
 	$guid = (int)$guid;
@@ -355,16 +402,18 @@ function get_site_domain($guid) {
  * to the sites init event and changing $CONFIG->site_id.
  *
  * @uses $CONFIG
- * @param string $event Event API required parameter
+ *
+ * @param string $event       Event API required parameter
  * @param string $object_type Event API required parameter
- * @param null $object Event API required parameter
+ * @param null   $object      Event API required parameter
+ *
  * @return true
  */
 function sites_init($event, $object_type, $object) {
 	global $CONFIG;
 
 	if (is_installed() && is_db_installed()) {
-		$site = trigger_plugin_hook("siteid","system");
+		$site = trigger_plugin_hook("siteid", "system");
 		if ($site === null || $site === false) {
 			$CONFIG->site_id = (int) datalist_get('default_site');
 		} else {
@@ -380,10 +429,21 @@ function sites_init($event, $object_type, $object) {
 }
 
 // Register event handlers
-register_elgg_event_handler('boot','system','sites_init',2);
+register_elgg_event_handler('boot', 'system', 'sites_init', 2);
 
 // Register with unit test
 register_plugin_hook('unit_test', 'system', 'sites_test');
+
+/**
+ * Unit tests for sites
+ *
+ * @param sting  $hook   unit_test
+ * @param string $type   system
+ * @param mixed  $value  Array of tests
+ * @param mixed  $params Params
+ *
+ * @return array
+ */
 function sites_test($hook, $type, $value, $params) {
 	global $CONFIG;
 	$value[] = "{$CONFIG->path}engine/tests/objects/sites.php";