Elgg  Version 1.9
Namespaces | Functions | Variables
elgglib.php File Reference

Go to the source code of this file.

Namespaces

 Elgg\Core
 Activate a plugin or plugins.
 

Functions

 elgg_register_library ($name, $location)
 Register a php library. More...
 
 elgg_load_library ($name)
 Load a php library. More...
 
 forward ($location="", $reason= 'system')
 Forward to $location. More...
 
 elgg_register_js ($name, $url, $location= 'head', $priority=null)
 Register a JavaScript file for inclusion. More...
 
 elgg_define_js ($name, $config)
 Defines a JS lib as an AMD module. More...
 
 elgg_unregister_js ($name)
 Unregister a JavaScript file. More...
 
 elgg_load_js ($name)
 Load a JavaScript resource on this page. More...
 
 elgg_require_js ($name)
 Request that Elgg load an AMD module onto the page. More...
 
 elgg_get_loaded_js ($location= 'head')
 Get the JavaScript URLs that are loaded. More...
 
 elgg_register_css ($name, $url, $priority=null)
 Register a CSS file for inclusion in the HTML head. More...
 
 elgg_unregister_css ($name)
 Unregister a CSS file. More...
 
 elgg_load_css ($name)
 Load a CSS file for this page. More...
 
 elgg_get_loaded_css ()
 Get the loaded CSS URLs. More...
 
 elgg_register_external_file ($type, $name, $url, $location, $priority=500)
 Core registration function for external files. More...
 
 elgg_unregister_external_file ($type, $name)
 Unregister an external file. More...
 
 elgg_load_external_file ($type, $name)
 Load an external resource for use on this page. More...
 
 elgg_get_loaded_external_files ($type, $location)
 Get external resource descriptors. More...
 
 _elgg_bootstrap_externals_data_structure ($type)
 Bootstraps the externals data structure in $CONFIG. More...
 
 elgg_get_file_list ($directory, $exceptions=array(), $list=array(), $extensions=null)
 Returns a list of files in $directory. More...
 
 sanitise_filepath ($path, $append_slash=true)
 Sanitise file paths ensuring that they begin and end with slashes etc. More...
 
 system_messages ($message=null, $register="success", $count=false)
 Queues a message to be displayed. More...
 
 count_messages ($register="")
 Counts the number of messages, either globally or in a particular register. More...
 
 system_message ($message)
 Display a system message on next page load. More...
 
 register_error ($error)
 Display an error on next page load. More...
 
 elgg_register_event_handler ($event, $object_type, $callback, $priority=500)
 Register a callback as an Elgg event handler. More...
 
 elgg_unregister_event_handler ($event, $object_type, $callback)
 Unregisters a callback for an event. More...
 
 elgg_trigger_event ($event, $object_type, $object=null)
 Trigger an Elgg Event and attempt to run all handler callbacks registered to that event, type. More...
 
 elgg_trigger_before_event ($event, $object_type, $object=null)
 Trigger a "Before event" indicating a process is about to begin. More...
 
 elgg_trigger_after_event ($event, $object_type, $object=null)
 Trigger an "After event" indicating a process has finished. More...
 
 elgg_trigger_deprecated_event ($event, $object_type, $object=null, $message, $version)
 Trigger an event normally, but send a notice about deprecated use if any handlers are registered. More...
 
 elgg_register_plugin_hook_handler ($hook, $type, $callback, $priority=500)
 Register a callback as a plugin hook handler. More...
 
 elgg_unregister_plugin_hook_handler ($hook, $entity_type, $callback)
 Unregister a callback as a plugin hook. More...
 
 elgg_trigger_plugin_hook ($hook, $type, $params=null, $returnvalue=null)
 Trigger a Plugin Hook and run all handler callbacks registered to that hook:type. More...
 
 _elgg_php_exception_handler ($exception)
 Intercepts, logs, and displays uncaught exceptions. More...
 
 _elgg_php_error_handler ($errno, $errmsg, $filename, $linenum, $vars)
 Intercepts catchable PHP errors. More...
 
 elgg_log ($message, $level= 'NOTICE')
 Display or log a message. More...
 
 elgg_dump ($value, $to_screen=true)
 Logs or displays $value. More...
 
 elgg_get_version ($human_readable=false)
 Get the current Elgg version information. More...
 
 elgg_deprecated_notice ($msg, $dep_version, $backtrace_level=1)
 Sends a notice about deprecated use of a function, view, etc. More...
 
 elgg_http_build_url (array $parts, $html_encode=true)
 Builds a URL from the a parts array like one returned by parse_url(). More...
 
 elgg_add_action_tokens_to_url ($url, $html_encode=false)
 Adds action tokens to URL. More...
 
 elgg_http_remove_url_query_element ($url, $element)
 Removes an element from a URL's query string. More...
 
 elgg_http_add_url_query_elements ($url, array $elements)
 Sets elements in a URL's query string. More...
 
 elgg_http_url_is_identical ($url1, $url2, $ignore_params=array('offset', 'limit'))
 Test if two URLs are functionally identical. More...
 
 elgg_extract ($key, array $array, $default=null, $strict=true)
 Checks for $array[$key] and returns its value if it exists, else returns $default. More...
 
 elgg_sort_3d_array_by_value (&$array, $element, $sort_order=SORT_ASC, $sort_type=SORT_LOCALE_STRING)
 Sorts a 3d array by specific element. More...
 
 ini_get_bool ($ini_get_arg)
 Return the state of a php.ini setting as a bool. More...
 
 elgg_get_ini_setting_in_bytes ($setting)
 Returns a PHP INI setting in bytes. More...
 
 is_not_null ($string)
 Returns true is string is not empty, false, or null. More...
 
 _elgg_normalize_plural_options_array ($options, $singulars)
 Normalise the singular keys in an options array to plural keys. More...
 
 _elgg_shutdown_hook ()
 Emits a shutdown:system event upon PHP shutdown, but before database connections are dropped. More...
 
 _elgg_js_page_handler ($page)
 Serve javascript pages. More...
 
 _elgg_ajax_page_handler ($page)
 Serve individual views for Ajax. More...
 
 _elgg_css_page_handler ($page)
 Serve CSS. More...
 
 _elgg_cacheable_view_page_handler ($page, $type)
 Serves a JS or CSS view with headers for caching. More...
 
 _elgg_sql_reverse_order_by_clause ($order_by)
 Reverses the ordering in an ORDER BY clause. More...
 
 elgg_batch_enable_callback ($object)
 Enable objects with an enable() method. More...
 
 elgg_batch_disable_callback ($object)
 Disable objects with a disable() method. More...
 
 elgg_batch_delete_callback ($object)
 Delete objects with a delete() method. More...
 
 _elgg_is_valid_options_for_batch_operation ($options, $type)
 Checks if there are some constraints on the options array for potentially dangerous operations. More...
 
 _elgg_walled_garden_index ()
 Intercepts the index page when Walled Garden mode is enabled. More...
 
 _elgg_walled_garden_ajax_handler ($page)
 Serve walled garden sections. More...
 
 _elgg_walled_garden_init ()
 Checks the status of the Walled Garden and forwards to a login page if required. More...
 
 _elgg_walled_garden_remove_public_access ($hook, $type, $accesses)
 Remove public access for walled gardens. More...
 
 _elgg_engine_boot ()
 Boots the engine. More...
 
 _elgg_init ()
 Elgg's main init. More...
 
 _elgg_api_test ($hook, $type, $value, $params)
 Adds unit tests for the general API. More...
 

Variables

const ACCESS_DEFAULT -1
 
const ACCESS_PRIVATE 0
 
const ACCESS_LOGGED_IN 1
 
const ACCESS_PUBLIC 2
 
const ACCESS_FRIENDS -2
 
const ELGG_ENTITIES_ANY_VALUE null
 
const ELGG_ENTITIES_NO_VALUE 0
 
const REFERRER -1
 
const REFERER -1
 

Function Documentation

_elgg_ajax_page_handler (   $page)

Serve individual views for Ajax.

/ajax/view/<name of="" view>="">?<key/value params>

Parameters
array$pageArray of URL segements
Returns
bool
See also
elgg_register_ajax_view() ajax private

Definition at line 1681 of file elgglib.php.

_elgg_api_test (   $hook,
  $type,
  $value,
  $params 
)

Adds unit tests for the general API.

Parameters
string$hookunit_test
string$typesystem
array$valuearray of test files
array$paramsempty

unit_tests system

Returns
array private

Definition at line 2103 of file elgglib.php.

_elgg_bootstrap_externals_data_structure (   $type)

Bootstraps the externals data structure in $CONFIG.

Parameters
string$typeThe type of external, js or css. private

Definition at line 420 of file elgglib.php.

_elgg_cacheable_view_page_handler (   $page,
  $type 
)

Serves a JS or CSS view with headers for caching.

/<css||js>/name/of/view.<last_cache>.<css||js>

Parameters
array$pageThe page array
string$typeThe type: js or css
Returns
bool private

Definition at line 1750 of file elgglib.php.

_elgg_css_page_handler (   $page)

Serve CSS.

Serves CSS from the css views directory with headers for caching control

Parameters
array$pageThe page array
Returns
bool css private

Definition at line 1730 of file elgglib.php.

_elgg_engine_boot ( )

Boots the engine.

  1. sets error handlers
  2. connects to database
  3. verifies the installation succeeded
  4. loads application configuration
  5. loads i18n data
  6. loads cached autoloader state
  7. loads site configuration

private

Definition at line 2023 of file elgglib.php.

_elgg_init ( )

Elgg's main init.

Handles core actions for comments, the JS pagehandler, and the shutdown function.

init system

Returns
void private

Definition at line 2054 of file elgglib.php.

_elgg_is_valid_options_for_batch_operation (   $options,
  $type 
)

Checks if there are some constraints on the options array for potentially dangerous operations.

Parameters
array$optionsOptions array
string$typeOptions type: metadata or annotation
Returns
bool private

Definition at line 1877 of file elgglib.php.

_elgg_js_page_handler (   $page)

Serve javascript pages.

Searches for views under js/ and outputs them with special headers for caching control.

Parameters
array$pageThe page array
Returns
bool js private

Definition at line 1665 of file elgglib.php.

_elgg_normalize_plural_options_array (   $options,
  $singulars 
)

Normalise the singular keys in an options array to plural keys.

Used in elgg_get_entities*() functions to support shortcutting plural names by singular names.

Parameters
array$optionsThe options array. $options['keys'] = 'values';
array$singularsA list of singular words to pluralize by adding 's'.
Returns
array
Since
1.7.0 private

Definition at line 1594 of file elgglib.php.

_elgg_php_error_handler (   $errno,
  $errmsg,
  $filename,
  $linenum,
  $vars 
)

Intercepts catchable PHP errors.

Warning
This function should never be called directly.

Definition at line 1033 of file elgglib.php.

_elgg_php_exception_handler (   $exception)

Intercepts, logs, and displays uncaught exceptions.

To use a viewtype other than failsafe, create the views: <viewtype>/messages/exceptions/admin_exception <viewtype>/messages/exceptions/exception See the json viewtype for an example.

Warning
This function should never be called directly.
See also
http://www.php.net/set-exception-handler
Parameters
Exception$exceptionThe exception being handled
Returns
void private

Definition at line 946 of file elgglib.php.

_elgg_shutdown_hook ( )

Emits a shutdown:system event upon PHP shutdown, but before database connections are dropped.

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 also
http://www.php.net/register-shutdown-function
Returns
void
See also
register_shutdown_hook() private

Definition at line 1632 of file elgglib.php.

_elgg_sql_reverse_order_by_clause (   $order_by)

Reverses the ordering in an ORDER BY clause.

This is achived by replacing asc with desc, or appending desc to the end of the clause.

This is used mostly for elgg_get_entities() and other similar functions.

Parameters
string$order_byAn order by clause private
Returns
string private

Definition at line 1809 of file elgglib.php.

_elgg_walled_garden_ajax_handler (   $page)

Serve walled garden sections.

Parameters
array$pageArray of URL segments
Returns
string private

Definition at line 1956 of file elgglib.php.

_elgg_walled_garden_index ( )

Intercepts the index page when Walled Garden mode is enabled.

Returns
bool private

Definition at line 1930 of file elgglib.php.

_elgg_walled_garden_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 { public_pages walled_garden} will redirect to a login page.

Since
1.8.0 init system
Returns
void private

Definition at line 1980 of file elgglib.php.

_elgg_walled_garden_remove_public_access (   $hook,
  $type,
  $accesses 
)

Remove public access for walled gardens.

Parameters
string$hook
string$type
array$accesses
Returns
array private

Definition at line 2003 of file elgglib.php.

count_messages (   $register = "")

Counts the number of messages, either globally or in a particular register.

Parameters
string$registerOptionally, the register
Returns
integer The number of messages
Examples:
/root/Elgg/engine/lib/views.php.

Definition at line 579 of file elgglib.php.

elgg_add_action_tokens_to_url (   $url,
  $html_encode = false 
)

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 { input/form} you don't need to add tokens to the action. The form view automatically handles tokens.
Parameters
string$urlFull action URL
bool$html_encodeHTML encode the url? (default: false)
Returns
string URL with action tokens
Since
1.7.0

Definition at line 1277 of file elgglib.php.

elgg_batch_delete_callback (   $object)

Delete objects with a delete() method.

Used as a callback for ElggBatch.

Parameters
object$objectThe object to disable
Returns
bool private

Definition at line 1863 of file elgglib.php.

elgg_batch_disable_callback (   $object)

Disable objects with a disable() method.

Used as a callback for ElggBatch.

Parameters
object$objectThe object to disable
Returns
bool private

Definition at line 1849 of file elgglib.php.

elgg_batch_enable_callback (   $object)

Enable objects with an enable() method.

Used as a callback for ElggBatch.

Parameters
object$objectThe object to enable
Returns
bool private

Definition at line 1835 of file elgglib.php.

elgg_define_js (   $name,
  $config 
)

Defines a JS lib as an AMD module.

This is useful for shimming traditional JS or for setting the paths of AMD modules.

Calling multiple times for the same name will:

  • set the preferred path to the last call setting a path
  • overwrite the shimmed AMD modules with the last call setting a shimmed module

Use elgg_require_js($name) to load on the current page.

Calling this function is not needed if your JS are in views named like js/module/name.js Instead, simply call elgg_require_js("module/name").

Parameters
string$nameThe module name
array$configAn array like the following: array 'deps' An array of AMD module dependencies string 'exports' The name of the exported module string 'src' The URL to the JS. Can be relative.
Returns
void
Examples:
/root/Elgg/engine/lib/views.php.

Definition at line 153 of file elgglib.php.

elgg_deprecated_notice (   $msg,
  $dep_version,
  $backtrace_level = 1 
)

Sends a notice about deprecated use of a function, view, etc.

This function either displays or logs the deprecation message, depending upon the deprecation policies in CODING.txt. Logged messages are sent with the level of 'WARNING'. Only admins get visual deprecation notices. When non-admins are logged in, the notices are sent to PHP's log through elgg_dump().

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 also
CODING.txt
Parameters
string$msgMessage to log / display.
string$dep_versionHuman-readable release version: 1.7, 1.8, ...
int$backtrace_levelHow many levels back to display the backtrace. Useful if calling from functions that are called from other places (like elgg_view()). Set to -1 for a full backtrace.
Returns
bool
Since
1.7.0
Examples:
/root/Elgg/engine/lib/output.php, and /root/Elgg/engine/lib/views.php.

Definition at line 1171 of file elgglib.php.

elgg_dump (   $value,
  $to_screen = true 
)

Logs or displays $value.

If $to_screen is true, $value is displayed to screen. Else, it is handled by PHP's error_log() function.

A { debug log} is called. If a handler returns false, it will stop the default logging method.

Parameters
mixed$valueThe value
bool$to_screenDisplay to screen?
Returns
void
Since
1.7.0

Definition at line 1114 of file elgglib.php.

elgg_extract (   $key,
array  $array,
  $default = null,
  $strict = true 
)

Checks for $array[$key] and returns its value if it exists, else returns $default.

Shorthand for $value = (isset($array['key'])) ? $array['key'] : 'default';

Parameters
string$keyThe key to check.
array$arrayThe array to check against.
mixed$defaultDefault value to return if nothing is found.
bool$strictReturn array key if it's set, even if empty. If false, return $default if the array key is unset or empty.
Returns
mixed
Since
1.8.0
Examples:
/root/Elgg/engine/classes/ElggBatch.php, and /root/Elgg/engine/lib/views.php.

Definition at line 1464 of file elgglib.php.

elgg_get_file_list (   $directory,
  $exceptions = array(),
  $list = array(),
  $extensions = null 
)

Returns a list of files in $directory.

Only returns files. Does not recurse into subdirs.

Parameters
string$directoryDirectory to look in
array$exceptionsArray of filenames to ignore
array$listArray of files to append to
mixed$extensionsArray of extensions to allow, null for all. Use a dot: array('.php').
Returns
array Filenames in $directory, in the form $directory/filename.

Definition at line 452 of file elgglib.php.

elgg_get_ini_setting_in_bytes (   $setting)

Returns a PHP INI setting in bytes.

Use this for arithmetic when determining if a file can be uploaded.

Parameters
string$settingThe php.ini setting
Returns
int
Since
1.7.0 http://www.php.net/manual/en/function.ini-get.php

Definition at line 1542 of file elgglib.php.

elgg_get_loaded_css ( )

Get the loaded CSS URLs.

Returns
array
Since
1.8.0

Definition at line 266 of file elgglib.php.

elgg_get_loaded_external_files (   $type,
  $location 
)

Get external resource descriptors.

Parameters
string$typeType of file: js or css
string$locationPage location
Returns
array
Since
1.8.0

Definition at line 398 of file elgglib.php.

elgg_get_loaded_js (   $location = 'head')

Get the JavaScript URLs that are loaded.

Parameters
string$location'head' or 'footer'
Returns
array
Since
1.8.0

Definition at line 215 of file elgglib.php.

elgg_get_version (   $human_readable = false)

Get the current Elgg version information.

Parameters
bool$human_readableWhether to return a human readable version (default: false)
Returns
string|false Depending on success
Since
1.9

Definition at line 1126 of file elgglib.php.

elgg_http_add_url_query_elements (   $url,
array  $elements 
)

Sets elements in a URL's query string.

Parameters
string$urlThe URL
array$elementsKey/value pairs to set in the URL. If the value is null, the element is removed from the URL.
Returns
string The new URL with the query strings added
Since
1.7.0

Definition at line 1325 of file elgglib.php.

elgg_http_build_url ( array  $parts,
  $html_encode = true 
)

Builds a URL from the a parts array like one returned by parse_url().

Note
If only partial information is passed, a partial URL will be returned.
Parameters
array$partsAssociative array of URL components like parse_url() returns
bool$html_encodeHTML Encode the url?
Returns
string Full URL
Since
1.7.0

Definition at line 1242 of file elgglib.php.

elgg_http_remove_url_query_element (   $url,
  $element 
)

Removes an element from a URL's query string.

Note
You can send a partial URL string.
Parameters
string$urlFull URL
string$elementThe element to remove
Returns
string The new URL with the query element removed.
Since
1.7.0

Definition at line 1311 of file elgglib.php.

elgg_http_url_is_identical (   $url1,
  $url2,
  $ignore_params = array('offset', 'limit') 
)

Test if two URLs are functionally identical.

If $ignore_params is used, neither the name nor its value will be considered when comparing.

The order of GET params doesn't matter.

Parameters
string$url1First URL
string$url2Second URL
array$ignore_paramsGET params to ignore in the comparison
Returns
bool
Since
1.8.0

Definition at line 1369 of file elgglib.php.

elgg_load_css (   $name)

Load a CSS file for this page.

This must be called before elgg_view_page(). It can be called before the CSS file is registered. If you do not want a CSS file loaded, unregister it.

Parameters
string$nameIdentifier of the CSS file
Returns
void
Since
1.8.0
Examples:
/root/Elgg/engine/lib/views.php.

Definition at line 256 of file elgglib.php.

elgg_load_external_file (   $type,
  $name 
)

Load an external resource for use on this page.

Parameters
string$typeType of file: js or css
string$nameThe identifier for the file
Returns
void
Since
1.8.0

Definition at line 366 of file elgglib.php.

elgg_load_js (   $name)

Load a JavaScript resource on this page.

This must be called before elgg_view_page(). It can be called before the script is registered. If you do not want a script loaded, unregister it.

Parameters
string$nameIdentifier of the JavaScript resource
Returns
void
Since
1.8.0
Examples:
/root/Elgg/engine/lib/views.php.

Definition at line 190 of file elgglib.php.

elgg_load_library (   $name)

Load a php library.

Parameters
string$nameThe name of the library
Returns
void
Exceptions
InvalidParameterException
Since
1.8.0

Definition at line 38 of file elgglib.php.

elgg_log (   $message,
  $level = 'NOTICE' 
)

Display or log a message.

If $level is >= to the debug setting in ->debug, the message will be sent to elgg_dump(). Messages with lower priority than ->debug are ignored.

Outputs all levels but NOTICE to screen by default.

Note
No messages will be displayed unless debugging has been enabled.
Parameters
string$messageUser message
string$levelNOTICE | WARNING | ERROR
Returns
bool
Since
1.7.0

Definition at line 1083 of file elgglib.php.

elgg_register_css (   $name,
  $url,
  $priority = null 
)

Register a CSS file for inclusion in the HTML head.

Parameters
string$nameAn identifier for the CSS file
string$urlURL of the CSS file
int$priorityPriority of the CSS file (lower numbers load earlier)
Returns
bool
Since
1.8.0
Examples:
/root/Elgg/engine/lib/views.php.

Definition at line 229 of file elgglib.php.

elgg_register_event_handler (   $event,
  $object_type,
  $callback,
  $priority = 500 
)

Register a callback 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 to an event. Multiple handlers can be registered for the same event and will be executed in order of $priority.

For most events, any handler returning false will halt the execution chain and cause the event to be "cancelled". For After Events, the return values of the handlers will be ignored and all handlers will be called.

This function is called with the event name, event type, and handler callback name. Setting the optional $priority allows plugin authors to specify when the callback should be run. Priorities for plugins should be 1-1000.

The callback 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.

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.

$event and $object_type can use the special keyword 'all'. Handler callbacks registered with $event = all will be called for all events of type $object_type. Similarly, callbacks 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 callback will be called for all events.

Event handler callbacks 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 callback to test the passed parameters before taking an action.

When referring to events, the preferred syntax is "event, type".

Examples:
/root/Elgg/engine/lib/cache.php, /root/Elgg/engine/lib/output.php, and /root/Elgg/engine/lib/views.php.

Definition at line 669 of file elgglib.php.

elgg_register_external_file (   $type,
  $name,
  $url,
  $location,
  $priority = 500 
)

Core registration function for external files.

Parameters
string$typeType of external resource (js or css)
string$nameIdentifier used as key
string$urlURL
string$locationLocation in the page to include the file
int$priorityLoading priority of the file
Returns
bool
Since
1.8.0

Definition at line 282 of file elgglib.php.

elgg_register_js (   $name,
  $url,
  $location = 'head',
  $priority = null 
)

Register a JavaScript file for inclusion.

This function handles adding JavaScript to a web page. If multiple calls are made to register the same JavaScript file based on the $id variable, only the last file is included. This allows a plugin to add JavaScript from a view that may be called more than once. It also handles more than one plugin adding the same JavaScript.

jQuery plugins often have filenames such as jquery.rating.js. A best practice is to base $name on the filename: "jquery.rating". It is recommended to not use version numbers in the name.

The JavaScript files can be local to the server or remote (such as Google's CDN).

Parameters
string$nameAn identifier for the JavaScript library
string$urlURL of the JavaScript file
string$locationPage location: head or footer. (default: head)
int$priorityPriority of the JS file (lower numbers load earlier)
Returns
bool
Since
1.8.0
Examples:
/root/Elgg/engine/lib/views.php.

Definition at line 128 of file elgglib.php.

elgg_register_library (   $name,
  $location 
)

Register a php library.

Parameters
string$nameThe name of the library
string$locationThe location of the file
Returns
void
Since
1.8.0

Definition at line 19 of file elgglib.php.

elgg_register_plugin_hook_handler (   $hook,
  $type,
  $callback,
  $priority = 500 
)

Register a callback as a plugin hook handler.

Plugin hooks allow developers to losely couple plugins and features by responding to and emitting elgg_trigger_plugin_hook() customizable hooks. Handler callbacks can respond to the hook, change the details of the hook, or ignore it.

Multiple handlers can be registered for a plugin hook, and each callback is called in order of priority. If the return value of a handler is not null, that value is passed to the next callback in the call stack. When all callbacks have been run, the final value is passed back to the caller via elgg_trigger_plugin_hook().

Similar to Elgg Events, plugin hook handler callbacks are registered by passing a hook, a type, and a priority.

The callback is passed 4 arguments when called: $hook, $type, $value, and $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.
Examples:
/root/Elgg/engine/lib/output.php, and /root/Elgg/engine/lib/views.php.

Definition at line 853 of file elgglib.php.

elgg_require_js (   $name)

Request that Elgg load an AMD module onto the page.

Parameters
string$nameThe AMD module name.
Returns
void
Since
1.9.0

Definition at line 202 of file elgglib.php.

elgg_sort_3d_array_by_value ( $array,
  $element,
  $sort_order = SORT_ASC,
  $sort_type = SORT_LOCALE_STRING 
)

Sorts a 3d array by specific element.

Warning
Will re-index numeric indexes.
Note
This operates the same as the built-in sort functions. It sorts the array and returns a bool for success.

Do this: elgg_sort_3d_array_by_value($my_array); Not this: $my_array = elgg_sort_3d_array_by_value($my_array);

Parameters
array&$arrayArray to sort
string$elementElement to sort by
int$sort_orderPHP sort order http://us2.php.net/array_multisort
int$sort_typePHP sort type http://us2.php.net/sort
Returns
bool

Definition at line 1496 of file elgglib.php.

elgg_trigger_after_event (   $event,
  $object_type,
  $object = null 
)

Trigger an "After event" indicating a process has finished.

Unlike regular events, all the handlers will be called, their return values ignored.

To register for an after event, append ":after" to the event name when registering.

Parameters
string$eventThe event type. The fired event type will be appended with ":after".
string$object_typeThe object type
string$objectThe object involved in the event
Returns
true
See also
elgg_trigger_before_event

Definition at line 760 of file elgglib.php.

elgg_trigger_before_event (   $event,
  $object_type,
  $object = null 
)

Trigger a "Before event" indicating a process is about to begin.

Like regular events, a handler returning false will cancel the process and false will be returned.

To register for a before event, append ":before" to the event name when registering.

Parameters
string$eventThe event type. The fired event type will be appended with ":before".
string$object_typeThe object type
string$objectThe object involved in the event
Returns
bool False if any handler returned false, otherwise true
See also
elgg_trigger_event
elgg_trigger_after_event

Definition at line 741 of file elgglib.php.

elgg_trigger_deprecated_event (   $event,
  $object_type,
  $object = null,
  $message,
  $version 
)

Trigger an event normally, but send a notice about deprecated use if any handlers are registered.

Parameters
string$eventThe event type
string$object_typeThe object type
string$objectThe object involved in the event
string$messageThe deprecation message
string$versionHuman-readable release version: 1.9, 1.10, ...
Returns
bool
See also
elgg_trigger_event

Definition at line 780 of file elgglib.php.

elgg_trigger_event (   $event,
  $object_type,
  $object = null 
)

Trigger an Elgg Event and attempt to run all handler callbacks registered to that event, type.

This function attempts to run all handlers registered to $event, $object_type or the special keyword 'all' for either or both. If a handler returns false, the event will be cancelled (no further handlers will be called, and this function will return false).

$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 associated with the event.

Warning
Elgg events should only be triggered by core. Plugin authors should use trigger_elgg_plugin_hook() instead.

When referring to events, the preferred syntax is "event, type".

Definition at line 720 of file elgglib.php.

elgg_trigger_plugin_hook (   $hook,
  $type,
  $params = null,
  $returnvalue = null 
)

Trigger a Plugin Hook and run all handler callbacks registered to that hook:type.

This function runs all handlers registered to $hook, $type or the special keyword 'all' for either or both.

Use $params to send additional information to the handler callbacks.

$returnvalue is the initial value to pass to the handlers, which can change it by returning non-null values. It is useful to use $returnvalue to set defaults. If no handlers are registered, $returnvalue is immediately returned.

Handlers that return null (or with no explicit return or return value) will not change the value of $returnvalue.

$hook is usually a verb: import, get_views, output.

$type is usually a noun: user, ecml, page.

Like Elgg Events, $hook and $type can use the special keyword 'all'. Handler callbacks 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.

It's not possible for a plugin hook to change a non-null $returnvalue to null.

Examples:
/root/Elgg/engine/lib/output.php, and /root/Elgg/engine/lib/views.php.

Definition at line 925 of file elgglib.php.

elgg_unregister_css (   $name)

Unregister a CSS file.

Parameters
string$nameThe identifier for the CSS file
Returns
bool
Since
1.8.0

Definition at line 241 of file elgglib.php.

elgg_unregister_event_handler (   $event,
  $object_type,
  $callback 
)

Unregisters a callback for an event.

Parameters
string$eventThe event type
string$object_typeThe object type
string$callbackThe callback
Returns
bool true if a handler was found and removed
Since
1.7

Definition at line 683 of file elgglib.php.

elgg_unregister_external_file (   $type,
  $name 
)

Unregister an external file.

Parameters
string$typeType of file: js or css
string$nameThe identifier of the file
Returns
bool
Since
1.8.0

Definition at line 341 of file elgglib.php.

elgg_unregister_js (   $name)

Unregister a JavaScript file.

Parameters
string$nameThe identifier for the JavaScript library
Returns
bool
Since
1.8.0

Definition at line 175 of file elgglib.php.

elgg_unregister_plugin_hook_handler (   $hook,
  $entity_type,
  $callback 
)

Unregister a callback as a plugin hook.

Parameters
string$hookThe name of the hook
string$entity_typeThe name of the type of entity (eg "user", "object" etc)
callable$callbackThe PHP callback to be removed
Returns
void
Since
1.8.0

Definition at line 867 of file elgglib.php.

forward (   $location = "",
  $reason = 'system' 
)

Forward to $location.

Sends a 'Location: $location' header and exists. If headers have already been sent, throws an exception.

Parameters
string$locationURL to forward to browser to. This can be a path relative to the network's URL.
string$reasonShort explanation for why we're forwarding. Set to '404' to forward to error page. Default message is 'system'.
Returns
void
Exceptions
SecurityException

Definition at line 79 of file elgglib.php.

ini_get_bool (   $ini_get_arg)

Return the state of a php.ini setting as a bool.

Warning
Using this on ini settings that are not boolean will be inaccurate!
Parameters
string$ini_get_argThe INI setting
Returns
bool Depending on whether it's on or off

Definition at line 1522 of file elgglib.php.

is_not_null (   $string)

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.

Parameters
string$stringThe string to test
Returns
bool

Definition at line 1573 of file elgglib.php.

register_error (   $error)

Display an error on next page load.

See also
system_messages()
Parameters
string | array$errorError or errors to add
Returns
bool

Definition at line 605 of file elgglib.php.

sanitise_filepath (   $path,
  $append_slash = true 
)

Sanitise file paths ensuring that they begin and end with slashes etc.

Parameters
string$pathThe path
bool$append_slashAdd tailing slash
Returns
string

Definition at line 484 of file elgglib.php.

system_message (   $message)

Display a system message on next page load.

See also
system_messages()
Parameters
string | array$messageMessage or messages to add
Returns
bool

Definition at line 592 of file elgglib.php.

system_messages (   $message = null,
  $register = "success",
  $count = false 
)

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 views/default/page/shells/default.php and displays messages as javascript popups.

Examples:
/root/Elgg/engine/lib/views.php.

Definition at line 532 of file elgglib.php.

Variable Documentation

const ACCESS_DEFAULT -1

Definition at line 2120 of file elgglib.php.

const ACCESS_FRIENDS -2

Definition at line 2124 of file elgglib.php.

const ACCESS_LOGGED_IN 1

Definition at line 2122 of file elgglib.php.

const ACCESS_PRIVATE 0

Definition at line 2121 of file elgglib.php.

const ACCESS_PUBLIC 2

Definition at line 2123 of file elgglib.php.

const ELGG_ENTITIES_ANY_VALUE null

Definition at line 2134 of file elgglib.php.

const ELGG_ENTITIES_NO_VALUE 0

Definition at line 2143 of file elgglib.php.

const REFERER -1

Definition at line 2162 of file elgglib.php.

const REFERRER -1

Definition at line 2152 of file elgglib.php.