aboutsummaryrefslogtreecommitdiffstats
path: root/include
diff options
context:
space:
mode:
authormistic100 <mistic@piwigo.org>2013-11-20 12:15:36 +0000
committermistic100 <mistic@piwigo.org>2013-11-20 12:15:36 +0000
commite5ed169950821600f222d71f79656afb3fca143d (patch)
treea71e7e49f7afeb5443056cb1027a2d81c5bd51ba /include
parent0ea814f7819f8fe1a2e203c1d7ec0de1609fbc64 (diff)
feature 2999: Documentation of include/functions_plugins.inc.php
git-svn-id: http://piwigo.org/svn/trunk@25601 68402e56-0260-453c-a942-63ccdbb3a9ee
Diffstat (limited to '')
-rw-r--r--include/functions_plugins.inc.php169
1 files changed, 113 insertions, 56 deletions
diff --git a/include/functions_plugins.inc.php b/include/functions_plugins.inc.php
index 62a4796ae..f15de8f44 100644
--- a/include/functions_plugins.inc.php
+++ b/include/functions_plugins.inc.php
@@ -21,41 +21,54 @@
// | USA. |
// +-----------------------------------------------------------------------+
-/*
-Events and event handlers are the core of Piwigo plugin management.
-Plugins are addons that are found in plugins subdirectory. If activated, PWG
-will include the index.php of each plugin.
-Events are triggered by PWG core code. Plugins (or even PWG itself) can
-register their functions to handle these events. An event is identified by a
-string.
-*/
+/**
+ * @package functions\plugins
+ */
+
+/** base directory of plugins */
define('PHPWG_PLUGINS_PATH', PHPWG_ROOT_PATH.'plugins/');
+/** default priority for plugins handlers */
define('EVENT_HANDLER_PRIORITY_NEUTRAL', 50);
/**
- * class PluginMaintain
- * used to declare maintenance methods of a plugin
+ * Used to declare maintenance methods of a plugin.
*/
abstract class PluginMaintain
{
+ /** @var string $plugin_id */
protected $plugin_id;
-
+
+ /**
+ * @param string $id
+ */
function __construct($id)
{
$this->plugin_id = $id;
}
-
+
+ /**
+ * @param string $plugin_version
+ * @param array $errors - used to return error messages
+ */
abstract function install($plugin_version, &$errors=array());
+
+ /**
+ * @param string $plugin_version
+ * @param array $errors - used to return error messages
+ */
abstract function activate($plugin_version, &$errors=array());
+
abstract function deactivate();
+
abstract function uninstall();
-
- /*
- * test if a plugin needs to be updated and call a update function
- * @param: string $version, version exposed by the plugin
- * @param: string $on_update, name of a method to call when an update is needed
+
+ /**
+ * Tests if the plugin needs to be updated and call an update function
+ *
+ * @param string $version version exposed by the plugin (potentially new)
+ * @param string $on_update name of a method to call when an update is needed
* it receives the previous version as first parameter
*/
function autoUpdate($version, $on_update=null)
@@ -89,26 +102,36 @@ UPDATE '. PLUGINS_TABLE .'
}
/**
- * class ThemeMaintain
- * used to declare maintenance methods of a theme
+ * Used to declare maintenance methods of a theme.
*/
abstract class ThemeMaintain
{
+ /** @var string $theme_id */
protected $theme_id;
-
+
+ /**
+ * @param string $id
+ */
function __construct($id)
{
$this->theme_id = $id;
}
-
+
+ /**
+ * @param string $theme_version
+ * @param array $errors - used to return error messages
+ */
abstract function activate($theme_version, &$errors=array());
+
abstract function deactivate();
+
abstract function delete();
- /*
- * test if a theme needs to be updated and call a update function
- * @param: string $version, version exposed by the theme
- * @param: string $on_update, name of a method to call when an update is needed
+ /**
+ * Tests if the theme needs to be updated and call an update function
+ *
+ * @param string $version version exposed by the theme (potentially new)
+ * @param string $on_update name of a method to call when an update is needed
* it receives the previous version as first parameter
*/
function autoUpdate($version, $on_update=null)
@@ -143,12 +166,13 @@ UPDATE '. THEMES_TABLE .'
}
-/* Register a event handler.
+/**
+ * Register an event handler.
+ *
* @param string $event the name of the event to listen to
- * @param mixed $func the function that will handle the event
- * @param int $priority optional priority (greater priority will
- * be executed at last)
-*/
+ * @param Callable $func the callback function
+ * @param int $priority greater priority will be executed at last
+ */
function add_event_handler($event, $func,
$priority=EVENT_HANDLER_PRIORITY_NEUTRAL, $accepted_args=1)
{
@@ -173,12 +197,14 @@ function add_event_handler($event, $func,
return true;
}
-/* Register a event handler.
- * @param string $event the name of the event to listen to
- * @param mixed $func the function that needs removal
- * @param int $priority optional priority (greater priority will
- * be executed at last)
-*/
+/**
+ * Removes an event handler.
+ * @see add_event_handler()
+ *
+ * @param string $event
+ * @param Callable $func
+ * @param int $priority
+ */
function remove_event_handler($event, $func,
$priority=EVENT_HANDLER_PRIORITY_NEUTRAL)
{
@@ -210,10 +236,17 @@ function remove_event_handler($event, $func,
return false;
}
-/* Triggers an event and calls all registered event handlers
- * @param string $event name of the event
- * @param mixed $data data to pass to handlers
-*/
+/**
+ * Triggers a modifier event and calls all registered event handlers.
+ * trigger_modify() is used as a modifier: it allows to transmit _$data_
+ * through all handlers, thus each handler MUST return a value,
+ * optional _$args_ are not transmitted.
+ *
+ * @param string $event
+ * @param mixed $data data to transmit to all handlers
+ * @param mixed $args,... optional arguments
+ * @return mixed $data
+ */
function trigger_event($event, $data=null)
{
global $pwg_event_handlers;
@@ -245,13 +278,20 @@ function trigger_event($event, $data=null)
return $data;
}
-function trigger_action($event, $data=null)
+/**
+ * Triggers an notifier event and calls all registered event handlers.
+ * trigger_action() is only used as a notifier, no modification of data is possible
+ *
+ * @param string $event
+ * @param mixed $args,... optional arguments
+ */
+function trigger_action($event)
{
global $pwg_event_handlers;
if ( isset($pwg_event_handlers['trigger']) and $event!='trigger' )
{// special case for debugging - avoid recursive calls
trigger_action('trigger',
- array('type'=>'action', 'event'=>$event, 'data'=>$data) );
+ array('type'=>'action', 'event'=>$event, 'data'=>null) );
}
if ( !isset($pwg_event_handlers[$event]) )
@@ -272,11 +312,14 @@ function trigger_action($event, $data=null)
}
}
-/** Saves some data with the associated plugim id. It can be retrieved later (
- * during this script lifetime) using get_plugin_data
- * @param string plugin_id
- * @param mixed data
- * returns true on success, false otherwise
+/**
+ * Saves some data with the associated plugin id, data are only available
+ * during script lifetime.
+ * @depracted 2.6
+ *
+ * @param string $plugin_id
+ * @param mixed $data
+ * @return bool
*/
function set_plugin_data($plugin_id, &$data)
{
@@ -289,23 +332,31 @@ function set_plugin_data($plugin_id, &$data)
return false;
}
-/** Retrieves plugin data saved previously with set_plugin_data
- * @param string plugin_id
+/**
+ * Retrieves plugin data saved previously with set_plugin_data.
+ * @see set_plugin_data()
+ * @depracted 2.6
+ *
+ * @param string $plugin_id
+ * @return mixed
*/
function &get_plugin_data($plugin_id)
{
global $pwg_loaded_plugins;
- if ( isset($pwg_loaded_plugins[$plugin_id]) )
+ if ( isset($pwg_loaded_plugins[$plugin_id]['plugin_data']) )
{
return $pwg_loaded_plugins[$plugin_id]['plugin_data'];
}
return null;
}
-/* Returns an array of plugins defined in the database
- * @param string $state optional filter on this state
- * @param string $id optional returns only data about given plugin
-*/
+/**
+ * Returns an array of plugins defined in the database.
+ *
+ * @param string $state optional filter
+ * @param string $id returns only data about given plugin
+ * @return array
+ */
function get_db_plugins($state='', $id='')
{
$query = '
@@ -334,7 +385,11 @@ SELECT * FROM '.PLUGINS_TABLE;
return $plugins;
}
-
+/**
+ * Loads a plugin, it includes the main.inc.php file and updates _$pwg_loaded_plugins_.
+ *
+ * @param string $plugin
+ */
function load_plugin($plugin)
{
$file_name = PHPWG_PLUGINS_PATH.$plugin['id'].'/main.inc.php';
@@ -346,7 +401,9 @@ function load_plugin($plugin)
}
}
-/*loads all the plugins on startup*/
+/**
+ * Loads all the registered plugins.
+ */
function load_plugins()
{
global $conf, $pwg_loaded_plugins;