Fixes #3941 Refs #3936 added @access private in action lib and added elgg_unregister_action()

1 files changed, 92 insertions, 71 deletions

diff --git a/engine/lib/actions.php b/engine/lib/actions.php
index 99e22e104..44d1a715d 100644
--- a/engine/lib/actions.php
+++ b/engine/lib/actions.php
@@ -2,21 +2,23 @@
 /**
  * Elgg Actions
  *
- * Actions are the primary controllers (The C in MVC) in Elgg. They are
- * registered by {@link register_elgg_action()} and are called either by URL
- * http://elggsite.org/action/action_name or {@link action($action_name}.  For
- * URLs, a rewrite rule in .htaccess passes the action name to
- * engine/handlers/action_handler.php, which dispatches the action.
+ * Actions are one of the primary controllers (The C in MVC) in Elgg. They are
+ * registered by {@link register_elgg_action()} and are called by URL
+ * http://elggsite.org/action/action_name. For URLs, a rewrite rule in
+ * .htaccess passes the action name to engine/handlers/action_handler.php,
+ * which dispatches the request for the action.
  *
- * An action name should be registered to exactly one file in the system, usually under
- * the actions/ directory.
+ * An action name must be registered to a file in the system. Core actions are
+ * found in /actions/ and plugin actions are usually under /mod/<plugin>/actions/.
+ * It is recommended that actions be namespaced to avoid collisions.
  *
  * All actions require security tokens.  Using the {@elgg_view input/form} view
- * will automatically add tokens as hidden inputs.  To manually add hidden inputs,
- * use the {@elgg_view input/securitytoken} view.
+ * will automatically add tokens as hidden inputs as will the elgg_view_form()
+ * function.  To manually add hidden inputs, use the {@elgg_view input/securitytoken} view.
  *
  * To include security tokens for actions called via GET, use
- * {@link elgg_add_security_tokens_to_url()}.
+ * {@link elgg_add_security_tokens_to_url()} or specify is_action as true when
+ * using {@lgg_view output/url}.
  *
  * Action tokens can be manually generated by using {@link generate_action_token()}.
  *
@@ -31,30 +33,30 @@
  */
 
 /**
-* Perform an action.
-*
-* This function executes the action with name $action as
-* registered by {@link elgg_register_action()}.
-*
-* The plugin hook action, $action_name will be emitted before
-* the action is executed.  If a handler returns false, it will
-* prevent the action from being called.
-*
-* @note If an action isn't registered in the system or is registered
-* to an unavailable file the user will be forwarded to the site front
-* page and an error will be emitted via {@link register_error()}.
-*
-* @warning All actions require {@link http://docs.elgg.org/Actions/Tokens Action Tokens}.
-* @warning Most plugin shouldn't call this manually.
-*
-* @param string $action    The requested action
-* @param string $forwarder Optionally, the location to forward to
-*
-* @link http://docs.elgg.org/Actions
-* @see elgg_register_action()
-*
-* @return void
-*/
+ * Perform an action.
+ *
+ * This function executes the action with name $action as registered
+ * by {@link elgg_register_action()}.
+ *
+ * The plugin hook 'action', $action_name will be triggered before the action
+ * is executed.  If a handler returns false, it will prevent the action script
+ * from being called.
+ *
+ * @note If an action isn't registered in the system or is registered
+ * to an unavailable file the user will be forwarded to the site front
+ * page and an error will be emitted via {@link register_error()}.
+ *
+ * @warning All actions require {@link http://docs.elgg.org/Actions/Tokens Action Tokens}.
+ *
+ * @param string $action    The requested action
+ * @param string $forwarder Optionally, the location to forward to
+ *
+ * @link http://docs.elgg.org/Actions
+ * @see elgg_register_action()
+ *
+ * @return void
+ * @access private
+ */
 function action($action, $forwarder = "") {
 	global $CONFIG;
 
@@ -123,9 +125,8 @@ function action($action, $forwarder = "") {
 /**
  * Registers an action.
  *
- * Actions are registered to a single file in the system and are executed
- * either by the URL http://elggsite.org/action/action_name or by calling
- * {@link action()}.
+ * Actions are registered to a script in the system and are executed
+ * either by the URL http://elggsite.org/action/action_name/.
  *
  * $filename must be the full path of the file to register, or a path relative
  * to the core actions/ dir.
@@ -137,8 +138,7 @@ function action($action, $forwarder = "") {
  *
  * @tip Put action files under the actions/<plugin_name> directory of your plugin.
  *
- * @tip You don't need to include engine/start.php, call {@link gatekeeper()},
- * or call {@link admin_gatekeeper()}.
+ * @tip You don't need to include engine/start.php in your action files.
  *
  * @internal Actions are saved in $CONFIG->actions as an array in the form:
  * <code>
@@ -151,13 +151,13 @@ function action($action, $forwarder = "") {
  * @param string $action   The name of the action (eg "register", "account/settings/save")
  * @param string $filename Optionally, the filename where this action is located. If not specified,
  *                         will assume the action is in elgg/actions/<action>.php
- * @param string $access   Who is allowed to execute this action: admin, public, or logged_in.
+ * @param string $access   Who is allowed to execute this action: public, logged_in, admin.
  *                         (default: logged_in)
  *
  * @see action()
  * @see http://docs.elgg.org/Actions
  *
- * @return true
+ * @return bool
  */
 function elgg_register_action($action, $filename = "", $access = 'logged_in') {
 	global $CONFIG;
@@ -187,16 +187,31 @@ function elgg_register_action($action, $filename = "", $access = 'logged_in') {
 }
 
 /**
+ * Unregisters an action
+ *
+ * @param string $action Action name
+ * @return bool
+ * @since 1.8.1
+ */
+function elgg_unregister_action($action) {
+	global $CONFIG;
+
+	if (isset($CONFIG->actions[$action])) {
+		unset($CONFIG->actions[$action]);
+		return true;
+	} else {
+		return false;
+	}
+}
+
+/**
  * Validate an action token.
  *
- * Calls to actions will automatically validate tokens.
- * If tokens are not present or invalid, the action will be
- * denied and the user will be redirected to the front page.
+ * Calls to actions will automatically validate tokens. If tokens are not
+ * present or invalid, the action will be denied and the user will be redirected.
  *
  * Plugin authors should never have to manually validate action tokens.
  *
- * @access private
- *
  * @param bool  $visibleerrors Emit {@link register_error()} errors on failure?
  * @param mixed $token         The token to test against. Default: $_REQUEST['__elgg_token']
  * @param mixed $ts            The time stamp to test against. Default: $_REQUEST['__elgg_ts']
@@ -204,6 +219,7 @@ function elgg_register_action($action, $filename = "", $access = 'logged_in') {
  * @return bool
  * @see generate_action_token()
  * @link http://docs.elgg.org/Actions/Tokens
+ * @access private
  */
 function validate_action_token($visibleerrors = TRUE, $token = NULL, $ts = NULL) {
 	global $CONFIG;
@@ -265,17 +281,17 @@ function validate_action_token($visibleerrors = TRUE, $token = NULL, $ts = NULL)
 }
 
 /**
-* Validates the presence of action tokens.
-*
-* This function is called for all actions.  If action tokens are missing,
-* the user will be forwarded to the site front page and an error emitted.
-*
-* This function verifies form input for security features (like a generated token), and forwards
-* the page if they are invalid.
-*
-* @access private
-* @return mixed True if valid, or redirects to front page and exists.
-*/
+ * Validates the presence of action tokens.
+ *
+ * This function is called for all actions.  If action tokens are missing,
+ * the user will be forwarded to the site front page and an error emitted.
+ *
+ * This function verifies form input for security features (like a generated token),
+ * and forwards if they are invalid.
+ *
+ * @return mixed True if valid or redirects.
+ * @access private
+ */
 function action_gatekeeper() {
 	if (validate_action_token()) {
 		return TRUE;
@@ -301,6 +317,7 @@ function action_gatekeeper() {
  * @example actions/manual_tokens.php
  *
  * @return string|false
+ * @access private
  */
 function generate_action_token($timestamp) {
 	$site_secret = get_site_secret();
@@ -352,7 +369,7 @@ function get_site_secret() {
 }
 
 /**
- * Check if an action is registered and its file exists.
+ * Check if an action is registered and its script exists.
  *
  * @param string $action Action name
  *
@@ -366,21 +383,10 @@ function elgg_action_exists($action) {
 }
 
 /**
- * Initialize some ajaxy actions features
- */
-function actions_init() {
-	elgg_register_action('security/refreshtoken', '', 'public');
-
-	elgg_register_simplecache_view('js/languages/en');
-
-	elgg_register_plugin_hook_handler('action', 'all', 'ajax_action_hook');
-	elgg_register_plugin_hook_handler('forward', 'all', 'ajax_forward_hook');
-}
-
-/**
  * Checks whether the request was requested via ajax
  *
  * @return bool whether page was requested via ajax
+ * @since 1.8.0
  */
 function elgg_is_xhr() {
 	return isset($_SERVER['HTTP_X_REQUESTED_WITH'])
@@ -409,7 +415,8 @@ function elgg_is_xhr() {
  * @param string $type
  * @param string $reason
  * @param array $params
- *
+ * @return void
+ * @access private
  */
 function ajax_forward_hook($hook, $type, $reason, $params) {
 	if (elgg_is_xhr()) {
@@ -464,6 +471,8 @@ function ajax_forward_hook($hook, $type, $reason, $params) {
 
 /**
  * Buffer all output echo'd directly in the action for inclusion in the returned JSON.
+ * @return void
+ * @access private
  */
 function ajax_action_hook() {
 	if (elgg_is_xhr()) {
@@ -471,4 +480,16 @@ function ajax_action_hook() {
 	}
 }
 
+/**
+ * Initialize some ajaxy actions features
+ */
+function actions_init() {
+	elgg_register_action('security/refreshtoken', '', 'public');
+
+	elgg_register_simplecache_view('js/languages/en');
+
+	elgg_register_plugin_hook_handler('action', 'all', 'ajax_action_hook');
+	elgg_register_plugin_hook_handler('forward', 'all', 'ajax_forward_hook');
+}
+
 elgg_register_event_handler('init', 'system', 'actions_init');