Refs #2450: Documented access.php.

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

1 files changed, 159 insertions, 54 deletions

diff --git a/engine/lib/access.php b/engine/lib/access.php
index 80065fa72..e34f7c021 100644
--- a/engine/lib/access.php
+++ b/engine/lib/access.php
@@ -1,14 +1,14 @@
 <?php
 /**
- * Elgg access permissions
- * For users, objects, collections and all metadata
+ * Primary function for Elgg's entity and metadata access systems.
  *
- * @package Elgg
- * @subpackage Core
-
- * @author Curverider Ltd
-
- * @link http://elgg.org/
+ * Access is generally saved in the database as access_id.  This corresponds to
+ * one of the ACCESS_* constants defined in {@link elgglib.php}, or the ID of an
+ * access collection.
+ *
+ * @package Elgg.Core
+ * @subpackage Access
+ * @link http://docs.elgg.org/Access
  */
 
 /**
@@ -19,6 +19,8 @@
  * @param int $site_id Site ID; defaults to current site
  * @param boolean $flush If set to true, will refresh the access list from the database
  * @return string A list of access collections suitable for injection in an SQL call
+ * @link http://docs.elgg.org/Access
+ * @see get_access_array()
  */
 function get_access_list($user_id = 0, $site_id = 0, $flush = false) {
 	global $CONFIG, $init_finished, $SESSION;
@@ -48,12 +50,15 @@ function get_access_list($user_id = 0, $site_id = 0, $flush = false) {
 }
 
 /**
- * Gets an array of access restrictions the given user is allowed to see on this site
+ * Returns an array of access IDs a user is permitted to see.
+ *
+ * Can be overridden with the access:collections:read, user plugin hook.
  *
  * @param int $user_id User ID; defaults to currently logged in user
  * @param int $site_id Site ID; defaults to current site
  * @param boolean $flush If set to true, will refresh the access list from the database
- * @return array An array of access collections suitable for injection in an SQL call
+ * @return array An array of access collections ids
+ * @see get_access_list()
  */
 function get_access_array($user_id = 0, $site_id = 0, $flush = false) {
 	global $CONFIG, $init_finished;
@@ -79,11 +84,11 @@ function get_access_array($user_id = 0, $site_id = 0, $flush = false) {
 
 	if (empty($access_array[$user_id]) || $flush == true) {
 		$tmp_access_array = array(ACCESS_PUBLIC);
+
+		// The following can only return sensible data if the user is logged in.
 		if (isloggedin()) {
 			$tmp_access_array[] = ACCESS_LOGGED_IN;
 
-			// The following can only return sensible data if the user is logged in.
-
 			// Get ACL memberships
 			$query = "SELECT am.access_collection_id FROM {$CONFIG->dbprefix}access_collection_membership am ";
 			$query .= " LEFT JOIN {$CONFIG->dbprefix}access_collections ag ON ag.id = am.access_collection_id ";
@@ -125,13 +130,16 @@ function get_access_array($user_id = 0, $site_id = 0, $flush = false) {
 		$tmp_access_array = $access_array[$user_id];
 	}
 
-	return trigger_plugin_hook('access:collections:read','user',array('user_id' => $user_id, 'site_id' => $site_id),$tmp_access_array);
+	return trigger_plugin_hook('access:collections:read', 'user', array('user_id' => $user_id, 'site_id' => $site_id), $tmp_access_array);
 }
 
 /**
- * Gets the default access permission for new content
+ * Gets the default access permission.
+ *
+ * This returns the default access level for the site or optionally for the user.
  *
  * @return int default access id (see ACCESS defines in elgglib.php)
+ * @link http://docs.elgg.org/Access
  */
 function get_default_access(ElggUser $user = null) {
 	global $CONFIG;
@@ -152,17 +160,19 @@ function get_default_access(ElggUser $user = null) {
 }
 
 /**
- * Override the default behaviour and allow results to show hidden entities as well.
- * THIS IS A HACK.
+ * Allow disabled entities and metadata to be returned by getter functions
  *
  * @todo Replace this with query object!
+ * @global bool $ENTITY_SHOW_HIDDEN_OVERRIDE
+ * @access private
  */
 $ENTITY_SHOW_HIDDEN_OVERRIDE = false;
 
 /**
- * This will be replaced. Do not use in plugins!
+ * Show or hide disabled entities.
  *
- * @param bool $show
+ * @access private
+ * @param bool $show_hidden Show disabled entities.
  */
 function access_show_hidden_entities($show_hidden) {
 	global $ENTITY_SHOW_HIDDEN_OVERRIDE;
@@ -170,7 +180,10 @@ function access_show_hidden_entities($show_hidden) {
 }
 
 /**
- * This will be replaced. Do not use in plugins!
+ * Return current status of showing disabled entities.
+ *
+ * @access private
+ * @return bool
  */
 function access_get_show_hidden_status() {
 	global $ENTITY_SHOW_HIDDEN_OVERRIDE;
@@ -187,9 +200,10 @@ function access_get_show_hidden_status() {
  *
  * @param string $annotation_name name of the annotation
  * @param string $entity_guid SQL string that evaluates to the GUID of the entity the annotation should be attached to
- * @param string $owner_guid SQL string that evaluates to the GUID of the owner of the annotation	 	 *
+ * @param string $owner_guid SQL string that evaluates to the GUID of the owner of the annotation
  * @param boolean $exists If set to true, will return true if the annotation exists, otherwise returns false
  * @return string An SQL fragment suitable for inserting into a WHERE clause
+ * @todo Document and maybe even remove.  At least rename to something that makes sense.
  */
 function get_annotation_sql($annotation_name, $entity_guid, $owner_guid, $exists) {
 	global $CONFIG;
@@ -211,12 +225,18 @@ END;
 }
 
 /**
- * Add access restriction sql code to a given query.
- * Note that if this code is executed in privileged mode it will return blank.
- * @todo DELETE once Query classes are fully integrated
+ * Returns the SQL where clause for a table with a access_id and enabled columns.
+ *
+ * This handles returning where clauses for ACCESS_FRIENDS, and the currently
+ * unused block and filter lists.
+ *
+ * @warning If an admin is logged in or {@link elgg_set_ignore_access()} is true,
+ * this will return blank.
  *
  * @param string $table_prefix Optional table. prefix for the access code.
  * @param int $owner
+ * @return string The SQL for a where clause
+ * @access private
  */
 function get_access_sql_suffix($table_prefix = '', $owner = null) {
 	global $ENTITY_SHOW_HIDDEN_OVERRIDE, $CONFIG;
@@ -283,12 +303,18 @@ function get_access_sql_suffix($table_prefix = '', $owner = null) {
 }
 
 /**
- * Determines whether the given user has access to the given entity
+ * Can $user access $entity.
  *
- * @param ElggEntity $entity The entity to check access for.
- * @param ElggUser $user Optionally the user to check access for.
+ * @warning If a logged in user doesn't have access to an entity, the
+ * core engine will not load that entity.
+ *
+ * @tip This is mostly useful for checking if a 3rd user has access
+ * to an entity that is currently loaded.
  *
+ * @param ElggEntity $entity The entity to check access for.
+ * @param ElggUser $user Optionally the user to check access for. Defaults to the logged in user (which doesn't make sense).
  * @return boolean True if the user can access the entity
+ * @link http://docs.elgg.org/Access
  */
 function has_access_to_entity($entity, $user = null) {
 	global $CONFIG;
@@ -300,7 +326,8 @@ function has_access_to_entity($entity, $user = null) {
 	}
 
 	$query = "SELECT guid from {$CONFIG->dbprefix}entities e WHERE e.guid = " . $entity->getGUID();
-	$query .= " AND " . $access_bit; // Add access controls
+	// Add access controls
+	$query .= " AND " . $access_bit;
 	if (get_data($query)) {
 		return true;
 	} else {
@@ -309,14 +336,14 @@ function has_access_to_entity($entity, $user = null) {
 }
 
 /**
- * Returns an array of access permissions that the specified user is allowed to save objects with.
+ * Returns an array of access permissions that the user is allowed to save objects with.
  * Permissions are of the form ('id' => 'Description')
  *
  * @param int $user_id The user's GUID.
  * @param int $site_id The current site.
- * @param true|false $flush If this is set to true, this will shun any cached version
- *
+ * @param true|false $flush If this is set to true, this will ignore any cached version
  * @return array List of access permissions
+ * @link http://docs.elgg.org/Access
  */
 function get_write_access_array($user_id = 0, $site_id = 0, $flush = false) {
 	global $CONFIG;
@@ -355,19 +382,27 @@ function get_write_access_array($user_id = 0, $site_id = 0, $flush = false) {
 		$tmp_access_array = $access_array[$user_id];
 	}
 
-	$tmp_access_array = trigger_plugin_hook('access:collections:write','user',array('user_id' => $user_id, 'site_id' => $site_id),$tmp_access_array);
+	$tmp_access_array = trigger_plugin_hook('access:collections:write', 'user', array('user_id' => $user_id, 'site_id' => $site_id), $tmp_access_array);
 
 	return $tmp_access_array;
 }
 
 /**
- * Creates a new access control collection owned by the specified user.
+ * Creates a new access collection.
+ *
+ * Access colletions allow plugins and users to create granular access
+ * for entities.
+ *
+ * @internal Access collections are stored in the access_collections table.
+ * Memberships to collections are in access_collections_membership.
  *
  * @param string $name The name of the collection.
  * @param int $owner_guid The GUID of the owner (default: currently logged in user).
  * @param int $site_guid The GUID of the site (default: current site).
- *
  * @return int|false Depending on success (the collection ID if successful).
+ * @link http://docs.elgg.org/Access/Collections
+ * @see update_access_collection()
+ * @see delete_access_collection()
  */
 function create_access_collection($name, $owner_guid = 0, $site_guid = 0) {
 	global $CONFIG;
@@ -407,9 +442,18 @@ function create_access_collection($name, $owner_guid = 0, $site_guid = 0) {
 /**
  * Updates the membership in an access collection.
  *
+ * @warning Expects a full list of all members that should
+ * be part o the access collection
+ *
+ * @note This will run all hooks associated with adding or removing
+ * members to access collections.
+ *
  * @param int $collection_id The ID of the collection.
  * @param array $members Array of member GUIDs
  * @return true|false Depending on success
+ * @link http://docs.elgg.org/Access/Collections
+ * @see add_user_to_access_collection()
+ * @see remove_user_from_access_collection()
  */
 function update_access_collection($collection_id, $members) {
 	global $CONFIG;
@@ -448,13 +492,15 @@ function update_access_collection($collection_id, $members) {
 }
 
 /**
- * Deletes a specified access collection
+ * Deletes a specified access collection and its membership.
  *
  * @param int $collection_id The collection ID
- * @return true|false Depending on success
+ * @return bool
+ * @link http://docs.elgg.org/Access/Collections
+ * @see create_access_collection()
+ * @see update_access_collection()
  */
 function delete_access_collection($collection_id) {
-
 	$collection_id = (int) $collection_id;
 	$collections = get_write_access_array(null, null, TRUE);
 	$params = array('collection_id' => $collection_id);
@@ -477,8 +523,11 @@ function delete_access_collection($collection_id) {
 /**
  * Get a specified access collection
  *
+ * @note This doesn't return the members of an access collection,
+ * just the database row of the actual collection.
+ *
  * @param int $collection_id The collection ID
- * @return array|false Depending on success
+ * @return array|false
  */
 function get_access_collection($collection_id) {
 	global $CONFIG;
@@ -490,11 +539,16 @@ function get_access_collection($collection_id) {
 }
 
 /**
- * Adds a user to the specified user collection
+ * Adds a user to an access collection.
+ *
+ * Emits the access:collections:add_user, collection plugin hook.
  *
  * @param int $user_guid The GUID of the user to add
  * @param int $collection_id The ID of the collection to add them to
  * @return true|false Depending on success
+ * @link http://docs.elgg.org/Access/Collections
+ * @see update_access_collection()
+ * @see remove_user_from_access_collection()
  */
 function add_user_to_access_collection($user_guid, $collection_id) {
 	$collection_id = (int) $collection_id;
@@ -530,7 +584,9 @@ function add_user_to_access_collection($user_guid, $collection_id) {
 }
 
 /**
- * Removes a user from an access collection
+ * Removes a user from an access collection.
+ *
+ * Emits the access:collections:remove_user, collection plugin hook.
  *
  * @param int $user_guid The user GUID
  * @param int $collection_id The access collection ID
@@ -564,11 +620,14 @@ function remove_user_from_access_collection($user_guid, $collection_id) {
 }
 
 /**
- * Get all of a users collections
+ * Returns an array of database row objects of the access collections owned by $owner_guid.
  *
- * @param int $owner_guid The user ID
+ * @param int $owner_guid The entity guid
  * @param int $site_guid The GUID of the site (default: current site).
- * @return true|false Depending on success
+ * @return array|false
+ * @see add_access_collection()
+ * @see get_members_of_access_collection()
+ * @link http://docs.elgg.org/Access/Collections
  */
 function get_user_access_collections($owner_guid, $site_guid = 0) {
 	global $CONFIG;
@@ -589,11 +648,13 @@ function get_user_access_collections($owner_guid, $site_guid = 0) {
 }
 
 /**
- * Get all of members of a friend collection
+ * Get all of members of an access collection
  *
  * @param int $collection The collection's ID
- * @param true|false $idonly If set to true, will only return the members' IDs (default: false)
- * @return ElggUser entities if successful, false if not
+ * @param true|false $idonly If set to true, will only return the members' GUIDs (default: false)
+ * @return array ElggUser guids or entities if successful, false if not
+ * @see add_user_to_access_collection()
+ * @see http://docs.elgg.org/Access/Collections
  */
 function get_members_of_access_collection($collection, $idonly = FALSE) {
 	global $CONFIG;
@@ -621,16 +682,17 @@ function get_members_of_access_collection($collection, $idonly = FALSE) {
  *
  * @param int $owner_guid The GUID of the owning user
  * @return string A formatted rendition of the collections
+ * @todo Move to the friends/collection.php page.
  */
 function elgg_view_access_collections($owner_guid) {
 	if ($collections = get_user_access_collections($owner_guid)) {
 		foreach($collections as $key => $collection) {
 			$collections[$key]->members = get_members_of_access_collection($collection->id, true);
-			$collections[$key]->entities = get_user_friends($owner_guid,"",9999);
+			$collections[$key]->entities = get_user_friends($owner_guid, "", 9999);
 		}
 	}
 
-	return elgg_view('friends/collections',array('collections' => $collections));
+	return elgg_view('friends/collections', array('collections' => $collections));
 }
 
 /**
@@ -697,10 +759,11 @@ function get_entities_from_access_id($collection_id, $entity_type = "", $entity_
 }
 
 /**
- * Retrieve entities for a given access collection
+ * Return entities based upon access id.
  *
- * @param int $collection_id
- * @param array $options @see elgg_get_entities()
+ * @param array $options Any options accepted by {@link elgg_get_entities()} and:
+ * 	access_id => int The access ID of the entity.
+ * @see elgg_get_entities()
  * @return array
  * @since 1.7.0
  */
@@ -738,6 +801,7 @@ function elgg_get_entities_from_access_id(array $options=array()) {
  * @param $viewtypetoggle
  * @param $pagination
  * @return str
+ * @todo deprecate with elgg_list_entities_from_access_id() function
  */
 function list_entities_from_access_id($collection_id, $entity_type = "", $entity_subtype = "", $owner_guid = 0, $limit = 10, $fullview = true, $viewtypetoggle = true, $pagination = true) {
 	$offset = (int) get_input('offset');
@@ -749,16 +813,24 @@ function list_entities_from_access_id($collection_id, $entity_type = "", $entity
 }
 
 /**
- * Return a humanreadable version of an entity's access level
+ * Return the name of an ACCESS_* constant or a access collection,
+ * but only if the user has write access on that ACL.
+ *
+ * @warning This function probably doesn't work how it's meant to.
  *
  * @param $entity_accessid (int) The entity's access id
  * @return string e.g. Public, Private etc
  * @since 1.7.0
+ * @todo I think this probably wants get_access_array() instead of get_write_access_array(),
+ * but those two functions return different types of arrays.
  */
 function get_readable_access_level($entity_accessid){
 	$access = (int) $entity_accessid;
+
 	//get the access level for object in readable string
 	$options = get_write_access_array();
+
+	//@todo Really?  Use array_key_exists()
 	foreach($options as $key => $option) {
 		if($key == $access){
 			$entity_acl = htmlentities($option, ENT_QUOTES, 'UTF-8');
@@ -772,8 +844,21 @@ function get_readable_access_level($entity_accessid){
 /**
  * Set if entity access system should be ignored.
  *
+ * The access system will not return entities in any getter
+ * functions if the user doesn't have access.
+ *
+ * @internal For performance reasons this is done at the database level.
+ *
+ * @tip Use this to access entities in automated scripts
+ * when no user is logged in.
+ *
+ * @warning This will not show disabled entities.  Use {@link $ENTITY_SHOW_HIDDEN_OVERRIDE}
+ * for that.
+ *
  * @return bool Previous ignore_access setting.
  * @since 1.7.0
+ * @see http://docs.elgg.org/Access/IgnoreAccess
+ * @see elgg_get_ignore_access()
  */
 function elgg_set_ignore_access($ignore = true) {
 	$elgg_access = elgg_get_access_object();
@@ -785,6 +870,8 @@ function elgg_set_ignore_access($ignore = true) {
  *
  * @return bool
  * @since 1.7.0
+ * @see http://docs.elgg.org/Access/IgnoreAccess
+ * @see elgg_set_ignore_access()
  */
 function elgg_get_ignore_access() {
 	return elgg_get_access_object()->get_ignore_access();
@@ -793,6 +880,9 @@ function elgg_get_ignore_access() {
 /**
  * Decides if the access system is being ignored.
  *
+ * The access system can be ignored if 1) an admin user is logged in
+ * or 2) {@link elgg_set_ignore_access()} was called with true.
+ *
  * @return bool
  * @since 1.7.0
  */
@@ -809,8 +899,11 @@ function elgg_check_access_overrides($user_guid = null) {
 /**
  * Returns the ElggAccess object.
  *
+ * This is used to
+ *
  * @return ElggAccess
  * @since 1.7.0
+ * @access private
  */
 function elgg_get_access_object() {
 	static $elgg_access;
@@ -822,12 +915,20 @@ function elgg_get_access_object() {
 	return $elgg_access;
 }
 
-global $init_finished;
+/**
+ * A flag to set if Elgg's access initialization is finished.
+ *
+ * @global bool $init_finished
+ * @access private
+ * @todo investigate why this is needed
+ */
 $init_finished = false;
 
 /**
  * A quick and dirty way to make sure the access permissions have been correctly set up
  *
+ * @elgg_event_handler init system
+ * @todo Invesigate
  */
 function access_init() {
 	global $init_finished;
@@ -835,10 +936,14 @@ function access_init() {
 }
 
 /**
- * Override permissions system
+ * Check if the access system should be overridden.
+ *
+ * Allows admin users and calls after {@link elgg_set_ignore_access} to
+ * by pass the access system.
  *
  * @return true|null
  * @since 1.7.0
+ * @elgg_event_handler permissions_check all
  */
 function elgg_override_permissions_hook($hook, $type, $returnval, $params) {
 	$user_guid = get_loggedin_userid();
@@ -862,4 +967,4 @@ register_elgg_event_handler('init', 'system', 'access_init', 9999);
 
 // For overrided permissions
 register_plugin_hook('permissions_check', 'all', 'elgg_override_permissions_hook');
-register_plugin_hook('container_permissions_check', 'all', 'elgg_override_permissions_hook');
+register_plugin_hook('container_permissions_check', 'all', 'elgg_override_permissions_hook');
\ No newline at end of file