diff options
Diffstat (limited to 'engine/lib/elgglib.php')
| -rw-r--r-- | engine/lib/elgglib.php | 759 |
1 files changed, 540 insertions, 219 deletions
diff --git a/engine/lib/elgglib.php b/engine/lib/elgglib.php index d4aa37a53..47d05327e 100644 --- a/engine/lib/elgglib.php +++ b/engine/lib/elgglib.php @@ -1,25 +1,22 @@ <?php /** - * Elgg library - * Contains important functionality core to Elgg + * Bootstrapping and helper procedural code available for use in Elgg core and plugins. * - * @package Elgg - * @subpackage Core - * @author Curverider Ltd - * @link http://elgg.org/ - */ - -/** - * Getting directories and moving the browser + * + * @package Elgg.Core + * @todo These functions can't be subpackaged because they cover a wide mix of + * puposes and subsystems. Many of them should be moved to more relevant files. */ /** - * Forwards the browser. - * Returns false if headers have already been sent and the browser cannot be moved. + * Forward to $location. + * + * Sends a 'Location: $location' header and exists. If headers have already been sent, returns FALSE. * - * @param string $location URL to forward to browser to. Can be relative path. - * @return nothing|false - */function forward($location = "") { + * @param string $location URL to forward to browser to. Can be path relative to the network's URL. + * @return False False if headers have been sent. Terminates execution if forwarding. + */ +function forward($location = "") { global $CONFIG; if (!headers_sent()) { @@ -27,14 +24,15 @@ $location = $_SERVER['HTTP_REFERER']; } - $current_page = current_page_url(); if ((substr_count($location, 'http://') == 0) && (substr_count($location, 'https://') == 0)) { $location = $CONFIG->url . $location; } // return new forward location or false to stop the forward or empty string to exit + $current_page = current_page_url(); $params = array('current_url' => $current_page, 'forward_url' => $location); $location = trigger_plugin_hook('forward', 'system', $params, $location); + if ($location) { header("Location: {$location}"); exit; @@ -47,7 +45,13 @@ } /** - * Return the current page URL. + * Returns the current page's complete URL. + * + * The current URL is assembled using the network's wwwroot and the request URI + * in $_SERVER as populated by the web server. This function will include + * any schemes, usernames and passwords, and ports. + * + * @return string The current page URL. */ function current_page_url() { global $CONFIG; @@ -74,7 +78,6 @@ function current_page_url() { $page .= ":" . $url['port']; } - //$page.="/"; $page = trim($page, "/"); $page .= $_SERVER['REQUEST_URI']; @@ -83,22 +86,33 @@ function current_page_url() { } /** - * This is a factory function which produces an ElggCache object suitable for caching file load paths. + * Returns an ElggCache object suitable for caching view + * file load paths to disk under $CONFIG->dataroot. * * @todo Can this be done in a cleaner way? * @todo Swap to memcache etc? + * + * @return ElggFileCache A cache object suitable for caching file load paths. */ function elgg_get_filepath_cache() { global $CONFIG; + + /** + * A default filestore cache using the dataroot. + */ static $FILE_PATH_CACHE; - if (!$FILE_PATH_CACHE) $FILE_PATH_CACHE = new ElggFileCache($CONFIG->dataroot); + + if (!$FILE_PATH_CACHE) { + $FILE_PATH_CACHE = new ElggFileCache($CONFIG->dataroot); + } return $FILE_PATH_CACHE; } /** - * Function which resets the file path cache. + * Deletes the view file paths cache from disk. * + * @return bool On success */ function elgg_filepath_cache_reset() { $cache = elgg_get_filepath_cache(); @@ -106,9 +120,11 @@ function elgg_filepath_cache_reset() { } /** - * Saves a filepath cache. + * Saves $data to the views file paths disk cache as + * 'view_paths'. * - * @param mixed $data + * @param mixed $data The data + * @return bool On success */ function elgg_filepath_cache_save($data) { global $CONFIG; @@ -122,8 +138,9 @@ function elgg_filepath_cache_save($data) { } /** - * Retrieve the contents of the filepath cache. + * Returns the contents of the views file paths cache from disk. * + * @return mixed Null if simplecache isn't enabled, the contents of the views file paths cache if it is. */ function elgg_filepath_cache_load() { global $CONFIG; @@ -141,25 +158,33 @@ function elgg_filepath_cache_load() { } /** - * Enable the filepath cache. + * Enables the views file paths disk cache. * + * Uses the 'viewpath_cache_enabled' datalist with a boolean value. + * Resets the views paths cache. + * + * @return null */ function elgg_enable_filepath_cache() { global $CONFIG; - datalist_set('viewpath_cache_enabled',1); + datalist_set('viewpath_cache_enabled', 1); $CONFIG->viewpath_cache_enabled = 1; elgg_filepath_cache_reset(); } /** - * Disable filepath cache. + * Disables the views file paths disk cache. + * + * Uses the 'viewpath_cache_enabled' datalist with a boolean value. + * Resets the views paths cache. * + * @return null */ function elgg_disable_filepath_cache() { global $CONFIG; - datalist_set('viewpath_cache_enabled',0); + datalist_set('viewpath_cache_enabled', 0); $CONFIG->viewpath_cache_enabled = 0; elgg_filepath_cache_reset(); } @@ -203,7 +228,9 @@ function add_submenu_item($label, $link, $group = 'default', $onclick = false, $ /** * Add an entry to the submenu. * - * @param array $item The item as array( + * @param array $item The item as: + * <code> + * array( * 'title' => 'Text to display', * 'url' => 'URL of the link', * 'id' => 'entry_unique_id' //used by children items to identify parents @@ -211,11 +238,13 @@ function add_submenu_item($label, $link, $group = 'default', $onclick = false, $ * 'selected' => BOOL // Is this item selected? (If NULL or unset will attempt to guess) * 'vars' => array() // Array of vars to pass to the navigation/submenu_item view * ) + * </code> * * @param string $context Context in which to display this menu item. 'all' will make it show up all the time. Use sparingly. * @param string $group Group for the item. Each submenu group has its own <ul> * @return BOOL * @since 1.8 + * @see elgg_prepare_submenu */ function elgg_add_submenu_item(array $item, $context = 'all', $group = 'default') { global $CONFIG; @@ -267,6 +296,7 @@ function elgg_add_submenu_item(array $item, $context = 'all', $group = 'default' * @param string $context * @param bool $sort Sort the menu items alphabetically * @since 1.8 + * @see elgg_add_submenu_item */ function elgg_prepare_submenu($context = 'main', $sort = FALSE) { global $CONFIG; @@ -355,6 +385,7 @@ function elgg_prepare_submenu($context = 'main', $sort = FALSE) { * @param object $a * @param object $b * @since 1.8 + * @see elgg_prepare_submenu */ function elgg_submenu_item_cmp($a, $b) { $a = $a->text; @@ -381,6 +412,7 @@ function get_submenu() { * @param BOOL $sort Sort by display name? * @return string Formatted HTML. * @since 1.8 + * @todo Rename to a view function. See {@trac #2320}. */ function elgg_get_submenu($context = NULL, $sort = FALSE) { global $CONFIG; @@ -403,7 +435,6 @@ function elgg_get_submenu($context = NULL, $sort = FALSE) { $temp_items = array(); while ($item = current($items)) { - $t = ''; // ignore parents created by a child but parent never defined properly if (!isset($item->text) || !($item->text)) { next($items); @@ -460,20 +491,21 @@ function elgg_get_submenu($context = NULL, $sort = FALSE) { } /** - * Automatically views likes and a like input relating to the given entity + * Returns the HTML for "likes" and "like this" on entities. * * @param ElggEntity $entity The entity to like - * @return string|false The HTML (etc) for the likes, or false on failure + * @return string|false The HTML for the likes, or false on failure * @since 1.8 + * @see @elgg_view likes/forms/edit */ function elgg_view_likes($entity){ if (!($entity instanceof ElggEntity)) { return false; } + if ($likes = trigger_plugin_hook('likes', $entity->getType(), array('entity' => $entity), false)) { return $likes; } else { - //display the form $likes = elgg_view('likes/forms/edit', array('entity' => $entity)); return $likes; } @@ -510,12 +542,6 @@ function elgg_count_comments($entity) { } } - - -/** - * Library loading and handling - */ - /** * @deprecated 1.7 */ @@ -525,13 +551,15 @@ function get_library_files($directory, $exceptions = array(), $list = array()) { } /** - * Returns a list of files in $directory + * Returns a list of files in $directory. * - * @param str $directory + * Only returns files. Does not recurse into subdirs. + * + * @param string $directory * @param array $exceptions Array of filenames to ignore * @param array $list Array of files to append to - * @param mixed $extensions Array of extensions to allow, NULL for all. (With a dot: array('.php')) - * @return array of filenames including $directory + * @param mixed $extensions Array of extensions to allow, NULL for all. Use a dot: array('.php'). + * @return array Filenames in $directory, in the form $directory/filename. */ function elgg_get_file_list($directory, $exceptions = array(), $list = array(), $extensions = NULL) { $directory = sanitise_filepath($directory); @@ -556,10 +584,25 @@ function elgg_get_file_list($directory, $exceptions = array(), $list = array(), } /** - * Ensures that the installation has all the correct files, that PHP is configured correctly, and so on. - * Leaves appropriate messages in the error register if not. + * Checks that Elgg has been installed and attempts to complete installation if not. + * + * This is called by {@link engine/start.php} immediately after Elgg libraries are loaded + * to check the installation state. + * + * Elgg's installation state is determined by (1) the existence of the engine/settings.php + * file, (2) a .htaccess file, and (3) a populated database. This function checks + * for 1 and 2, while 3 is checked by {@link is_installed()} and {@link is_db_installed()}. + * + * If settings.php doesn't exist and $_REQUEST['db_install_vars'] is present, + * this function attempts to write the values from 'db_install_vars' to settings.php. + * + * If .htaccess doens't exist this function attempts to copy htaccess_dist to .htaccess. + * + * If there are any problems, this function calls {@link register_error()} and returns FALSE. + * Since this function is called during bootstrapping, the viewtype is failsafe. + * Returning FALSE results in an InstallationException, which halts execution. * - * @return true|false True if everything is ok (or Elgg is fit enough to run); false if not. + * @return bool */ function sanitised() { $sanitised = true; @@ -608,18 +651,16 @@ function sanitised() { } /** - * Registers - */ - -/** - * Adds an array with a name to a given generic array register. - * For example, these are used for menus. + * Adds an entry in $CONFIG[$register_name][$subregister_name]. + * + * This is only used for the site-wide menu. See {@link add_menu()}. * * @param string $register_name The name of the top-level register * @param string $subregister_name The name of the subregister * @param mixed $subregister_value The value of the subregister * @param array $children_array Optionally, an array of children * @return true|false Depending on success + * @todo Can be deprecated when the new menu system is introduced. */ function add_to_register($register_name, $subregister_name, $subregister_value, $children_array = array()) { global $CONFIG; @@ -649,12 +690,15 @@ function add_to_register($register_name, $subregister_name, $subregister_value, } /** - * Removes what has been registered at [register_name][subregister_name] + * Removes a register entry from $CONFIG[register_name][subregister_name] + * + * This is used to by {@link remove_menu()} to remove site-wide menu items. * * @param string $register_name The name of the top-level register * @param string $subregister_name The name of the subregister * @return true|false Depending on success * @since 1.7.0 + * @todo Can be deprecated when the new menu system is introduced. */ function remove_from_register($register_name, $subregister_name) { global $CONFIG; @@ -680,12 +724,13 @@ function remove_from_register($register_name, $subregister_name) { } /** - * Returns a register object + * Constructs and returns a register object. * * @param string $register_name The name of the register * @param mixed $register_value The value of the register * @param array $children_array Optionally, an array of children * @return false|stdClass Depending on success + * @todo Can be deprecated when the new menu system is introduced. */ function make_register_object($register_name, $register_value, $children_array = array()) { elgg_deprecated_notice('make_register_object() is deprecated by add_submenu_item()', 1.7); @@ -706,6 +751,7 @@ function make_register_object($register_name, $register_value, $children_array = * * @param string $register_name The name of the register * @return array|false Depending on success + * @todo Can be deprecated when the new menu system is introduced. */ function get_register($register_name) { global $CONFIG; @@ -718,15 +764,16 @@ function get_register($register_name) { } /** - * Adds an item to the menu register - * This is used in the core to create the tools dropdown menu - * You can obtain the menu array by calling get_register('menu') + * Adds an item to the site-wide menu. + * + * You can obtain the menu array by calling {@link get_register('menu')} * * @param string $menu_name The name of the menu item * @param string $menu_url The URL of the page * @param array $menu_children Optionally, an array of submenu items (not currently used) * @param string $context * @return true|false Depending on success + * @todo Can be deprecated when the new menu system is introduced. */ function add_menu($menu_name, $menu_url, $menu_children = array(), $context = "") { global $CONFIG; @@ -759,11 +806,12 @@ function remove_menu($menu_name) { /** * Returns a menu item for use in the children section of add_menu() - * This is not currently used in the Elgg core + * This is not currently used in the Elgg core. * * @param string $menu_name The name of the menu item * @param string $menu_url Its URL * @return stdClass|false Depending on success + * @todo Can be deprecated when the new menu system is introduced. */ function menu_item($menu_name, $menu_url) { elgg_deprecated_notice('menu_item() is deprecated by add_submenu_item', 1.7); @@ -771,14 +819,30 @@ function menu_item($menu_name, $menu_url) { } /** - * Message register handling - * If a null $message parameter is given, the function returns the array of messages so far and empties it - * based on the $register parameters. Otherwise, any message or array of messages is added. + * Queues a message to be displayed. + * + * Messages will not be displayed immediately, but are stored in + * for later display, usually upon next page load. + * + * The method of displaying these messages differs depending upon plugins and + * viewtypes. The core default viewtype retrieves messages in {@link views/default/page_shells/default.php} + * and displays messages as javascript popups. + * + * @internal Messages are stored as strings in the $_SESSION['msg'][$register] array. + * + * @warning This function is used to both add to and clear the message + * stack. If $messages is null, $register will be returned and cleared. + * If $messages is null and $register is empty, all messages will be + * returned and removed. + * + * @important This function handles the standard {@link system_message()} ($register = + * 'messages') as well as {@link register_error()} messages ($register = 'errors'). * * @param string|array $message Optionally, a single message or array of messages to add, (default: null) * @param string $register This allows for different types of messages: "errors", "messages" (default: messages) * @param bool $count Count the number of messages (default: false) * @return true|false|array Either the array of messages, or a response regarding whether the message addition was successful + * @todo Clean up. Separate registering messages and retrieving them. */ function system_messages($message = null, $register = "messages", $count = false) { if (!isset($_SESSION['msg'])) { @@ -826,22 +890,24 @@ function system_messages($message = null, $register = "messages", $count = false * @return integer The number of messages */ function count_messages($register = "") { - return system_messages(null,$register,true); + return system_messages(null, $register, true); } /** - * An alias for system_messages($message) to handle standard user information messages + * Display a system message on next page load. * + * @see system_messages() * @param string|array $message Message or messages to add - * @return true|false Success response + * @return Bool */ function system_message($message) { return system_messages($message, "messages"); } /** - * An alias for system_messages($message) to handle error messages + * Display an error on next page load. * + * @see system_messages() * @param string|array $message Error or errors to add * @return true|false Success response */ @@ -850,26 +916,25 @@ function register_error($error) { } /** - * Event register - * Adds functions to the register for a particular event, but also calls all functions registered to an event when required - * - * Event handler functions must be of the form: - * - * event_handler_function($event, $object_type, $object); - * - * And must return true or false depending on success. A false will halt the event in its tracks and no more functions will be called. + * Register a callback function as a handler or trigger registered handlers for an event. * - * You can then simply register them using the following function. Optionally, this can be called with a priority nominally from 0 to 1000, where functions with lower priority values are called first (note that priorities CANNOT be negative): + * Elgg emits an event when certain core actions occur, like creating an entity. + * Functions registered to these events can respond to the event, prevent the + * event from completing, or ignore the event. * - * register_elgg_event_handler($event, $object_type, $function_name [, $priority = 500]); + * Callback functions are registered with {@link register_elgg_event_handler()} * - * Note that you can also use 'all' in place of both the event and object type. + * When an event is triggered ({@link trigger_elgg_event()}, each callback function is + * run in order of priority. Any callback that returns false will halt execution + * and control will be passed back to the caller. * - * To trigger an event properly, you should always use: + * @internal Events are stored in $CONFIG->events as: + * <code> + * $CONFIG->events[$event][$type][$priority] = 'callback_function' + * </code> * - * trigger_elgg_event($event, $object_type [, $object]); - * - * Where $object is optional, and represents the $object_type the event concerns. This will return true if successful, or false if it fails. + * @note You cannot generally alter the event, only halt it. + * @tip Plugin authors should use {@link register_elgg_event_handler()} to register events. * * @param string $event The type of event (eg 'init', 'update', 'delete') * @param string $object_type The type of object (eg 'system', 'blog', 'user') @@ -878,6 +943,12 @@ function register_error($error) { * @param boolean $call Set to true to call the event rather than add to it (default false) * @param mixed $object Optionally, the object the event is being performed on (eg a user) * @return true|false Depending on success + * + * @todo Separate registering and calling events. {@trac #2466} + * @example events/basic.php Register and respond to an Elgg event + * @example events/advanced.php Register for an Elgg event and optionally halt it. + * @internal @example events/emit.php Basic emitting of an Elgg event. + * @link http://docs.elgg.org/Tutorials/Core/Events */ function events($event = "", $object_type = "", $function = "", $priority = 500, $call = false, $object = null) { global $CONFIG; @@ -947,19 +1018,63 @@ function events($event = "", $object_type = "", $function = "", $priority = 500, } /** - * Alias function for events, that registers a function to a particular kind of event + * Register a callback function as an Elgg event handler. + * + * Events are emitted by Elgg when certain actions occur. Plugins + * can respond to these events or halt them completely by registering a handler + * as a callback function to an event. Multiple handlers can be registered for + * the same event and will be executed in order of $priority. Any handler + * returning false will halt the execution chain. + * + * This function is called with the event name, event type, and handler function name. + * Setting the optional $priority allows plugin authors to specify when the + * function should be run. Priorities for plugins should be 1-1000. + * + * The callback function is passed 3 arguments when called: $event, $type, and optional $params. + * + * $event is the name of event being emitted. + * $type is the type of event or object concerned. + * $params is an optional parameter passed that can include a related object. See + * specific event documentation for details on which events pass what parameteres. + * + * @tip If a priority isn't specified it is determined by the order the handler was + * registered relative to the event and type. For plugins, this generally means + * the earlier the plugin is in the load order, the earlier the priorities are for + * any event handlers. + * + * @tip $event and $object_type can use the special keyword 'all'. Handler functions registered + * with $event = all will be called for all events of type $object_type. Similarly, + * functions registered with $object_type = all will be called for all events of type + * $event, regardless of $object_type. If $event and $object_type both are 'all', the + * handler function will be called for all events. + * + * @tip Event handler functions are considered in the follow order: + * - Specific registration where 'all' isn't used. + * - Registration where 'all' is used for $event only. + * - Registration where 'all' is used for $type only. + * - Registration where 'all' is used for both. + * + * @warning If you use the 'all' keyword, you must have logic in the handler function to + * test the passed parameters before taking an action. + * + * @tip When referring to events, the preferred syntax is "event:type". * * @param string $event The event type * @param string $object_type The object type - * @param string $function The function name - * @return true|false Depending on success + * @param string $function The handler callback function name + * @param int $priority The priority of the event + * @return bool + * @link http://docs.elgg.org/Tutorials/Plugins/Events + * @example events/basic.php Basic example of registering an event handler callback function. + * @example events/advanced.php Advanced example of registering an event handler callback function and halting execution. + * @example events/all.php Example of how to use the 'all' keyword. */ function register_elgg_event_handler($event, $object_type, $function, $priority = 500) { return events($event, $object_type, $function, $priority); } /** - * Unregisters a function to a particular kind of event + * Unregisters a callback function from an event. * * @param string $event The event type * @param string $object_type The object type @@ -976,12 +1091,33 @@ function unregister_elgg_event_handler($event, $object_type, $function) { } /** - * Alias function for events, that triggers a particular kind of event + * Trigger an Elgg Event and run all handler functions registered to that event:type. + * + * This function runs all handlers regsitered to $event:$object_type or + * the special keyword 'all' for either or both. + * + * $event is usually a verb: create, update, delete, annotation. + * + * $object_type is usually a noun: object, group, user, annotation, relationship, metadata. + * + * $object is usually an Elgg* object assciated with the event. + * + * @warning Elgg events should only be called by core. Plugin authors should use + * {@link trigger_elgg_plugin_hook()} instead. + * + * @tip When referring to events, the preferred syntax is "event:type". + * + * @internal Only rarely should events be changed, added, or removed in core. + * When making changes to events, be sure to first create a ticket in trac. + * + * @internal @tip Think of $object_type as the primary namespace element, and + * $event as the secondary namespace. * * @param string $event The event type * @param string $object_type The object type * @param string $function The function name - * @return true|false Depending on success + * @return bool The result of running all handler functions. + * @link http://docs.elgg.org/Tutorials/Core/Events */ function trigger_elgg_event($event, $object_type, $object = null) { $return = true; @@ -993,27 +1129,68 @@ function trigger_elgg_event($event, $object_type, $object = null) { } /** - * Register a function to a plugin hook for a particular hook name and type, with a given priority. + * Register a callback function as a plugin hook handler. * - * eg if you want the function "export_user" to be called when the hook "export" for "user" entities - * is run, use: + * Plugin hooks allow developers to losely couple plugins and features by + * repsonding to and emitting {@link trigger_plugin_hook()} customizable hooks. + * Handler functions can respond to the hook, change the details of the hook, or ignore it. * - * register_plugin_hook("export", "user", "export_user"); + * Multiple handlers can be registered for a plugin hook, and each callback + * function is called in order of priority. If the return value of a handler + * function is not null, that value is passed to the next function in the + * call stack. When all functions have been run, the final value is passed + * back to the caller via {@link trigger_plugin_hook()}. * - * "all" is a valid value for both $hook and $entity_type. "none" is a valid value for $entity_type. + * Similar to Elgg Events, plugin hook handler functions are registered by passing + * a hook, a type, and a priority. * - * The export_user function would then be defined as: + * The callback function is passed 4 arguments when called: $hook, $type + * $value, and $params. * - * function export_user($hook, $entity_type, $returnvalue, $params); + * - str $hook The name of the hook. + * - str $type The type of hook. + * - mixed $value The return value of the last handler or the default + * value if no other handlers have been called. + * - mixed $params An optional array of parameters. Used to provide additional information + * to plugins. * - * Where $returnvalue is the return value returned by the last function returned by the hook, and - * $params is an array containing a set of parameters (or nothing). + * @internal Plugin hooks are stored in $CONFIG->hooks as: + * <code> + * $CONFIG->hooks[$hook][$type][$priority] = 'callback_function' + * </code> + * + * @tip Plugin hooks are similar to Elgg Events in that Elgg emits + * a plugin hook when certain actions occur, but a plugin hook allows you to alter the + * parameters, as well as halt execution. + * + * @tip If a priority isn't specified it is determined by the order the handler was + * registered relative to the event and type. For plugins, this generally means + * the earlier the plugin is in the load order, the earlier the priorities are for + * any event handlers. + * + * @tip Like Elgg Events, $hook and $type can use the special keyword 'all'. + * Handler functions registered with $hook = all will be called for all hooks + * of type $type. Similarly, handlers registered with $type = all will be + * called for all hooks of type $event, regardless of $object_type. If $hook + * and $type both are 'all', the handler will be called for all hooks. + * + * @tip Plugin hooks are sometimes used to gather lists from plugins. This is + * usually done by pushing elements into an array passed in $params. Be sure + * to append to and then return $value so you don't overwrite other plugin's + * values. + * + * @warning Unlike Elgg Events, a handler that returns false will NOT halt the + * execution chain. * * @param string $hook The name of the hook - * @param string $type The type of the hook (NB Can be an ElggEntity type [user, object, group, site] or custom-defined 'get_sections') + * @param string $type The type of the hook * @param string $function The name of a valid function to be run * @param string $priority The priority - 0 is first, 1000 last, default is 500 - * @return true|false Depending on success + * @return bool + * + * @example hooks/register/basic.php Registering for a plugin hook and examining the variables. + * @example hooks/register/advanced.php Registering for a plugin hook and changing the params. + * @link http://docs.elgg.org/Tutorials/Plugins/Hooks */ function register_plugin_hook($hook, $type, $function, $priority = 500) { global $CONFIG; @@ -1043,7 +1220,7 @@ function register_plugin_hook($hook, $type, $function, $priority = 500) { } /** - * Unregister a function to a plugin hook for a particular entity type + * Unregister a callback function as a plugin hook. * * @param string $hook The name of the hook * @param string $entity_type The name of the type of entity (eg "user", "object" etc) @@ -1060,18 +1237,38 @@ function unregister_plugin_hook($hook, $entity_type, $function) { } /** - * Triggers a plugin hook, with various parameters as an array. For example, to provide - * a 'foo' hook that concerns the type 'bar', with a parameter called 'param1' - * with value 'value1', that by default returns true, you'd call: + * Trigger a Plugin Hook and run all handler functions registered to that hook:type. + * + * This function runs all handlers regsitered to $hook:$type or + * the special keyword 'all' for either or both. + * + * Use $params to send additional information to the handler functions. + * + * $returnvalue Is the initial value to pass to the handlers, which can + * then change it. It is useful to use $returnvalue to set defaults. + * If no handlers are registered, $returnvalue is immediately returned. * - * trigger_plugin_hook('foo', 'bar', array('param1' => 'value1'), true); + * $hook is usually a verb: import, get_views, output. * - * @see register_plugin_hook + * $type is usually a noun: user, ecml, page. + * + * @tip Like Elgg Events, $hook and $type can use the special keyword 'all'. + * Handler functions registered with $hook = all will be called for all hooks + * of type $type. Similarly, handlers registered with $type = all will be + * called for all hooks of type $event, regardless of $object_type. If $hook + * and $type both are 'all', the handler will be called for all hooks. + * + * @see register_plugin_hook() * @param string $hook The name of the hook to trigger (NB: "all" will trigger for all $types regardless of $hook value) * @param string $type The type of the hook to trigger (NB: "all" will trigger for all $hooks regardless of $type value) - * @param array $params Any parameters. It's good practice to name the keys, i.e. by using array('name' => 'value', 'name2' => 'value2') + * @param mixed $params Additional parameters to pass to the handlers * @param mixed $returnvalue An initial return value - * @return mixed|null The cumulative return value for the plugin hook functions + * @return mixed|null The return value of the last handler function called + * + * @example hooks/trigger/basic.php Trigger a hook that determins if execution should continue. + * @example hooks/trigger/advanced.php Trigger a hook with a default value and use the results to populate a menu. + * @example hooks/basic.php Trigger and respond to a basic plugin hook. + * @link http://docs.elgg.org/Tutorials/Plugins/Hooks */ function trigger_plugin_hook($hook, $type, $params = null, $returnvalue = null) { global $CONFIG; @@ -1088,7 +1285,9 @@ function trigger_plugin_hook($hook, $type, $params = null, $returnvalue = null) if (!empty($CONFIG->hooks['all'][$type]) && is_array($CONFIG->hooks['all'][$type])) { foreach($CONFIG->hooks['all'][$type] as $hookfunction) { $temp_return_value = $hookfunction($hook, $type, $returnvalue, $params); - if (!is_null($temp_return_value)) $returnvalue = $temp_return_value; + if (!is_null($temp_return_value)) { + $returnvalue = $temp_return_value; + } } } @@ -1114,12 +1313,15 @@ function trigger_plugin_hook($hook, $type, $params = null, $returnvalue = null) } /** - * Error handling - */ - -/** - * PHP Error handler function. - * This function acts as a wrapper to catch and report PHP error messages. + * Intercepts catchable PHP errors. + * + * @warning This function should never be called directly. + * + * @internal + * For catchable fatal errors, throws an Exception with the error. + * + * For non-fatal errors, depending upon the debug settings, either + * log the error or ignore it. * * @see http://www.php.net/set-error-handler * @param int $errno The level of the error raised @@ -1156,18 +1358,21 @@ function __elgg_php_error_handler($errno, $errmsg, $filename, $linenum, $vars) { } /** - * Throws a message to the Elgg logger + * Display or log a message. + * + * If $level is >= to the debug setting in {@link $CONFIG->debug}, the + * message will be sent to {@link elgg_dump()}. Messages with lower + * priority than {@link $CONFIG->debug} are ignored. * - * The Elgg log is currently implemented such that any messages sent at a level - * greater than or equal to the debug setting will be sent to elgg_dump. - * The default location for elgg_dump is the screen except for notices. + * {@link elgg_dump()} outputs all levels but NOTICE to screen by default. * - * Note: No messages will be displayed unless debugging has been enabled. + * @note No messages will be displayed unless debugging has been enabled. * * @param str $message User message * @param str $level NOTICE | WARNING | ERROR | DEBUG * @return bool * @since 1.7.0 + * @todo This is complicated and confusing. Using int constants for debug levels will make things easier. */ function elgg_log($message, $level='NOTICE') { global $CONFIG; @@ -1205,11 +1410,13 @@ function elgg_log($message, $level='NOTICE') { } /** - * Extremely generic var_dump-esque wrapper + * Logs or displays $value. + * + * If $to_screen is true, $value is displayed to screen. Else, + * it is handled by PHP's {@link error_log()} function. * - * Immediately dumps the given $value as a human-readable string. - * The $value can instead be written to the screen or server log depending on - * the value of the $to_screen flag. + * A {@elgg_plugin_hook debug:log} is called. If a handler returns + * false, it will stop the default logging method. * * @param mixed $value * @param bool $to_screen @@ -1245,8 +1452,9 @@ function elgg_dump($value, $to_screen = TRUE, $level = 'NOTICE') { } /** - * Custom exception handler. - * This function catches any thrown exceptions and handles them appropriately. + * Intercepts, logs, and display uncaught exceptions. + * + * @warning This function should never be called directly. * * @see http://www.php.net/set-exception-handler * @param Exception $exception The exception being handled @@ -1254,33 +1462,43 @@ function elgg_dump($value, $to_screen = TRUE, $level = 'NOTICE') { function __elgg_php_exception_handler($exception) { error_log("*** FATAL EXCEPTION *** : " . $exception); - ob_end_clean(); // Wipe any existing output buffer + // Wipe any existing output buffer + ob_end_clean(); // make sure the error isn't cached header("Cache-Control: no-cache, must-revalidate", true); header('Expires: Fri, 05 Feb 1982 00:00:00 -0500', true); + // @todo Why don't we send a 500 header? //header("Internal Server Error", true, 500); - $body = elgg_view("messages/exceptions/exception",array('object' => $exception)); + $body = elgg_view("messages/exceptions/exception", array('object' => $exception)); page_draw(elgg_echo('exception:title'), $body); } /** - * Data lists + * An array of key value pairs from the datalists table. + * + * Used as a cache in datalist functions. + * + * @global array $DATALIST_CACHE */ - $DATALIST_CACHE = array(); /** - * Get the value of a particular piece of data in the datalist + * Get the value of a datalist element. * - * @param string $name The name of the datalist - * @return string|false Depending on success + * @internal Datalists are stored in the datalist table. + * + * @tip Use datalists to store information common to a full installation. + * + * @param string $name The name of the datalist element + * @return string|false The datalist value or false if it doesn't exist. */ function datalist_get($name) { global $CONFIG, $DATALIST_CACHE; - // We need this, because sometimes datalists are received before the database is created + // We need this, because sometimes datalists are attempted + // to be retrieved before the database is created if (!is_db_installed()) { return false; } @@ -1320,28 +1538,17 @@ function datalist_get($name) { } } - - /*if ($row = get_data_row("SELECT value from {$CONFIG->dbprefix}datalists where name = '{$name}' limit 1")) { - $DATALIST_CACHE[$name] = $row->value; - - // Cache it if memcache is available - if ($datalist_memcache) $datalist_memcache->save($name, $row->value); - - return $row->value; - }*/ - return false; } /** - * Sets the value for a system-wide piece of data (overwriting a previous value if it exists) + * Set the value for a datalist element. * * @param string $name The name of the datalist * @param string $value The new value * @return true */ function datalist_set($name, $value) { - global $CONFIG, $DATALIST_CACHE; $name = sanitise_string($name); @@ -1357,7 +1564,6 @@ function datalist_set($name, $value) { $datalist_memcache->delete($name); } - //delete_data("delete from {$CONFIG->dbprefix}datalists where name = '{$name}'"); insert_data("INSERT into {$CONFIG->dbprefix}datalists set name = '{$name}', value = '{$value}' ON DUPLICATE KEY UPDATE value='{$value}'"); $DATALIST_CACHE[$name] = $value; @@ -1366,14 +1572,25 @@ function datalist_set($name, $value) { } /** - * Runs a function once - not per page load, but per installation. - * If you like, you can also set the threshold for the function execution - i.e., - * if the function was executed before or on $timelastupdatedcheck, this - * function will run it again. + * Run a function one time per installation. + * + * If you pass a timestamp as the second argument, it will run the function + * only if (i) it has never been run before or (ii) the timestamp is >= + * the last time it was run. + * + * @warning Functions are determined by their name. If you change the name of a function + * it will be run again. + * + * @tip Use $timelastupdatedcheck in your plugins init function to perform automated + * upgrades. Schedule a function to run once and pass the timestamp of the new release. + * This will cause the run once function to be run on all installations. To perform + * additional upgrades, create new functions for each release. + * + * @internal A datalist entry $functioname is created with the value of time(). * * @param string $functionname The name of the function you want to run. - * @param int $timelastupdatedcheck Optionally, the UNIX epoch timestamp of the execution threshold - * @return true|false Depending on success. + * @param int $timelastupdatedcheck A UNIX timestamp. If time() is > than this, this function will be run again. + * @return bool */ function run_function_once($functionname, $timelastupdatedcheck = 0) { if ($lastupdated = datalist_get($functionname)) { @@ -1383,7 +1600,7 @@ function run_function_once($functionname, $timelastupdatedcheck = 0) { } if (is_callable($functionname) && $lastupdated <= $timelastupdatedcheck) { $functionname(); - datalist_set($functionname,time()); + datalist_set($functionname, time()); return true; } else { return false; @@ -1392,12 +1609,21 @@ function run_function_once($functionname, $timelastupdatedcheck = 0) { /** * Sends a notice about deprecated use of a function, view, etc. - * Note: This will ALWAYS at least log a warning. Don't use to pre-deprecate things. + * + * This function either displays or logs the deprecation message, + * depending upon the deprecation policies in {@link CODING.txt}. + * Logged messages are sent with the level of 'WARNING'. + * + * A user-visual message will be displayed if $dep_version is greater + * than 1 minor releases lower than the current Elgg version, or at all + * lower than the current Elgg major version. + * + * @note This will always at least log a warning. Don't use to pre-deprecate things. * This assumes we are releasing in order and deprecating according to policy. * + * @see CODING.txt * @param str $msg Message to log / display. - * @param str $version human-readable *release* version the function was deprecated. No bloody A, B, (R)C, or D. - * + * @param str $version human-readable *release* version: 1.7, 1.7.3 * @return bool * @since 1.7.0 */ @@ -1406,7 +1632,6 @@ function elgg_deprecated_notice($msg, $dep_version) { // if it's a 2 minor releases behind, visual and logged // if it's 1 minor release behind, logged. // bugfixes don't matter because you're not deprecating between them, RIGHT? - if (!$dep_version) { return FALSE; } @@ -1450,13 +1675,7 @@ function elgg_deprecated_notice($msg, $dep_version) { /** - * Privilege elevation and gatekeeper code - */ - - -/** - * Gatekeeper function which ensures that a we are being executed from - * a specified location. + * Checks if code is being called from a certain function. * * To use, call this function with the function name (and optional file location) that it has to be called * from, it will either return true or false. @@ -1486,6 +1705,7 @@ function elgg_deprecated_notice($msg, $dep_version) { * @param mixed $function The function that this function must have in its call stack, * to test against a method pass an array containing a class and method name. * @param string $file Optional file that the function must reside in. + * @todo This is neat but is it necessary? */ function call_gatekeeper($function, $file = "") { // Sanity check @@ -1516,7 +1736,6 @@ function call_gatekeeper($function, $file = "") { return false; } - // If file then check that this it is being called from this function if ($file) { $mirror = null; @@ -1544,6 +1763,7 @@ function call_gatekeeper($function, $file = "") { * @param string $path The full path and filename that this function must have in its call stack If a partial path is given and $include_subdirs is true, then the function will return true if called by any function in or below the specified path. * @param bool $include_subdirs Are subdirectories of the path ok, or must you specify an absolute path and filename. * @param bool $strict_mode If true then the calling method or function must be directly called by something on $path, if false the whole call stack is searched. + * @todo Again, very neat, but is it necessary? */ function callpath_gatekeeper($path, $include_subdirs = true, $strict_mode = false) { global $CONFIG; @@ -1590,7 +1810,9 @@ function callpath_gatekeeper($path, $include_subdirs = true, $strict_mode = fals } /** - * Returns true or false depending on whether a PHP .ini setting is on or off + * Return the state of a php.ini setting. + * + * Normalizes the setting to bool. * * @param string $ini_get_arg The INI setting * @return true|false Depending on whether it's on or off @@ -1605,10 +1827,13 @@ function ini_get_bool($ini_get_arg) { } /** + * Returns true is string is not empty, false, or null. + * * Function to be used in array_filter which returns true if $string is not null. * * @param string $string * @return bool + * @todo This is used once in metadata.php. Use a lambda function instead. */ function is_not_null($string) { if (($string==='') || ($string===false) || ($string===null)) { @@ -1620,11 +1845,13 @@ function is_not_null($string) { /** - * Normalise the singular keys in an options array - * to the plural keys. + * Normalise the singular keys in an options array to plural keys. * - * @param $options - * @param $singulars + * Used in elgg_get_entities*() functions to support shortcutting plural + * names by singular names. + * + * @param array $options The options array. $options['keys'] = 'values'; + * @param array $singulars A list of sinular words to pluralize by adding 's'. * @return array * @since 1.7.0 */ @@ -1647,15 +1874,18 @@ function elgg_normalise_plural_options_array($options, $singulars) { } /** - * Get the full URL of the current page. + * Return the full URL of the current page. * * @return string The URL + * @todo Combine / replace with current_page_url() */ function full_url() { $s = empty($_SERVER["HTTPS"]) ? '' : ($_SERVER["HTTPS"] == "on") ? "s" : ""; $protocol = substr(strtolower($_SERVER["SERVER_PROTOCOL"]), 0, strpos(strtolower($_SERVER["SERVER_PROTOCOL"]), "/")) . $s; $port = ($_SERVER["SERVER_PORT"] == "80" || $_SERVER["SERVER_PORT"] == "443") ? "" : (":".$_SERVER["SERVER_PORT"]); + // This is here to prevent XSS in poorly written browsers used by 80% of the population. + // {@trac [5813]} $quotes = array('\'', '"'); $encoded = array('%27', '%22'); @@ -1675,6 +1905,8 @@ function full_url() { * xxx.xxx.xxx.xxx/nn (nn = # bits, cisco style -- i.e. /24 = class C) * Does not match: * xxx.xxx.xxx.xx[yyy-zzz] (range, partial octets not supported) + * + * @todo not used at all. */ function test_ip($range, $ip) { $result = 1; @@ -1737,10 +1969,9 @@ function test_ip($range, $ip) { * @param array $networks * @param string $ip * @return bool + * @todo not used at all in core. */ function is_ip_in_array(array $networks, $ip) { - global $SYSTEM_LOG; - foreach ($networks as $network) { if (test_ip(trim($network), $ip)) { return true; @@ -1753,7 +1984,9 @@ function is_ip_in_array(array $networks, $ip) { require_once dirname(dirname(__FILE__)).'/classes/Friendable.php'; /** - * Rebuilds a parsed (partial) URL + * Builds a URL from the a parts array like one returned by {@link parse_url()}. + * + * @note If only partial information is passed, a partial URL will be returned. * * @param array $parts Associative array of URL components like parse_url() returns * @param bool $htmlencode HTML Encode the url? @@ -1777,14 +2010,22 @@ function elgg_http_build_url(array $parts, $html_encode = TRUE) { } } - /** * Adds action tokens to URL * + * As of 1.7.0 action tokens are required on all actions. + * Use this function to append action tokens to a URL's GET parameters. + * This will preserve any existing GET parameters. + * + * @note If you are using {@elgg_view input/form} you don't need to + * add tokens to the action. The form view automatically handles + * tokens. + * * @param str $link Full action URL * @param bool $htmlencode html encode the url? * @return str URL with action tokens * @since 1.7.0 + * @link http://docs.elgg.org/Tutorials/Actions */ function elgg_add_action_tokens_to_url($url, $html_encode = TRUE) { $components = parse_url($url); @@ -1808,7 +2049,10 @@ function elgg_add_action_tokens_to_url($url, $html_encode = TRUE) { return elgg_http_build_url($components, $html_encode); } + /** + * Add action tokens to URL. + * * @deprecated 1.7 final */ function elgg_validate_action_url($url) { @@ -1817,12 +2061,15 @@ function elgg_validate_action_url($url) { return elgg_add_action_tokens_to_url($url); } + /** - * Removes a single elementry from a (partial) url query. + * Removes an element from a URL's query string. + * + * @note You can send a partial URL string. * * @param string $url * @param string $element - * @return string + * @return string The new URL with the query element removed. * @since 1.7.0 */ function elgg_http_remove_url_query_element($url, $element) { @@ -1844,13 +2091,12 @@ function elgg_http_remove_url_query_element($url, $element) { return $string; } - /** - * Adds get params to $url + * Adds an element or elements to a URL's query string. * - * @param str $url - * @param array $elements k/v pairs. - * @return str + * @param str $url The URL + * @param array $elements key/value pairs to add to the URL + * @return str The new URL with the query strings added * @since 1.7.0 */ function elgg_http_add_url_query_elements($url, array $elements) { @@ -1872,16 +2118,12 @@ function elgg_http_add_url_query_elements($url, array $elements) { return $string; } - /** - * Breadcrumb support. - */ - -/** - * Adds a breadcrumb to the stack + * Adds a breadcrumb to the breadcrumbs stack. * * @param string $title The title to display * @param string $link Optional. The link for the title. + * @link http://docs.elgg.org/Tutorials/UI/Breadcrumbs */ function elgg_push_breadcrumb($title, $link = NULL) { global $CONFIG; @@ -1897,6 +2139,7 @@ function elgg_push_breadcrumb($title, $link = NULL) { * Removes last breadcrumb entry. * * @return array popped item. + * @link http://docs.elgg.org/Tutorials/UI/Breadcrumbs */ function elgg_pop_breadcrumb() { global $CONFIG; @@ -1909,9 +2152,10 @@ function elgg_pop_breadcrumb() { } /** - * Returns all breadcrumbs + * Returns all breadcrumbs as an array of array('title' => 'Readable Title', 'link' => 'URL') * * @return array Breadcrumbs + * @link http://docs.elgg.org/Tutorials/UI/Breadcrumbs */ function elgg_get_breadcrumbs() { global $CONFIG; @@ -1919,16 +2163,13 @@ function elgg_get_breadcrumbs() { return (is_array($CONFIG->breadcrumbs)) ? $CONFIG->breadcrumbs : array(); } - -/** - * Sticky forms - */ - /** * Load all the REQUEST variables into the sticky form cache * * Call this from an action when you want all your submitted variables * available if the submission fails validation and is sent back to the form + * + * @link http://docs.elgg.org/Tutorials/UI/StickyForms */ function elgg_make_sticky_form($form_name) { global $CONFIG; @@ -1947,7 +2188,6 @@ function elgg_make_sticky_form($form_name) { } } - /** * Clear the sticky form cache * @@ -1956,23 +2196,25 @@ function elgg_make_sticky_form($form_name) { * after a validation error. * * @param string $name Form namespace + * @link http://docs.elgg.org/Tutorials/UI/StickyForms */ function elgg_clear_sticky_form($form_name) { unset($_SESSION['sticky_forms'][$form_name]); } /** - * Has this form been made sticky + * Has this form been made sticky? * * @param string $name Form namespace * @return boolean + * @link http://docs.elgg.org/Tutorials/UI/StickyForms */ function elgg_is_sticky_form($form_name) { return isset($_SESSION['sticky_forms'][$form_name]); } /** - * Get a specific stick variable + * Get a specific sticky variable * * @param string $variable The name of the variable * @param mixed $default Default value if the variable does not exist in sticky cache @@ -1980,6 +2222,7 @@ function elgg_is_sticky_form($form_name) { * @return mixed * * @todo should this filter the default value? + * @link http://docs.elgg.org/Tutorials/UI/StickyForms */ function elgg_get_sticky_value($form_name, $variable, $default = NULL, $filter_result = true) { if (isset($_SESSION['sticky_forms'][$form_name][$variable])) { @@ -1997,6 +2240,7 @@ function elgg_get_sticky_value($form_name, $variable, $default = NULL, $filter_r * Clear a specific sticky variable * * @param string $variable The name of the variable to clear + * @link http://docs.elgg.org/Tutorials/UI/StickyForms */ function elgg_clear_sticky_value($form_name, $variable) { unset($_SESSION['sticky_forms'][$form_name][$variable]); @@ -2005,6 +2249,7 @@ function elgg_clear_sticky_value($form_name, $variable) { /** * Returns the current active sticky form. * @return mixed Str | FALSE + * @link http://docs.elgg.org/Tutorials/UI/StickyForms */ function elgg_get_active_sticky_form() { global $CONFIG; @@ -2018,13 +2263,22 @@ function elgg_get_active_sticky_form() { return (elgg_is_sticky_form($form_name)) ? $form_name : FALSE; } +/** + * Sets the active sticky form. + * + * @param string $form_name + * @link http://docs.elgg.org/Tutorials/UI/StickyForms + */ function elgg_set_active_sticky_form($form_name) { global $CONFIG; $CONFIG->active_sticky_form = $form_name; } + /** - * Returns the PHP INI setting in bytes + * Returns a PHP INI setting in bytes. + * + * @tip Use this for arithmetic when determining if a file can be uploaded. * * @param str $setting * @return int @@ -2051,10 +2305,14 @@ function elgg_get_ini_setting_in_bytes($setting) { } /** - * Server javascript pages. + * Serve javascript pages. + * + * Searches for views under js/ and outputs them with special + * headers for caching control. * * @param $page * @return unknown_type + * @elgg_pagehandler js */ function js_page_handler($page) { if (is_array($page) && sizeof($page)) { @@ -2073,9 +2331,14 @@ function js_page_handler($page) { } /** - * This function is a shutdown hook registered on startup which does nothing more than trigger a - * shutdown event when the script is shutting down, but before database connections have been dropped etc. + * Emits a shutdown:system event upon PHP shutdown, but before database connections are dropped. + * + * @tip Register for the shutdown:system event to perform functions at the end of page loads. + * + * @warning Using this event to perform long-running functions is not very useful. Servers will hold pages until processing is done + * before sending them out to the browser. * + * @see register_shutdown_hook() */ function __elgg_shutdown_hook() { global $START_MICROTIME; @@ -2088,28 +2351,31 @@ function __elgg_shutdown_hook() { } /** - * Register functions for Elgg core + * Elgg's main init. * - * @return unknown_type + * Handles core actions for comments and likes, the JS pagehandler, and the shutdown function. + * + * @elgg_event_handler init system */ function elgg_init() { global $CONFIG; - // Actions register_action('comments/add'); register_action('comments/delete'); register_action('likes/add'); register_action('likes/delete'); - // Page handler for JS - register_page_handler('js','js_page_handler'); + register_page_handler('js', 'js_page_handler'); - // Register an event triggered at system shutdown + // Trigger the shutdown:system event upon PHP shutdown. register_shutdown_function('__elgg_shutdown_hook'); } /** - * Walled garden system:index plugin hook. + * Intercepts the index page when Walled Garden mode is enabled. + * + * @link http://docs.elgg.org/Tutorials/WalledGarden + * @elgg_plugin_hook index system */ function elgg_walled_garden_index() { $login = elgg_view('account/forms/login_walled_garden'); @@ -2121,7 +2387,9 @@ function elgg_walled_garden_index() { } /** - * Runs unit tests for the API. + * Adds unit tests for the general API. + * + * @elgg_plugin_hook unit_tests system */ function elgg_api_test($hook, $type, $value, $params) { global $CONFIG; @@ -2132,9 +2400,14 @@ function elgg_api_test($hook, $type, $value, $params) { } /** - * Sorts out the featured URLs and the "more" dropdown + * Returns the main site menu. + * + * @note The main site menu is split into "featured" links and + * "more" links. + * * @return array ('featured_urls' and 'more') * @since 1.8 + * @link http://docs.elgg.org/Tutorials/UI/SiteMenu */ function elgg_get_nav_items() { $menu_items = get_register('menu'); @@ -2152,7 +2425,7 @@ function elgg_get_nav_items() { // make sure the url is a valid link. // this prevents disabled plugins leaving behind - // valid links when no using a pagehandler. + // valid links when not using a pagehandler. foreach ($featured_urls_info as $info) { if (in_array($info->value->url, $valid_urls)) { $featured_urls[] = $info->value->url; @@ -2174,8 +2447,14 @@ function elgg_get_nav_items() { } /** - * Hook that registers the custom menu items. + * Registers any custom menu items with the main Site Menu. + * + * @note Custom menu items are added through the admin interface. Plugins + * can add standard menu items by using {@link add_menu()}. + * * @since 1.8 + * @link http://docs.elgg.org/Tutorials/UI/SiteMenu + * @elgg_event_handler init system */ function add_custom_menu_items() { if ($custom_items = get_config('menu_items_custom_items')) { @@ -2186,7 +2465,11 @@ function add_custom_menu_items() { } /** - * Test two URLs to see if they are functionally identical. + * Test if two URLs are functionally identical. + * + * @tip If $ignore_params is used, neither the name nor its value will be considered when comparing. + * + * @tip The order of GET params doesn't matter. * * @param string $url1 * @param string $url2 @@ -2277,9 +2560,16 @@ function elgg_http_url_is_identical($url1, $url2, $ignore_params = array('offset } /** - * Checks walled garden status upon Elgg init. + * Checks the status of the Walled Garden and forwards to a login page + * if required. + * + * If the site is in Walled Garden mode, all page except those registered as + * plugin pages by {@elgg_hook public_pages walled_garden} will redirect to + * a login page. * * @since 1.8 + * @elgg_event_handler init system + * @link http://docs.elgg.org/Tutorials/WalledGarden */ function elgg_walled_garden() { global $CONFIG; @@ -2307,8 +2597,10 @@ function elgg_get_array_value($key, array $array, $default = NULL) { /** * Sorts a 3d array by specific element. - * Will re-index numeric indexes. - * NB: This operates the same as the built-in sort functions. + * + * @warning Will re-index numeric indexes. + * + * @note This operates the same as the built-in sort functions. * ie, sorts the array and returns a bool for success. * * Do this: elgg_sort_3d_array_by_value($my_array); @@ -2334,29 +2626,58 @@ function elgg_sort_3d_array_by_value(&$array, $element, $sort_order = SORT_ASC, return array_multisort($sort, $sort_order, $sort_type, $array); } -/** - * Some useful constant definitions + +/**#@+ + * Controlls access levels on ElggEntity entities, metadata, and annotations. + * + * @var int */ define('ACCESS_DEFAULT', -1); define('ACCESS_PRIVATE', 0); define('ACCESS_LOGGED_IN', 1); define('ACCESS_PUBLIC', 2); define('ACCESS_FRIENDS', -2); +/**#@-*/ /** - * @since 1.7.0 + * Constant to request the value of a parameter be ignored in elgg_get_*() functions + * + * @see elgg_get_entities() + * @var NULL + * @since 1.7 */ define('ELGG_ENTITIES_ANY_VALUE', NULL); + +/** + * Constant to request the value of a parameter be nothing in elgg_get_*() functions. + * + * @see elgg_get_entities() + * @var int 0 + * @since 1.7 + */ define('ELGG_ENTITIES_NO_VALUE', 0); /** - * @since 1.7.2 + * Used in calls to forward() to specify the browser should be redirected to the + * referring page. + * + * @see forward + * @var unknown_type */ define('REFERRER', -1); + +/** + * Alternate spelling for REFERRER. Included because of some bad documentation + * in the original HTTP spec. + * + * @see forward() + * @link http://en.wikipedia.org/wiki/HTTP_referrer#Origin_of_the_term_referer + * @var int -1 + */ define('REFERER', -1); register_elgg_event_handler('init', 'system', 'elgg_init'); register_plugin_hook('unit_test', 'system', 'elgg_api_test'); register_elgg_event_handler('init', 'system', 'add_custom_menu_items', 1000); -register_elgg_event_handler('init', 'system', 'elgg_walled_garden', 1000); +register_elgg_event_handler('init', 'system', 'elgg_walled_garden', 1000);
\ No newline at end of file |