diff --git a/inc/plugincontroller.class.php b/inc/plugincontroller.class.php
index c825870cd142625481280ce397be4a4d819319de..33d8c92cd89a7cd45c06cc5693ecf963aac11214 100644
--- a/inc/plugincontroller.class.php
+++ b/inc/plugincontroller.class.php
@@ -11,15 +11,15 @@ if(!defined('DOKU_PLUGIN')) define('DOKU_PLUGIN',DOKU_INC.'lib/plugins/');
class Doku_Plugin_Controller {
- var $list_bytype = array();
- var $tmp_plugins = array();
- var $plugin_cascade = array('default'=>array(),'local'=>array(),'protected'=>array());
- var $last_local_config_file = '';
+ protected $list_bytype = array();
+ protected $tmp_plugins = array();
+ protected $plugin_cascade = array('default'=>array(),'local'=>array(),'protected'=>array());
+ protected $last_local_config_file = '';
/**
* Populates the master list of plugins
*/
- function __construct() {
+ public function __construct() {
$this->loadConfig();
$this->_populateMasterList();
}
@@ -34,11 +34,13 @@ class Doku_Plugin_Controller {
* false to only return enabled plugins,
* true to return both enabled and disabled plugins
*
- * @return array of plugin names
+ * @return array of
+ * - plugin names when $type = ''
+ * - or plugin component names when a $type is given
*
* @author Andreas Gohr <andi@splitbrain.org>
*/
- function getList($type='',$all=false){
+ public function getList($type='',$all=false){
// request the complete list
if (!$type) {
@@ -64,9 +66,9 @@ class Doku_Plugin_Controller {
* @param $name string name of the plugin to load
* @param $new bool true to return a new instance of the plugin, false to use an already loaded instance
* @param $disabled bool true to load even disabled plugins
- * @return objectreference the plugin object or null on failure
+ * @return DokuWiki_Plugin|DokuWiki_Syntax_Plugin|null the plugin object or null on failure
*/
- function load($type,$name,$new=false,$disabled=false){
+ public function load($type,$name,$new=false,$disabled=false){
//we keep all loaded plugins available in global scope for reuse
global $DOKU_PLUGINS;
@@ -108,26 +110,59 @@ class Doku_Plugin_Controller {
return $DOKU_PLUGINS[$type][$name];
}
- function isdisabled($plugin) {
+ /**
+ * Whether plugin is disabled
+ *
+ * @param string $plugin name of plugin
+ * @return bool; true disabled, false enabled
+ */
+ public function isdisabled($plugin) {
return empty($this->tmp_plugins[$plugin]);
}
- function disable($plugin) {
+ /**
+ * Disable the plugin
+ *
+ * @param string $plugin name of plugin
+ * @return bool; true saving succeed, false saving failed
+ */
+ public function disable($plugin) {
if(array_key_exists($plugin,$this->plugin_cascade['protected'])) return false;
$this->tmp_plugins[$plugin] = 0;
return $this->saveList();
}
- function enable($plugin) {
+ /**
+ * Enable the plugin
+ *
+ * @param string $plugin name of plugin
+ * @return bool; true saving succeed, false saving failed
+ */
+ public function enable($plugin) {
if(array_key_exists($plugin,$this->plugin_cascade['protected'])) return false;
$this->tmp_plugins[$plugin] = 1;
return $this->saveList();
}
- function get_directory($plugin) {
+ /**
+ * Returns directory name of plugin
+ *
+ * @param string $plugin name of plugin
+ * @return string name of directory
+ */
+ public function get_directory($plugin) {
return $plugin;
}
+ /**
+ * Returns cascade of the config files
+ *
+ * @return array with arrays of plugin configs
+ */
+ public function getCascade() {
+ return $this->plugin_cascade;
+ }
+
protected function _populateMasterList() {
global $conf;
@@ -169,6 +204,13 @@ class Doku_Plugin_Controller {
}
}
+ /**
+ * Includes the plugin config $files
+ * and returns the entries of the $plugins array set in these files
+ *
+ * @param array $files list of files to include, latter overrides previous
+ * @return array with entries of the $plugins arrays of the included files
+ */
protected function checkRequire($files) {
$plugins = array();
foreach($files as $file) {
@@ -179,14 +221,15 @@ class Doku_Plugin_Controller {
return $plugins;
}
- function getCascade() {
- return $this->plugin_cascade;
- }
-
/**
* Save the current list of plugins
+ *
+ * @param bool $forceSave;
+ * false to save only when config changed
+ * true to always save
+ * @return bool; true saving succeed, false saving failed
*/
- function saveList($forceSave = false) {
+ protected function saveList($forceSave = false) {
global $conf;
if (empty($this->tmp_plugins)) return false;
@@ -216,9 +259,10 @@ class Doku_Plugin_Controller {
/**
* Rebuild the set of local plugins
+ *
* @return array array of plugins to be saved in end($config_cascade['plugins']['local'])
*/
- function rebuildLocal() {
+ protected function rebuildLocal() {
//assign to local variable to avoid overwriting
$backup = $this->tmp_plugins;
//Can't do anything about protected one so rule them out completely
@@ -238,7 +282,7 @@ class Doku_Plugin_Controller {
* Build the list of plugins and cascade
*
*/
- function loadConfig() {
+ protected function loadConfig() {
global $config_cascade;
foreach(array('default','protected') as $type) {
if(array_key_exists($type,$config_cascade['plugins']))
@@ -253,7 +297,18 @@ class Doku_Plugin_Controller {
$this->tmp_plugins = array_merge($this->plugin_cascade['default'],$this->plugin_cascade['local'],$this->plugin_cascade['protected']);
}
- function _getListByType($type, $enabled) {
+ /**
+ * Returns a list of available plugin components of given type
+ *
+ * @param string $type, plugin_type name;
+ * the type of plugin to return,
+ * @param bool $enabled;
+ * true to return enabled plugins,
+ * false to return disabled plugins
+ *
+ * @return array of plugin components of requested type
+ */
+ protected function _getListByType($type, $enabled) {
$master_list = $enabled ? array_keys(array_filter($this->tmp_plugins)) : array_keys(array_filter($this->tmp_plugins,array($this,'negate')));
$plugins = array();
@@ -278,14 +333,29 @@ class Doku_Plugin_Controller {
return $plugins;
}
- function _splitName($name) {
+ /**
+ * Split name in a plugin name and a component name
+ *
+ * @param string $name
+ * @return array with
+ * - plugin name
+ * - and component name when available, otherwise empty string
+ */
+ protected function _splitName($name) {
if (array_search($name, array_keys($this->tmp_plugins)) === false) {
return explode('_',$name,2);
}
return array($name,'');
}
- function negate($input) {
+
+ /**
+ * Returns inverse boolean value of the input
+ *
+ * @param mixed $input
+ * @return bool inversed boolean value of input
+ */
+ protected function negate($input) {
return !(bool) $input;
}
}
diff --git a/inc/pluginutils.php b/inc/pluginutils.php
index 7c37d4f7ffefbff48d2aae99ed87cef67e22b961..894bbefb6c7512effc89cc86a3b62e574326866f 100644
--- a/inc/pluginutils.php
+++ b/inc/pluginutils.php
@@ -14,31 +14,92 @@ if(!defined('DOKU_PLUGIN_NAME_REGEX')) define('DOKU_PLUGIN_NAME_REGEX', '[a-zA-Z
/**
* Original plugin functions, remain for backwards compatibility
*/
+
+/**
+ * Return list of available plugins
+ *
+ * @param string $type type of plugins; empty string for all
+ * @param bool $all; true to retrieve all, false to retrieve only enabled plugins
+ * @return array with plugin names or plugin component names
+ */
function plugin_list($type='',$all=false) {
+ /** @var $plugin_controller Doku_Plugin_Controller */
global $plugin_controller;
return $plugin_controller->getList($type,$all);
}
+
+/**
+ * Returns plugin object
+ * Returns only new instances of a plugin when $new is true or if plugin is not Singleton,
+ * otherwise an already loaded instance.
+ *
+ * @param $type string type of plugin to load
+ * @param $name string name of the plugin to load
+ * @param $new bool true to return a new instance of the plugin, false to use an already loaded instance
+ * @param $disabled bool true to load even disabled plugins
+ * @return DokuWiki_Plugin|DokuWiki_Syntax_Plugin|null the plugin object or null on failure
+ */
function plugin_load($type,$name,$new=false,$disabled=false) {
+ /** @var $plugin_controller Doku_Plugin_Controller */
global $plugin_controller;
return $plugin_controller->load($type,$name,$new,$disabled);
}
+
+/**
+ * Whether plugin is disabled
+ *
+ * @param string $plugin name of plugin
+ * @return bool; true disabled, false enabled
+ */
function plugin_isdisabled($plugin) {
+ /** @var $plugin_controller Doku_Plugin_Controller */
global $plugin_controller;
return $plugin_controller->isdisabled($plugin);
}
+
+/**
+ * Enable the plugin
+ *
+ * @param string $plugin name of plugin
+ * @return bool; true saving succeed, false saving failed
+ */
function plugin_enable($plugin) {
+ /** @var $plugin_controller Doku_Plugin_Controller */
global $plugin_controller;
return $plugin_controller->enable($plugin);
}
+
+/**
+ * Disable the plugin
+ *
+ * @param string $plugin name of plugin
+ * @return bool; true saving succeed, false saving failed
+ */
function plugin_disable($plugin) {
+ /** @var $plugin_controller Doku_Plugin_Controller */
global $plugin_controller;
return $plugin_controller->disable($plugin);
}
+
+/**
+ * Returns directory name of plugin
+ *
+ * @param string $plugin name of plugin
+ * @return string name of directory
+ */
function plugin_directory($plugin) {
+ /** @var $plugin_controller Doku_Plugin_Controller */
global $plugin_controller;
return $plugin_controller->get_directory($plugin);
}
+
+/**
+ * Returns cascade of the config files
+ *
+ * @return array with arrays of plugin configs
+ */
function plugin_getcascade() {
+ /** @var $plugin_controller Doku_Plugin_Controller */
global $plugin_controller;
return $plugin_controller->getCascade();
}
diff --git a/inc/search.php b/inc/search.php
index 884aa7b237ecfbbbe1d9cfd46b6e4e532bb61161..cd36feeab3593a2474ce5108cfebbd053608508e 100644
--- a/inc/search.php
+++ b/inc/search.php
@@ -9,14 +9,15 @@
if(!defined('DOKU_INC')) die('meh.');
/**
- * recurse direcory
+ * Recurse directory
*
* This function recurses into a given base directory
* and calls the supplied function for each file and directory
*
- * @param array ref $data The results of the search are stored here
+ * @param array &$data The results of the search are stored here
* @param string $base Where to start the search
* @param callback $func Callback (function name or array with object,method)
+ * @param array $opts option array will be given to the Callback
* @param string $dir Current directory beyond $base
* @param int $lvl Recursion Level
* @param mixed $sort 'natural' to use natural order sorting (default); 'date' to sort by filemtime; leave empty to skip sorting.
@@ -68,12 +69,12 @@ function search(&$data,$base,$func,$opts,$dir='',$lvl=1,$sort='natural'){
* decide if this directory should be traversed (true) or not (false)
* The function has to accept the following parameters:
*
- * &$data - Reference to the result data structure
- * $base - Base usually $conf['datadir']
- * $file - current file or directory relative to $base
- * $type - Type either 'd' for directory or 'f' for file
- * $lvl - Current recursion depht
- * $opts - option array as given to search()
+ * array &$data - Reference to the result data structure
+ * string $base - Base usually $conf['datadir']
+ * string $file - current file or directory relative to $base
+ * string $type - Type either 'd' for directory or 'f' for file
+ * int $lvl - Current recursion depht
+ * array $opts - option array as given to search()
*
* return values for files are ignored
*
@@ -334,6 +335,15 @@ function pathID($path,$keeptxt=false){
* showhidden bool show hidden files too
* firsthead bool return first heading for pages
*
+ * @param array &$data - Reference to the result data structure
+ * @param string $base - Base usually $conf['datadir']
+ * @param string $file - current file or directory relative to $base
+ * @param string $type - Type either 'd' for directory or 'f' for file
+ * @param int $lvl - Current recursion depht
+ * @param array $opts - option array as given to search()
+ * @return bool if this directory should be traversed (true) or not (false)
+ * return value is ignored for files
+ *
* @author Andreas Gohr <gohr@cosmocode.de>
*/
function search_universal(&$data,$base,$file,$type,$lvl,$opts){