<?php
/**
- * Elgg actions
- * Allows system modules to specify actions
+ * Elgg Actions
*
- * @package Elgg
- * @subpackage Core
- * @author Curverider Ltd
- * @link http://elgg.org/
+ * Actions are the primary controllers (The C in MVC) in Elgg. The 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, rewrite a rule in .htaccess passes the action name to
+ * engine/handlers/action_handler.php, which dispatches the action.
+ *
+ * An action name should be registered to exactly one file in the system, usually under
+ * the actions/ directory.
+ *
+ * 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.
+ *
+ * To include security tokens for actions called via GET, use
+ * {@link elgg_add_security_tokens_to_url()}.
+ *
+ * Action tokens can be manually generated by using {@link generate_action_token()}.
+ *
+ * @tip When registered, actions can be restricted to logged in or admin users.
+ *
+ * @tip Action URLs should be called with a trailing / to prevent 301 redirects.
+ *
+ * @package Elgg.Core
+ * @subpackage Actions
+ * @link http://docs.elgg.org/Actions
+ * @link http://docs.elgg.org/Actions/Tokens
*/
-// Action setting and run *************************************************
-
/**
-* Loads an action script, if it exists, then forwards elsewhere
+* Perform an action.
+*
+* This function executes the action with name $action as
+* registered by {@link 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 regiser_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 register_action()
*/
function action($action, $forwarder = "") {
global $CONFIG;
if ($CONFIG->actions[$action]['public'] || get_loggedin_userid()) {
// Trigger action event
- // @todo This is only called before the primary action is called. We need to rethink actions for 1.5
+ // @todo This is only called before the primary action is called.
$event_result = true;
$event_result = trigger_plugin_hook('action', $action, null, $event_result);
// Include action
- // Event_result being false doesn't produce an error -
+ // Event_result being false doesn't produce an error
// since i assume this will be handled in the hook itself.
// @todo make this better!
if ($event_result) {
if (!include($CONFIG->actions[$action]['file'])) {
- register_error(sprintf(elgg_echo('actionundefined'),$action));
+ register_error(sprintf(elgg_echo('actionundefined'), $action));
}
}
} else {
register_error(elgg_echo('actionunauthorized'));
}
} else {
- register_error(sprintf(elgg_echo('actionundefined'),$action));
+ register_error(sprintf(elgg_echo('actionundefined'), $action));
}
forward($CONFIG->url . $forwarder);
}
/**
- * Registers a particular action in memory
+ * 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()}.
+ *
+ * $file must be the full path of the file to register, or a path relative
+ * to the core actions/ dir.
+ *
+ * Actions should be namedspaced for your plugin. Example:
+ * <code>
+ * register_action('myplugin/save_settings', ...);
+ * </code>
+ *
+ * @tip Put action files under the actions/ directory of your plugin.
+ *
+ * @tip You don't need to include engine/start.php, call {@link gatekeeper()},
+ * or call {@link admin_gatekeeper()}.
+ *
+ * @internal Actions are saved in $CONFIG->actions as an array in the form:
+ * <code>
+ * array(
+ * 'file' => '/location/to/file.php',
+ * 'public' => BOOL If false, user must be logged in.
+ * 'admin' => BOOL If true, user must be admin (implies plugin = false)
+ * )
+ * </code>
*
* @param string $action The name of the action (eg "register", "account/settings/save")
* @param boolean $public Can this action be accessed by people not logged into the system?
* @param string $filename Optionally, the filename where this action is located
* @param boolean $admin_only Whether this action is only available to admin users.
+ * @see action()
+ * @see http://docs.elgg.org/Actions
*/
function register_action($action, $public = false, $filename = "", $admin_only = false) {
global $CONFIG;
* @param string $event Events API required parameters
* @param string $object_type Events API required parameters
* @param string $object Events API required parameters
+ * @todo remove
*/
function actions_init($event, $object_type, $object) {
register_action("error");
}
/**
- * Validate an action token, returning true if valid and false if not
+ * 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.
*
- * @return unknown
+ * 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. Pulls from $_REQUEST['__elgg_token'] if NULL.
+ * @param mixed $ts The time stamp to test against. Pulls from $_REQUEST['__elgg_ts'] if NULL.
+ * @return bool
+ * @see generate_action_token()
+ * @link http://docs.elgg.org/Actions/Tokens
*/
function validate_action_token($visibleerrors = TRUE, $token = NULL, $ts = NULL) {
if (!$token) {
}
/**
-* Action gatekeeper.
+* 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.
*
-* Place at the head of actions.
+* @access private
+* @return mixed True if valid, or redirects to front page and exists.
*/
function action_gatekeeper() {
if (validate_action_token()) {
}
/**
- * Generate a token for the current user suitable for being placed in a hidden field in action forms.
+ * Generate an action token.
+ *
+ * Action tokens are based on timestamps as returned by {@link time()}.
+ * They are valid for one hour.
+ *
+ * Action tokens should be passed to all actions name __elgg_ts and __elgg_token.
+ *
+ * @warning Action tokens are required for all actions.
*
* @param int $timestamp Unix timestamp
+ * @see @elgg_view input/securitytoken
+ * @see @elgg_view input/form
+ * @example actions/manual_tokens.php
*/
function generate_action_token($timestamp) {
- // Get input values
$site_secret = get_site_secret();
-
- // Current session id
$session_id = session_id();
-
// Session token
$st = $_SESSION['__elgg_session'];
if (($site_secret) && ($session_id)) {
- return md5($site_secret.$timestamp.$session_id.$st);
+ return md5($site_secret . $timestamp . $session_id . $st);
}
return FALSE;
}
/**
- * Initialise the site secret.
+ * Initialise the site secret hash.
+ *
+ * Used during installation and saves as a datalist.
*
+ * @return mixed The site secret hash or false
+ * @access private
+ * @todo Move to better file.
*/
function init_site_secret() {
$secret = md5(rand().microtime());
}
/**
- * Retrieve the site secret.
+ * Returns the site secret.
+ *
+ * Used to generate difficult to guess hashes for sessions and action tokens.
*
+ * @return string Site secret.
+ * @access private
+ * @todo Move to better file.
*/
function get_site_secret() {
$secret = datalist_get('__site_secret__');
return (isset($CONFIG->actions[$action]) && file_exists($CONFIG->actions[$action]['file']));
}
-register_elgg_event_handler("init","system","actions_init");
+register_elgg_event_handler("init", "system", "actions_init");
\ No newline at end of file
projects / lorea / elgg.git / commitdiff