diff options
Diffstat (limited to 'include/functions_plugins.inc.php')
| -rw-r--r-- | include/functions_plugins.inc.php | 275 |
1 files changed, 233 insertions, 42 deletions
diff --git a/include/functions_plugins.inc.php b/include/functions_plugins.inc.php index 7d6da7289..d71f58491 100644 --- a/include/functions_plugins.inc.php +++ b/include/functions_plugins.inc.php @@ -2,7 +2,7 @@ // +-----------------------------------------------------------------------+ // | Piwigo - a PHP based photo gallery | // +-----------------------------------------------------------------------+ -// | Copyright(C) 2008-2013 Piwigo Team http://piwigo.org | +// | Copyright(C) 2008-2014 Piwigo Team http://piwigo.org | // | Copyright(C) 2003-2008 PhpWebGallery Team http://phpwebgallery.net | // | Copyright(C) 2002-2003 Pierrick LE GALL http://le-gall.net/pierrick | // +-----------------------------------------------------------------------+ @@ -21,25 +21,158 @@ // | 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 + */ -define('PHPWG_PLUGINS_PATH', PHPWG_ROOT_PATH.'plugins/'); +/** base directory of plugins */ +define('PHPWG_PLUGINS_PATH', PHPWG_ROOT_PATH.'plugins/'); +/** default priority for plugins handlers */ define('EVENT_HANDLER_PRIORITY_NEUTRAL', 50); -/* Register a event handler. + +/** + * 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(); + + /** + * 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) + { + global $pwg_loaded_plugins; + + $current_version = $pwg_loaded_plugins[$this->plugin_id]['version']; + + if ( $version == 'auto' or $current_version == 'auto' + or safe_version_compare($current_version, $version, '<') + ) + { + if (!empty($on_update)) + { + call_user_func(array(&$this, $on_update), $current_version); + } + + if ($version != 'auto') + { + $query = ' +UPDATE '. PLUGINS_TABLE .' + SET version = "'. $version .'" + WHERE id = "'. $this->plugin_id .'" +;'; + pwg_query($query); + + $pwg_loaded_plugins[$this->plugin_id]['version'] = $version; + } + } + } +} + +/** + * 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(); + + /** + * 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) + { + $query = ' +SELECT version + FROM '. THEMES_TABLE .' + WHERE id = "'. $this->theme_id .'" +;'; + list($current_version) = pwg_db_fetch_row(pwg_query($query)); + + if ( $version == 'auto' or $current_version == 'auto' + or safe_version_compare($current_version, $version, '<') + ) + { + if (!empty($on_update)) + { + call_user_func(array(&$this, $on_update), $current_version); + } + + if ($version != 'auto') + { + $query = ' +UPDATE '. THEMES_TABLE .' + SET version = "'. $version .'" + WHERE id = "'. $this->theme_id .'" +;'; + pwg_query($query); + } + } + } +} + + +/** + * 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) { @@ -64,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) { @@ -101,10 +236,29 @@ 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_change() 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. + * + * @since 2.6 + * @todo remove trigger_event() + * + * @param string $event + * @param mixed $data data to transmit to all handlers + * @param mixed $args,... optional arguments + * @return mixed $data + */ +function trigger_change($event, $data=null) +{ + return call_user_func_array('trigger_event', func_get_args()); +} + +/** + * @deprecated 2.6 + * @see trigger_change + */ function trigger_event($event, $data=null) { global $pwg_event_handlers; @@ -136,13 +290,32 @@ function trigger_event($event, $data=null) return $data; } -function trigger_action($event, $data=null) +/** + * Triggers a notifier event and calls all registered event handlers. + * trigger_notify() is only used as a notifier, no modification of data is possible + * + * @since 2.6 + * @todo remove trigger_action() + * + * @param string $event + * @param mixed $args,... optional arguments + */ +function trigger_notify($event) +{ + return call_user_func_array('trigger_action', func_get_args()); +} + +/** + * @deprecated 2.6 + * @see trigger_notify + */ +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]) ) @@ -163,11 +336,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) { @@ -180,23 +356,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 = ' @@ -220,12 +404,16 @@ SELECT * FROM '.PLUGINS_TABLE; $plugins = array(); while ($row = pwg_db_fetch_assoc($result)) { - array_push($plugins, $row); + $plugins[] = $row; } 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'; @@ -237,7 +425,9 @@ function load_plugin($plugin) } } -/*loads all the plugins on startup*/ +/** + * Loads all the registered plugins. + */ function load_plugins() { global $conf, $pwg_loaded_plugins; @@ -252,4 +442,5 @@ function load_plugins() trigger_action('plugins_loaded'); } } + ?>
\ No newline at end of file |