/functions/plugin.php

Description
Description | Functions

plugin.php

This file provides the framework for a plugin architecture.

Documentation on how to write plugins might show up some time.

Functions
Description | Functions
boolean_hook_function (line 202)

This function is used for hooks which are to return true or false. If $priority is > 0, any one or more trues will override any falses. If $priority < 0, then one or more falses will override any trues.

Priority 0 means majority rules. Ties will be broken with $tie

If any plugin on this hook wants to modify the $args plugin parameter, it simply has to use call-by-reference syntax in the hook function that it has registered for the current hook. Note that this is in addition to (entirely independent of) the return value for this hook.

  • return: The result of the function
boolean boolean_hook_function (string $name, mixed &$args, [int $priority = 0], [boolean $tie = false])
  • string $name: The hook name
  • mixed &$args: A single value or an array of arguments that are to be passed to all plugins operating off the hook being called. Note that this argument is passed by reference thus it is liable to be changed after the hook completes.
  • int $priority: See explanation above
  • boolean $tie: See explanation above
check_plugin_dependencies (line 941)

Check a plugin's other plugin dependencies.

Determines whether or not all of the given plugin's required plugins are installed and up to the proper version, and if they are activated if required.

By default, the desired plugin must be currently activated, and if it is not, this function will return FALSE. By overriding the default value of $force_inclusion, this function will attempt to grab dependency information from the given plugin even if it is not activated (plugin still has to be unpackaged and set in place in the plugins directory). Use with care - some plugins might break SquirrelMail when this is used.

NOTE that if a plugin does not report whether or not it has other plugin dependencies, this function will return TRUE, although that is possibly incorrect or misleading.

  • return: Boolean TRUE if all of the plugin's required plugins are correctly installed, the constant SQ_INCOMPATIBLE is returned if the given plugin is entirely incompatible with the current SquirrelMail version, otherwise an array of the required plugins that are either not installed or not up to the minimum required version. The array is keyed by plugin name where values are arrays again, where at least the following keys (and corresponding values) will be available: 'version' - value is the minimum version required for that plugin (in printable, non- parsed format) or the constant SQ_INCOMPATIBLE, which indicates that the plugin is actually incompatible (not required), 'activate' - value is boolean: TRUE indicates that the plugin must also be activated, FALSE means that it only needs to be present, but does not need to be activated.
  • since: 1.5.2
mixed check_plugin_dependencies (string $plugin_name, [bool $force_inclusion = FALSE])
  • string $plugin_name: plugin_name name of the plugin to check; must precisely match the plugin directory name
  • bool $force_inclusion: force_inclusion try to get version info for plugins not activated? (default FALSE)
check_plugin_version (line 499)

Check a plugin's version.

Returns TRUE if the given plugin is installed, activated and is at minimum version $a.$b.$c. If any one of those conditions fails, FALSE will be returned (careful of plugins that are sufficiently versioned but are not activated).

By overriding the default value of $force_inclusion, this function will attempt to grab versioning information from the given plugin even if it is not activated (the plugin still has to be unpackaged and set in place in the plugins directory). Use with care - some plugins might break SquirrelMail when this is used.

Note that this function assumes plugin versioning is consistently applied in the same fashion that SquirrelMail versions are, with the exception that an applicable SquirrelMail version may be appended to the version number (which will be ignored herein). That is, plugin version number schemes are expected in the following format: 1.2.3, or 1.2.3-1.4.0.

Any characters after the third number indicating things such as beta or release candidate versions are discarded, so formats such as the following will also work, although extra information about beta versions can possibly confuse the desired results of the version check: 1.2.3-beta4, 1.2.3.RC2, and so forth.

  • since: 1.5.2
bool check_plugin_version (string $plugin_name, [int $a = 0], [int $b = 0], [int $c = 0], [bool $force_inclusion = FALSE])
  • string $plugin_name: plugin_name Name of the plugin to check; must precisely match the plugin directory name
  • int $a: a Major version number
  • int $b: b Minor version number
  • int $c: c Release number
  • bool $force_inclusion: force_inclusion Try to get version info for plugins not activated? (default FALSE)
concat_hook_function (line 142)

This function executes a hook that allows for an arbitrary return value from each plugin that will be merged into one array (or one string if all return values are strings) and returned to the core hook location.

Note that unlike PHP's array_merge function, matching array keys will not overwrite each other, instead, values under such keys will be concatenated if they are both strings, or merged if they are arrays (in the same (non-overwrite) manner recursively).

Plugins returning non-arrays (strings, objects, etc) will have their output added to the end of the ultimate return array, unless ALL values returned are strings, in which case one string with all returned strings concatenated together is returned (unless $force_array is TRUE).

If any plugin on this hook wants to modify the $args plugin parameter, it simply has to use call-by-reference syntax in the hook function that it has registered for the current hook. Note that this is in addition to (entirely independent of) the return value for this hook.

  • return: the merged return arrays or strings of each plugin on this hook.
mixed concat_hook_function (string $name, mixed &$args, [boolean $force_array = FALSE])
  • string $name: Name of hook being executed
  • mixed &$args: A single value or an array of arguments that are to be passed to all plugins operating off the hook being called. Note that this argument is passed by reference thus it is liable to be changed after the hook completes.
  • boolean $force_array: When TRUE, guarantees the return value will ALWAYS be an array, (simple strings will be forced into a one-element array). When FALSE, behavior is as described above (OPTIONAL; default behavior is to return mixed - array or string).
do_hook (line 72)

This function executes a plugin hook.

It includes an arbitrary return value that is managed by all plugins on the same hook and returned to the core hook location.

The desired format of the return value should be defined by the context in which the hook is called.

Note that the master return value for this hook is passed to each plugin after the main argument(s) value/array as a convenience only - to show what the current return value is even though it is liable to be changed by other plugins.

If any plugin on this hook wants to modify the $args plugin parameter, it simply has to use call-by-reference syntax in the hook function that it has registered for the current hook. Note that this is in addition to (entirely independent of) the return value for this hook.

  • return: The return value that is managed by the plugins on the current hook.
mixed do_hook (string $name, mixed &$args)
  • string $name: Name of hook being executed
  • mixed &$args: A single value or an array of arguments that are to be passed to all plugins operating off the hook being called. Note that this argument is passed by reference thus it is liable to be changed after the hook completes.
get_plugin_dependencies (line 789)

Get a plugin's other plugin dependencies.

Determines and returns all the other plugins that a given plugin requires, as well as the minimum version numbers of the required plugins and whether or not they need to be activated.

By default, the desired plugin must be currently activated, and if it is not, this function will return FALSE. By overriding the default value of $force_inclusion, this function will attempt to grab dependency information from the given plugin even if it is not activated (plugin still has to be unpackaged and set in place in the plugins directory). Use with care - some plugins might break SquirrelMail when this is used.

By turning on the $do_parse argument (it is on by default), the version string for each required plugin will be parsed by SquirrelMail into a SquirrelMail-compatible version string (such as "1.2.3") if it is not already. See notes about version formatting under the get_plugin_version() function documentation.

  • return: Boolean FALSE is returned if the plugin could not be found or does not indicate whether it has other plugin dependencies, the constant SQ_INCOMPATIBLE is returned if the given plugin is entirely incompatible with the current SquirrelMail version, otherwise an array is returned where keys are the names of required plugin dependencies, and values are arrays again, where at least the following keys (and corresponding values) will be available: 'version' - value is the minimum version required for that plugin (the format of which might vary per the value of $do_parse as well as if the plugin requires a SquirrelMail core plugin, in which case it is "CORE" or "CORE:1.5.2" or similar, or, if the plugin is actually incompatible (not required) with this one, the constant SQ_INCOMPATIBLE will be found here), 'activate' - value is boolean: TRUE indicates that the plugin must also be activated, FALSE means that it only needs to be present, but does not need to be activated. Note that the return value might be an empty array, indicating that the plugin has no dependencies.
  • since: 1.5.2
mixed get_plugin_dependencies (string $plugin_name, [bool $force_inclusion = FALSE], [bool $do_parse = TRUE])
  • string $plugin_name: plugin_name name of the plugin to check; must precisely match the plugin directory name
  • bool $force_inclusion: force_inclusion try to get version info for plugins not activated? (default FALSE)
  • bool $do_parse: do_parse return the version numbers for required plugins in SquirrelMail-compatible format (default FALSE)
get_plugin_requirement (line 577)

Get a certain plugin requirement.

Attempts to find the given plugin requirement value in the given plugin's informational array, and returns it or NULL if it was not found.

Some plugins have different values for the same requirement depending on the SquirrelMail version, and this function is smart enough to take that into account.

By default, the desired plugin must be currently activated, and if it is not, this function will return NULL. By overriding the default value of $force_inclusion, this function will attempt to grab requirement information from the given plugin even if it is not activated (plugin still has to be unpackaged and set in place in the plugins directory). Use with care - some plugins might break SquirrelMail when this is used.

  • return: NULL is returned if the plugin could not be found or does not include the given requirement, the constant SQ_INCOMPATIBLE is returned if the given plugin is entirely incompatible with the current SquirrelMail version (unless $ignore_incompatible is TRUE), otherwise the value of the requirement is returned, whatever that may be (varies per requirement type).
  • since: 1.5.2
mixed get_plugin_requirement (string $plugin_name, string $requirement, [boolean $ignore_incompatible = TRUE], [boolean $force_inclusion = FALSE])
  • string $plugin_name: Name of the plugin to check; must precisely match the plugin directory name
  • string $requirement: The desired requirement name
  • boolean $ignore_incompatible: When TRUE, version incompatibility information will NOT be returned if found; when FALSE, it will be (OPTIONAL; default TRUE)
  • boolean $force_inclusion: Try to get requirement info for plugins not activated? (OPTIONAL; default FALSE)
get_plugin_version (line 346)

Get a plugin's version.

Determines and returns a plugin's version.

By default, the desired plugin must be currently activated, and if it is not, this function will return FALSE. By overriding the default value of $force_inclusion, this function will attempt to grab versioning information from the given plugin even if it is not activated (plugin still has to be unpackaged and set in place in the plugins directory). Use with care - some plugins might break SquirrelMail when this is used.

By turning on the $do_parse argument, the version string will be parsed by SquirrelMail into a SquirrelMail-compatible version string (such as "1.2.3") if it is not already.

Note that this assumes plugin versioning is consistently applied in the same fashion that SquirrelMail versions are, with the exception that an applicable SquirrelMail version may be appended to the version number (which will be ignored herein). That is, plugin version number schemes are expected in the following format: 1.2.3, or 1.2.3-1.4.0.

Any characters after the third version number indicating things such as beta or release candidate versions are discarded, so formats such as the following will also work, although extra information about beta versions can possibly confuse the desired results of the version check: 1.2.3-beta4, 1.2.3.RC2, and so forth.

  • return: The plugin version string if found, otherwise, boolean FALSE is returned indicating that no version information could be found for the plugin.
  • since: 1.5.2
mixed get_plugin_version (string $plugin_name, [bool $force_inclusion = FALSE], [bool $do_parse = FALSE])
  • string $plugin_name: plugin_name name of the plugin to check; must precisely match the plugin directory name
  • bool $force_inclusion: force_inclusion try to get version info for plugins not activated? (default FALSE)
  • bool $do_parse: do_parse return the plugin version in SquirrelMail-compatible format (default FALSE)
is_plugin_enabled (line 273)

Check if plugin is enabled

  • since: 1.5.1
boolean is_plugin_enabled (string $plugin_name)
  • string $plugin_name: plugin name
soupNazi (line 263)

Do not use, use checkForJavascript() instead.

This function checks whether the user's USER_AGENT is known to be broken. If so, returns true and the plugin is invisible to the offending browser. *** THIS IS A TEST FOR JAVASCRIPT SUPPORT ***

  • return: whether this browser properly supports JavaScript
  • deprecated: use checkForJavascript() since 1.5.1
bool soupNazi ()
use_plugin (line 21)

This function adds a plugin.

void use_plugin (string $name)
  • string $name: Internal plugin name (ie. delete_move_next)

Documentation generated on Mon, 13 Jan 2020 04:23:21 +0100 by phpDocumentor 1.4.3