Changeset 25601


Ignore:
Timestamp:
11/20/13 13:15:36 (6 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.