Changeset 25601 for trunk


Ignore:
Timestamp:
Nov 20, 2013, 1:15:36 PM (10 years ago)
Author:
mistic100
Message:

feature 2999: Documentation of include/functions_plugins.inc.php

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/include/functions_plugins.inc.php

    r25406 r25601  
    2222// +-----------------------------------------------------------------------+
    2323
    24 /*
    25 Events and event handlers are the core of Piwigo plugin management.
    26 Plugins are addons that are found in plugins subdirectory. If activated, PWG
    27 will include the index.php of each plugin.
    28 Events are triggered by PWG core code. Plugins (or even PWG itself) can
    29 register their functions to handle these events. An event is identified by a
    30 string.
    31 */
    32 
     24/**
     25 * @package functions\plugins
     26 */
     27
     28
     29/** base directory of plugins */
    3330define('PHPWG_PLUGINS_PATH', PHPWG_ROOT_PATH.'plugins/');
     31/** default priority for plugins handlers */
    3432define('EVENT_HANDLER_PRIORITY_NEUTRAL', 50);
    3533
    3634
    3735/**
    38  * class PluginMaintain
    39  * used to declare maintenance methods of a plugin
     36 * Used to declare maintenance methods of a plugin.
    4037 */
    4138abstract class PluginMaintain
    4239{
     40  /** @var string $plugin_id */
    4341  protected $plugin_id;
    44  
     42
     43  /**
     44   * @param string $id
     45   */
    4546  function __construct($id)
    4647  {
    4748    $this->plugin_id = $id;
    4849  }
    49  
     50
     51  /**
     52   * @param string $plugin_version
     53   * @param array $errors - used to return error messages
     54   */
    5055  abstract function install($plugin_version, &$errors=array());
     56
     57  /**
     58   * @param string $plugin_version
     59   * @param array $errors - used to return error messages
     60   */
    5161  abstract function activate($plugin_version, &$errors=array());
     62
    5263  abstract function deactivate();
     64
    5365  abstract function uninstall();
    54  
    55   /*
    56    * test if a plugin needs to be updated and call a update function
    57    * @param: string $version, version exposed by the plugin
    58    * @param: string $on_update, name of a method to call when an update is needed
     66
     67  /**
     68   * Tests if the plugin needs to be updated and call an update function
     69   *
     70   * @param string $version version exposed by the plugin (potentially new)
     71   * @param string $on_update name of a method to call when an update is needed
    5972   *          it receives the previous version as first parameter
    6073   */
    … …  
    90103
    91104/**
    92  * class ThemeMaintain
    93  * used to declare maintenance methods of a theme
     105 * Used to declare maintenance methods of a theme.
    94106 */
    95107abstract class ThemeMaintain
    96108{
     109  /** @var string $theme_id */
    97110  protected $theme_id;
    98  
     111
     112  /**
     113   * @param string $id
     114   */
    99115  function __construct($id)
    100116  {
    101117    $this->theme_id = $id;
    102118  }
    103  
     119
     120  /**
     121   * @param string $theme_version
     122   * @param array $errors - used to return error messages
     123   */
    104124  abstract function activate($theme_version, &$errors=array());
     125
    105126  abstract function deactivate();
     127
    106128  abstract function delete();
    107129 
    108   /*
    109    * test if a theme needs to be updated and call a update function
    110    * @param: string $version, version exposed by the theme
    111    * @param: string $on_update, name of a method to call when an update is needed
     130  /**
     131   * Tests if the theme needs to be updated and call an update function
     132   *
     133   * @param string $version version exposed by the theme (potentially new)
     134   * @param string $on_update name of a method to call when an update is needed
    112135   *          it receives the previous version as first parameter
    113136   */
    … …  
    144167
    145168
    146 /* Register a event handler.
     169/**
     170 * Register an event handler.
     171 *
    147172 * @param string $event the name of the event to listen to
    148  * @param mixed $func the function that will handle the event
    149  * @param int $priority optional priority (greater priority will
    150  * be executed at last)
    151 */
     173 * @param Callable $func the callback function
     174 * @param int $priority greater priority will be executed at last
     175 */
    152176function add_event_handler($event, $func,
    153177    $priority=EVENT_HANDLER_PRIORITY_NEUTRAL, $accepted_args=1)
    … …  
    174198}
    175199
    176 /* Register a event handler.
    177  * @param string $event the name of the event to listen to
    178  * @param mixed $func the function that needs removal
    179  * @param int $priority optional priority (greater priority will
    180  * be executed at last)
    181 */
     200/**
     201 * Removes an event handler.
     202 * @see add_event_handler()
     203 *
     204 * @param string $event
     205 * @param Callable $func
     206 * @param int $priority
     207 */
    182208function remove_event_handler($event, $func,
    183209   $priority=EVENT_HANDLER_PRIORITY_NEUTRAL)
    … …  
    211237}
    212238
    213 /* Triggers an event and calls all registered event handlers
    214  * @param string $event name of the event
    215  * @param mixed $data data to pass to handlers
    216 */
     239/**
     240 * Triggers a modifier event and calls all registered event handlers.
     241 * trigger_modify() is used as a modifier: it allows to transmit _$data_
     242 * through all handlers, thus each handler MUST return a value,
     243 * optional _$args_ are not transmitted.
     244 *
     245 * @param string $event
     246 * @param mixed $data data to transmit to all handlers
     247 * @param mixed $args,... optional arguments
     248 * @return mixed $data
     249 */
    217250function trigger_event($event, $data=null)
    218251{
    … …  
    246279}
    247280
    248 function trigger_action($event, $data=null)
     281/**
     282 * Triggers an notifier event and calls all registered event handlers.
     283 * trigger_action() is only used as a notifier, no modification of data is possible
     284 *
     285 * @param string $event
     286 * @param mixed $args,... optional arguments
     287 */
     288function trigger_action($event)
    249289{
    250290  global $pwg_event_handlers;
    … …  
    252292  {// special case for debugging - avoid recursive calls
    253293    trigger_action('trigger',
    254         array('type'=>'action', 'event'=>$event, 'data'=>$data) );
     294        array('type'=>'action', 'event'=>$event, 'data'=>null) );
    255295  }
    256296
    … …  
    273313}
    274314
    275 /** Saves some data with the associated plugim id. It can be retrieved later (
    276  * during this script lifetime) using get_plugin_data
    277  * @param string plugin_id
    278  * @param mixed data
    279  * returns true on success, false otherwise
     315/**
     316 * Saves some data with the associated plugin id, data are only available
     317 * during script lifetime.
     318 * @depracted 2.6
     319 *
     320 * @param string $plugin_id
     321 * @param mixed $data
     322 * @return bool
    280323 */
    281324function set_plugin_data($plugin_id, &$data)
    … …  
    290333}
    291334
    292 /** Retrieves plugin data saved previously with set_plugin_data
    293  * @param string plugin_id
     335/**
     336 * Retrieves plugin data saved previously with set_plugin_data.
     337 * @see set_plugin_data()
     338 * @depracted 2.6
     339 *
     340 * @param string $plugin_id
     341 * @return mixed
    294342 */
    295343function &get_plugin_data($plugin_id)
    296344{
    297345  global $pwg_loaded_plugins;
    298   if ( isset($pwg_loaded_plugins[$plugin_id]) )
     346  if ( isset($pwg_loaded_plugins[$plugin_id]['plugin_data']) )
    299347  {
    300348    return $pwg_loaded_plugins[$plugin_id]['plugin_data'];
    … …  
    303351}
    304352
    305 /* Returns an array of plugins defined in the database
    306  * @param string $state optional filter on this state
    307  * @param string $id optional returns only data about given plugin
    308 */
     353/**
     354 * Returns an array of plugins defined in the database.
     355 *
     356 * @param string $state optional filter
     357 * @param string $id returns only data about given plugin
     358 * @return array
     359 */
    309360function get_db_plugins($state='', $id='')
    310361{
    … …  
    335386}
    336387
    337 
     388/**
     389 * Loads a plugin, it includes the main.inc.php file and updates _$pwg_loaded_plugins_.
     390 *
     391 * @param string $plugin
     392 */
    338393function load_plugin($plugin)
    339394{
    … …  
    347402}
    348403
    349 /*loads all the plugins on startup*/
     404/**
     405 * Loads all the registered plugins.
     406 */
    350407function load_plugins()
    351408{
Note: See TracChangeset for help on using the changeset viewer.