aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorcash <cash@36083f99-b078-4883-b0ff-0f9b5a30f544>2011-06-01 12:01:44 +0000
committercash <cash@36083f99-b078-4883-b0ff-0f9b5a30f544>2011-06-01 12:01:44 +0000
commita5b06dfbcb6cdecf3b4e1f9d168711fc7faa2aad (patch)
tree964d73a57d443bf93dfa2645418506be2f897457
parent9a68be3c337ed98475535ab6b0483f53073678e1 (diff)
downloadelgg-a5b06dfbcb6cdecf3b4e1f9d168711fc7faa2aad.tar.gz
elgg-a5b06dfbcb6cdecf3b4e1f9d168711fc7faa2aad.tar.bz2
Fixes #3455 added documentation back to deprecated functions
git-svn-id: http://code.elgg.org/elgg/trunk@9125 36083f99-b078-4883-b0ff-0f9b5a30f544
-rw-r--r--engine/lib/deprecated-1.8.php366
1 files changed, 281 insertions, 85 deletions
diff --git a/engine/lib/deprecated-1.8.php b/engine/lib/deprecated-1.8.php
index 44cbb1aaa..12398c8d5 100644
--- a/engine/lib/deprecated-1.8.php
+++ b/engine/lib/deprecated-1.8.php
@@ -1,7 +1,83 @@
<?php
/**
- * @return str
+ * ***************************************************************************
+ * NOTE: If this is ever removed from Elgg, sites lose the ability to upgrade
+ * from 1.7.x and earlier to the latest version of Elgg without upgrading to
+ * 1.8 first.
+ * ***************************************************************************
+ *
+ * Upgrade the database schema in an ordered sequence.
+ *
+ * Executes all upgrade files in elgg/engine/schema/upgrades/ in sequential order.
+ * Upgrade files must be in the standard Elgg release format of YYYYMMDDII.sql
+ * where II is an incrementor starting from 01.
+ *
+ * Files that are < $version will be ignored.
+ *
+ * @warning Plugin authors should not call this function directly.
+ *
+ * @param int $version The version you are upgrading from in the format YYYYMMDDII.
+ * @param string $fromdir Optional directory to load upgrades from. default: engine/schema/upgrades/
+ * @param bool $quiet If true, suppress all error messages. Only use for the upgrade from <=1.6.
+ *
+ * @return bool
+ * @see upgrade.php
+ * @see version.php
+ * @deprecated 1.8 Use PHP upgrades for sql changes.
+ */
+function db_upgrade($version, $fromdir = "", $quiet = FALSE) {
+ global $CONFIG;
+
+ elgg_deprecated_notice('db_upgrade() is deprecated by using PHP upgrades.', 1.8);
+
+ $version = (int) $version;
+
+ if (!$fromdir) {
+ $fromdir = $CONFIG->path . 'engine/schema/upgrades/';
+ }
+
+ if ($handle = opendir($fromdir)) {
+ $sqlupgrades = array();
+
+ while ($sqlfile = readdir($handle)) {
+ if (!is_dir($fromdir . $sqlfile)) {
+ if (preg_match('/^([0-9]{10})\.(sql)$/', $sqlfile, $matches)) {
+ $sql_version = (int) $matches[1];
+ if ($sql_version > $version) {
+ $sqlupgrades[] = $sqlfile;
+ }
+ }
+ }
+ }
+
+ asort($sqlupgrades);
+
+ if (sizeof($sqlupgrades) > 0) {
+ foreach ($sqlupgrades as $sqlfile) {
+
+ // hide all errors.
+ if ($quiet) {
+ try {
+ run_sql_script($fromdir . $sqlfile);
+ } catch (DatabaseException $e) {
+ error_log($e->getmessage());
+ }
+ } else {
+ run_sql_script($fromdir . $sqlfile);
+ }
+ }
+ }
+ }
+
+ return TRUE;
+}
+
+/**
+ * Lists entities from an access collection
+ *
* @deprecated 1.8 Use elgg_list_entities_from_access_id()
+ *
+ * @return str
*/
function list_entities_from_access_id($access_id, $entity_type = "", $entity_subtype = "", $owner_guid = 0, $limit = 10, $fullview = true, $listtypetoggle = true, $pagination = true) {
@@ -14,7 +90,14 @@ function list_entities_from_access_id($access_id, $entity_type = "", $entity_sub
}
/**
+ * Registers a particular action in memory
+ *
* @deprecated 1.8 Use {@link elgg_register_action()} instead
+ *
+ * @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.
*/
function register_action($action, $public = false, $filename = "", $admin_only = false) {
elgg_deprecated_notice("register_action() was deprecated by elgg_register_action()", 1.8);
@@ -35,6 +118,8 @@ function register_action($action, $public = false, $filename = "", $admin_only =
* This function extends the view "admin/main" with the provided view.
* This view should provide a description and either a control or a link to.
*
+ * @deprecated 1.8 Extend admin views manually
+ *
* Usage:
* - To add a control to the main admin panel then extend admin/main
* - To add a control to a new page create a page which renders a view admin/subpage
@@ -48,8 +133,6 @@ function register_action($action, $public = false, $filename = "", $admin_only =
* @param string $view The view to extend, by default this is 'admin/main'.
* @param int $priority Optional priority to govern the appearance in the list.
*
- * @deprecated 1.8 Extend admin views manually
- *
* @return void
*/
function extend_elgg_admin_page($new_admin_view, $view = 'admin/main', $priority = 500) {
@@ -249,6 +332,8 @@ function list_entities_from_annotation_count($entity_type = "", $entity_subtype
/**
* Adds an entry in $CONFIG[$register_name][$subregister_name].
*
+ * @deprecated 1.8 Use the new menu system.
+ *
* This is only used for the site-wide menu. See {@link add_menu()}.
*
* @param string $register_name The name of the top-level register
@@ -257,7 +342,6 @@ function list_entities_from_annotation_count($entity_type = "", $entity_subtype
* @param array $children_array Optionally, an array of children
*
* @return true|false Depending on success
- * @deprecated 1.8
*/
function add_to_register($register_name, $subregister_name, $subregister_value, $children_array = array()) {
elgg_deprecated_notice("add_to_register() has been deprecated", 1.8);
@@ -290,6 +374,8 @@ function add_to_register($register_name, $subregister_name, $subregister_value,
/**
* Removes a register entry from $CONFIG[register_name][subregister_name]
*
+ * @deprecated 1.8 Use the new menu system.
+ *
* 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
@@ -297,7 +383,6 @@ function add_to_register($register_name, $subregister_name, $subregister_value,
*
* @return true|false Depending on success
* @since 1.7.0
- * @deprecated 1.8
*/
function remove_from_register($register_name, $subregister_name) {
elgg_deprecated_notice("remove_from_register() has been deprecated", 1.8);
@@ -326,10 +411,11 @@ function remove_from_register($register_name, $subregister_name) {
/**
* If it exists, returns a particular register as an array
*
+ * @deprecated 1.8 Use the new menu system
+ *
* @param string $register_name The name of the register
*
* @return array|false Depending on success
- * @deprecated 1.8
*/
function get_register($register_name) {
elgg_deprecated_notice("get_register() has been deprecated", 1.8);
@@ -363,6 +449,8 @@ function get_register($register_name) {
* Deprecated events core function. Code divided between elgg_register_event_handler()
* and trigger_elgg_event().
*
+ * @deprecated 1.8 Use explicit register/trigger event functions
+ *
* @param string $event The type of event (eg 'init', 'update', 'delete')
* @param string $object_type The type of object (eg 'system', 'blog', 'user')
* @param string $function The name of the function that will handle the event
@@ -371,7 +459,6 @@ function get_register($register_name) {
* @param mixed $object Optionally, the object the event is being performed on (eg a user)
*
* @return true|false Depending on success
- * @deprecated 1.8 Use explicit register/trigger event functions
*/
function events($event = "", $object_type = "", $function = "", $priority = 500, $call = false, $object = null) {
@@ -386,7 +473,14 @@ function events($event = "", $object_type = "", $function = "", $priority = 500,
}
/**
+ * Alias function for events, that registers a function to a particular kind of event
+ *
* @deprecated 1.8 Use elgg_register_event_handler() instead
+ *
+ * @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
*/
function register_elgg_event_handler($event, $object_type, $callback, $priority = 500) {
elgg_deprecated_notice("register_elgg_event_handler() was deprecated by elgg_register_event_handler()", 1.8);
@@ -394,7 +488,14 @@ function register_elgg_event_handler($event, $object_type, $callback, $priority
}
/**
+ * Unregisters a function to a particular kind of event
+ *
* @deprecated 1.8 Use elgg_unregister_event_handler instead
+ *
+ * @param string $event The event type
+ * @param string $object_type The object type
+ * @param string $function The function name
+ * @since 1.7.0
*/
function unregister_elgg_event_handler($event, $object_type, $callback) {
elgg_deprecated_notice('unregister_elgg_event_handler => elgg_unregister_event_handler', 1.8);
@@ -402,7 +503,14 @@ function unregister_elgg_event_handler($event, $object_type, $callback) {
}
/**
+ * Alias function for events, that triggers a particular kind of event
+ *
* @deprecated 1.8 Use elgg_trigger_event() instead
+ *
+ * @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
*/
function trigger_elgg_event($event, $object_type, $object = null) {
elgg_deprecated_notice('trigger_elgg_event() was deprecated by elgg_trigger_event()', 1.8);
@@ -410,7 +518,29 @@ function trigger_elgg_event($event, $object_type, $object = null) {
}
/**
+ * Register a function to a plugin hook for a particular entity type, with a given priority.
+ *
* @deprecated 1.8 Use elgg_register_plugin_hook_handler() instead
+ *
+ * eg if you want the function "export_user" to be called when the hook "export" for "user" entities
+ * is run, use:
+ *
+ * register_plugin_hook("export", "user", "export_user");
+ *
+ * "all" is a valid value for both $hook and $entity_type. "none" is a valid value for $entity_type.
+ *
+ * The export_user function would then be defined as:
+ *
+ * function export_user($hook, $entity_type, $returnvalue, $params);
+ *
+ * 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).
+ *
+ * @param string $hook The name of the hook
+ * @param string $entity_type The name of the type of entity (eg "user", "object" etc)
+ * @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
*/
function register_plugin_hook($hook, $type, $callback, $priority = 500) {
elgg_deprecated_notice("register_plugin_hook() was deprecated by elgg_register_plugin_hook_handler()", 1.8);
@@ -418,7 +548,14 @@ function register_plugin_hook($hook, $type, $callback, $priority = 500) {
}
/**
+ * Unregister a function to a plugin hook for a particular entity type
+ *
* @deprecated 1.8 Use elgg_unregister_plugin_hook_handler() instead
+ *
+ * @param string $hook The name of the hook
+ * @param string $entity_type The name of the type of entity (eg "user", "object" etc)
+ * @param string $function The name of a valid function to be run
+ * @since 1.7.0
*/
function unregister_plugin_hook($hook, $entity_type, $callback) {
elgg_deprecated_notice("unregister_plugin_hook() was deprecated by elgg_unregister_plugin_hook_handler()", 1.8);
@@ -426,7 +563,20 @@ function unregister_plugin_hook($hook, $entity_type, $callback) {
}
/**
+ * Triggers a plugin hook, with various parameters as an array. For example, to provide
+ * a 'foo' hook that concerns an entity of type 'bar', with a parameter called 'param1'
+ * with value 'value1', that by default returns true, you'd call:
+ *
* @deprecated 1.8 Use elgg_trigger_plugin_hook() instead
+ *
+ * trigger_plugin_hook('foo', 'bar', array('param1' => 'value1'), true);
+ *
+ * @see register_plugin_hook
+ * @param string $hook The name of the hook to trigger
+ * @param string $entity_type The name of the entity type to trigger it for (or "all", or "none")
+ * @param array $params Any parameters. It's good practice to name the keys, i.e. by using array('name' => 'value', 'name2' => 'value2')
+ * @param mixed $returnvalue An initial return value
+ * @return mixed|null The cumulative return value for the plugin hook functions
*/
function trigger_plugin_hook($hook, $type, $params = null, $returnvalue = null) {
elgg_deprecated_notice("trigger_plugin_hook() was deprecated by elgg_trigger_plugin_hook()", 1.8);
@@ -2844,6 +2994,13 @@ $priority = 500) {
}
/**
+ * Returns a representation of a full 'page' (which might be an HTML page,
+ * RSS file, etc, depending on the current viewtype)
+ *
+ * @param string $title
+ * @param string $body
+ * @return string
+ *
* @deprecated 1.8 Use elgg_view_page()
*/
function page_draw($title, $body, $sidebar = "") {
@@ -3510,8 +3667,12 @@ $asc = false, $fullview = true, $listtypetoggle = false, $pagination = true, $or
}
/**
- * @deprecated 1.8
- * @see elgg_set_view_location()
+ * Set an alternative base location for a view (as opposed to the default of $CONFIG->viewpath)
+ *
+ * @param string $view The name of the view
+ * @param string $location The base location path
+ *
+ * @deprecated 1.8 Use elgg_set_view_location()
*/
function set_view_location($view, $location, $viewtype = '') {
elgg_deprecated_notice("set_view_location() was deprecated by elgg_set_view_location()", 1.8);
@@ -3519,8 +3680,14 @@ function set_view_location($view, $location, $viewtype = '') {
}
/**
- * @deprecated 1.8
- * @see elgg_register_entity_url_handler()
+ * Sets the URL handler for a particular entity type and subtype
+ *
+ * @param string $function_name The function to register
+ * @param string $entity_type The entity type
+ * @param string $entity_subtype The entity subtype
+ * @return true|false Depending on success
+ *
+ * @deprecated 1.8 Use elgg_register_entity_url_handler()
*/
function register_entity_url_handler($function_name, $entity_type = "all", $entity_subtype = "all") {
elgg_deprecated_notice("register_entity_url_handler() was deprecated by elgg_register_entity_url_handler()", 1.8);
@@ -3807,6 +3974,27 @@ function clear_annotations_by_owner($owner_guid) {
}
/**
+ * Registers a page handler for a particular identifier
+ *
+ * For example, you can register a function called 'blog_page_handler' for handler type 'blog'
+ * Now for all URLs of type http://yoururl/pg/blog/*, the blog_page_handler() function will be called.
+ * The part of the URL marked with * above will be exploded on '/' characters and passed as an
+ * array to that function.
+ * For example, the URL http://yoururl/blog/username/friends/ would result in the call:
+ * blog_page_handler(array('username','friends'), blog);
+ *
+ * Page handler functions should return true or the default page handler will be called.
+ *
+ * A request to register a page handler with the same identifier as previously registered
+ * handler will replace the previous one.
+ *
+ * The context is set to the page handler identifier before the registered
+ * page handler function is called. For the above example, the context is set to 'blog'.
+ *
+ * @param string $handler The page type to handle
+ * @param string $function Your function name
+ * @return true|false Depending on success
+ *
* @deprecated 1.8 Use {@link elgg_register_page_handler()}
*/
function register_page_handler($handler, $function){
@@ -3815,6 +4003,13 @@ function register_page_handler($handler, $function){
}
/**
+ * Unregister a page handler for an identifier
+ *
+ * Note: to replace a page handler, call register_page_handler()
+ *
+ * @param string $handler The page type identifier
+ * @since 1.7.2
+ *
* @deprecated 1.8 Use {@link elgg_unregister_page_handler()}
*/
function unregister_page_handler($handler) {
@@ -3823,6 +4018,11 @@ function unregister_page_handler($handler) {
}
/**
+ * Register an annotation url handler.
+ *
+ * @param string $function_name The function.
+ * @param string $extender_name The name, default 'all'.
+ *
* @deprecated 1.8 Use {@link elgg_register_annotation_url_handler()}
*/
function register_annotation_url_handler($function, $extender_name) {
@@ -3831,6 +4031,15 @@ function register_annotation_url_handler($function, $extender_name) {
}
/**
+ * Sets the URL handler for a particular extender type and name.
+ * It is recommended that you do not call this directly, instead use one of the wrapper functions in the
+ * subtype files.
+ *
+ * @param string $function_name The function to register
+ * @param string $extender_type Extender type
+ * @param string $extender_name The name of the extender
+ * @return true|false Depending on success
+ *
* @deprecated 1.8 Use {@link elgg_register_extender_url_handler()}
*/
function register_extender_url_handler($function, $type = "all", $name = "all") {
@@ -3839,6 +4048,14 @@ function register_extender_url_handler($function, $type = "all", $name = "all")
}
/**
+ * Registers and entity type and subtype to return in search and other places.
+ * A description in the elgg_echo languages file of the form item:type:subtype
+ * is also expected.
+ *
+ * @param string $type The type of entity (object, site, user, group)
+ * @param string $subtype The subtype to register (may be blank)
+ * @return true|false Depending on success
+ *
* @deprecated 1.8 Use {@link elgg_register_entity_type()}
*/
function register_entity_type($type, $subtype = null) {
@@ -3847,6 +4064,11 @@ function register_entity_type($type, $subtype = null) {
}
/**
+ * Register a metadata url handler.
+ *
+ * @param string $function_name The function.
+ * @param string $extender_name The name, default 'all'.
+ *
* @deprecated 1.8 Use {@link elgg_register_metadata_url_handler()}
*/
function register_metadata_url_handler($function, $extender_name = "all") {
@@ -3854,7 +4076,12 @@ function register_metadata_url_handler($function, $extender_name = "all") {
}
/**
+ * Sets the URL handler for a particular relationship type
*
+ * @param string $function_name The function to register
+ * @param string $relationship_type The relationship type.
+ * @return true|false Depending on success
+ *
* @deprecated 1.8 Use {@link elgg_register_relationship_url_handler()}
*/
function register_relationship_url_handler($function_name, $relationship_type = "all") {
@@ -3863,6 +4090,15 @@ function register_relationship_url_handler($function_name, $relationship_type =
}
/**
+ * Registers a view to be simply cached
+ *
+ * Views cached in this manner must take no parameters and be login agnostic -
+ * that is to say, they look the same no matter who is logged in (or logged out).
+ *
+ * CSS and the basic jS views are automatically cached like this.
+ *
+ * @param string $viewname View name
+ *
* @deprecated 1.8 Use {@link elgg_register_simplecache_view()}
*/
function elgg_view_register_simplecache($viewname) {
@@ -3871,6 +4107,11 @@ function elgg_view_register_simplecache($viewname) {
}
/**
+ * Regenerates the simple cache.
+ *
+ * @param string $viewtype Optional viewtype to regenerate
+ * @see elgg_view_register_simplecache()
+ *
* @deprecated 1.8 Use {@link elgg_regenerate_simplecache()}
*/
function elgg_view_regenerate_simplecache($viewtype = NULL) {
@@ -3879,6 +4120,10 @@ function elgg_view_regenerate_simplecache($viewtype = NULL) {
}
/**
+ * Enables the simple cache.
+ *
+ * @see elgg_view_register_simplecache()
+ *
* @deprecated 1.8 Use {@link elgg_enable_simplecache()}
*/
function elgg_view_enable_simplecache() {
@@ -3887,6 +4132,10 @@ function elgg_view_enable_simplecache() {
}
/**
+ * Disables the simple cache.
+ *
+ * @see elgg_view_register_simplecache()
+ *
* @deprecated 1.8 Use {@link elgg_disable_simplecache()}
*/
function elgg_view_disable_simplecache() {
@@ -3912,6 +4161,22 @@ function is_installed() {
}
/**
+ * Attempt to authenticate.
+ * This function will process all registered PAM handlers or stop when the first
+ * handler fails. A handler fails by either returning false or throwing an
+ * exception. The advantage of throwing an exception is that it returns a message
+ * through the global $_PAM_HANDLERS_MSG which can be used in communication with
+ * a user. The order that handlers are processed is determined by the order that
+ * they were registered.
+ *
+ * If $credentials are provided the PAM handler should authenticate using the
+ * provided credentials, if not then credentials should be prompted for or
+ * otherwise retrieved (eg from the HTTP header or $_SESSION).
+ *
+ * @param mixed $credentials Mixed PAM handler specific credentials (e.g. username, password)
+ * @param string $policy - the policy type, default is "user"
+ * @return bool true if authenticated, false if not.
+ *
* @deprecated 1.8 See {@link ElggPAM}
*/
function pam_authenticate($credentials = NULL, $policy = "user") {
@@ -4375,6 +4640,11 @@ function using_widgets() {
}
/**
+ * Displays a particular widget
+ *
+ * @param ElggObject $widget The widget to display
+ * @return string The HTML for the widget, including JavaScript wrapper
+ *
* @deprecated 1.8
*/
function display_widget(ElggObject $widget) {
@@ -4382,80 +4652,6 @@ function display_widget(ElggObject $widget) {
return elgg_view_entity($widget);
}
-
-/**
- * ***************************************************************************
- * NOTE: If this is ever removed from Elgg, sites lose the ability to upgrade
- * from 1.7.x and earlier to the latest version of Elgg without upgrading to
- * 1.8 first.
- * ***************************************************************************
- *
- * Upgrade the database schema in an ordered sequence.
- *
- * Executes all upgrade files in elgg/engine/schema/upgrades/ in sequential order.
- * Upgrade files must be in the standard Elgg release format of YYYYMMDDII.sql
- * where II is an incrementor starting from 01.
- *
- * Files that are < $version will be ignored.
- *
- * @warning Plugin authors should not call this function directly.
- *
- * @param int $version The version you are upgrading from in the format YYYYMMDDII.
- * @param string $fromdir Optional directory to load upgrades from. default: engine/schema/upgrades/
- * @param bool $quiet If true, suppress all error messages. Only use for the upgrade from <=1.6.
- *
- * @return bool
- * @see upgrade.php
- * @see version.php
- * @deprecated 1.8 Use PHP upgrades for sql changes.
- */
-function db_upgrade($version, $fromdir = "", $quiet = FALSE) {
- global $CONFIG;
-
- elgg_deprecated_notice('db_upgrade() is deprecated by using PHP upgrades.', 1.8);
-
- $version = (int) $version;
-
- if (!$fromdir) {
- $fromdir = $CONFIG->path . 'engine/schema/upgrades/';
- }
-
- if ($handle = opendir($fromdir)) {
- $sqlupgrades = array();
-
- while ($sqlfile = readdir($handle)) {
- if (!is_dir($fromdir . $sqlfile)) {
- if (preg_match('/^([0-9]{10})\.(sql)$/', $sqlfile, $matches)) {
- $sql_version = (int) $matches[1];
- if ($sql_version > $version) {
- $sqlupgrades[] = $sqlfile;
- }
- }
- }
- }
-
- asort($sqlupgrades);
-
- if (sizeof($sqlupgrades) > 0) {
- foreach ($sqlupgrades as $sqlfile) {
-
- // hide all errors.
- if ($quiet) {
- try {
- run_sql_script($fromdir . $sqlfile);
- } catch (DatabaseException $e) {
- error_log($e->getmessage());
- }
- } else {
- run_sql_script($fromdir . $sqlfile);
- }
- }
- }
- }
-
- return TRUE;
-}
-
/**
* Count the number of comments attached to an entity
*