application/plugin/PluginManager.php

   1 <?php
   2 namespace Shaarli\Plugin;
   3
   4 use Shaarli\Config\ConfigManager;
   5 use Shaarli\Plugin\Exception\PluginFileNotFoundException;
   6
   7 /**
   8  * Class PluginManager
   9  *
  10  * Use to manage, load and execute plugins.
  11  */
  12 class PluginManager
  13 {
  14     /**
  15      * List of authorized plugins from configuration file.
  16      *
  17      * @var array $authorizedPlugins
  18      */
  19     private $authorizedPlugins = [];
  20
  21     /**
  22      * List of loaded plugins.
  23      *
  24      * @var array $loadedPlugins
  25      */
  26     private $loadedPlugins = array();
  27
  28     /**
  29      * @var ConfigManager Configuration Manager instance.
  30      */
  31     protected $conf;
  32
  33     /**
  34      * @var array List of plugin errors.
  35      */
  36     protected $errors;
  37
  38     /**
  39      * Plugins subdirectory.
  40      *
  41      * @var string $PLUGINS_PATH
  42      */
  43     public static $PLUGINS_PATH = 'plugins';
  44
  45     /**
  46      * Plugins meta files extension.
  47      *
  48      * @var string $META_EXT
  49      */
  50     public static $META_EXT = 'meta';
  51
  52     /**
  53      * Constructor.
  54      *
  55      * @param ConfigManager $conf Configuration Manager instance.
  56      */
  57     public function __construct(&$conf)
  58     {
  59         $this->conf = $conf;
  60         $this->errors = array();
  61     }
  62
  63     /**
  64      * Load plugins listed in $authorizedPlugins.
  65      *
  66      * @param array $authorizedPlugins Names of plugin authorized to be loaded.
  67      *
  68      * @return void
  69      */
  70     public function load($authorizedPlugins)
  71     {
  72         $this->authorizedPlugins = $authorizedPlugins;
  73
  74         $dirs = glob(self::$PLUGINS_PATH . '/*', GLOB_ONLYDIR);
  75         $dirnames = array_map('basename', $dirs);
  76         foreach ($this->authorizedPlugins as $plugin) {
  77             $index = array_search($plugin, $dirnames);
  78
  79             // plugin authorized, but its folder isn't listed
  80             if ($index === false) {
  81                 continue;
  82             }
  83
  84             try {
  85                 $this->loadPlugin($dirs[$index], $plugin);
  86             } catch (PluginFileNotFoundException $e) {
  87                 error_log($e->getMessage());
  88             }
  89         }
  90     }
  91
  92     /**
  93      * Execute all plugins registered hook.
  94      *
  95      * @param string $hook   name of the hook to trigger.
  96      * @param array  $data   list of data to manipulate passed by reference.
  97      * @param array  $params additional parameters such as page target.
  98      *
  99      * @return void
 100      */
 101     public function executeHooks($hook, &$data, $params = array())
 102     {
 103         $metadataParameters = [
 104             'target' => '_PAGE_',
 105             'loggedin' => '_LOGGEDIN_',
 106             'basePath' => '_BASE_PATH_',
 107             'bookmarkService' => '_BOOKMARK_SERVICE_',
 108         ];
 109
 110         foreach ($metadataParameters as $parameter => $metaKey) {
 111             if (array_key_exists($parameter, $params)) {
 112                 $data[$metaKey] = $params[$parameter];
 113             }
 114         }
 115
 116         foreach ($this->loadedPlugins as $plugin) {
 117             $hookFunction = $this->buildHookName($hook, $plugin);
 118
 119             if (function_exists($hookFunction)) {
 120                 try {
 121                     $data = call_user_func($hookFunction, $data, $this->conf);
 122                 } catch (\Throwable $e) {
 123                     $error = $plugin . t(' [plugin incompatibility]: ') . $e->getMessage();
 124                     $this->errors = array_unique(array_merge($this->errors, [$error]));
 125                 }
 126             }
 127         }
 128
 129         foreach ($metadataParameters as $metaKey) {
 130             unset($data[$metaKey]);
 131         }
 132     }
 133
 134     /**
 135      * Load a single plugin from its files.
 136      * Call the init function if it exists, and collect errors.
 137      * Add them in $loadedPlugins if successful.
 138      *
 139      * @param string $dir        plugin's directory.
 140      * @param string $pluginName plugin's name.
 141      *
 142      * @return void
 143      * @throws \Shaarli\Plugin\Exception\PluginFileNotFoundException - plugin files not found.
 144      */
 145     private function loadPlugin($dir, $pluginName)
 146     {
 147         if (!is_dir($dir)) {
 148             throw new PluginFileNotFoundException($pluginName);
 149         }
 150
 151         $pluginFilePath = $dir . '/' . $pluginName . '.php';
 152         if (!is_file($pluginFilePath)) {
 153             throw new PluginFileNotFoundException($pluginName);
 154         }
 155
 156         $conf = $this->conf;
 157         include_once $pluginFilePath;
 158
 159         $initFunction = $pluginName . '_init';
 160         if (function_exists($initFunction)) {
 161             $errors = call_user_func($initFunction, $this->conf);
 162             if (!empty($errors)) {
 163                 $this->errors = array_merge($this->errors, $errors);
 164             }
 165         }
 166
 167         $this->loadedPlugins[] = $pluginName;
 168     }
 169
 170     /**
 171      * Construct normalize hook name for a specific plugin.
 172      *
 173      * Format:
 174      *      hook_<plugin_name>_<hook_name>
 175      *
 176      * @param string $hook       hook name.
 177      * @param string $pluginName plugin name.
 178      *
 179      * @return string - plugin's hook name.
 180      */
 181     public function buildHookName($hook, $pluginName)
 182     {
 183         return 'hook_' . $pluginName . '_' . $hook;
 184     }
 185
 186     /**
 187      * Retrieve plugins metadata from *.meta (INI) files into an array.
 188      * Metadata contains:
 189      *   - plugin description [description]
 190      *   - parameters split with ';' [parameters]
 191      *
 192      * Respects plugins order from settings.
 193      *
 194      * @return array plugins metadata.
 195      */
 196     public function getPluginsMeta()
 197     {
 198         $metaData = array();
 199         $dirs = glob(self::$PLUGINS_PATH . '/*', GLOB_ONLYDIR | GLOB_MARK);
 200
 201         // Browse all plugin directories.
 202         foreach ($dirs as $pluginDir) {
 203             $plugin = basename($pluginDir);
 204             $metaFile = $pluginDir . $plugin . '.' . self::$META_EXT;
 205             if (!is_file($metaFile) || !is_readable($metaFile)) {
 206                 continue;
 207             }
 208
 209             $metaData[$plugin] = parse_ini_file($metaFile);
 210             $metaData[$plugin]['order'] = array_search($plugin, $this->authorizedPlugins);
 211
 212             if (isset($metaData[$plugin]['description'])) {
 213                 $metaData[$plugin]['description'] = t($metaData[$plugin]['description']);
 214             }
 215             // Read parameters and format them into an array.
 216             if (isset($metaData[$plugin]['parameters'])) {
 217                 $params = explode(';', $metaData[$plugin]['parameters']);
 218             } else {
 219                 $params = array();
 220             }
 221             $metaData[$plugin]['parameters'] = array();
 222             foreach ($params as $param) {
 223                 if (empty($param)) {
 224                     continue;
 225                 }
 226
 227                 $metaData[$plugin]['parameters'][$param]['value'] = '';
 228                 // Optional parameter description in parameter.PARAM_NAME=
 229                 if (isset($metaData[$plugin]['parameter.' . $param])) {
 230                     $metaData[$plugin]['parameters'][$param]['desc'] = t($metaData[$plugin]['parameter.' . $param]);
 231                 }
 232             }
 233         }
 234
 235         return $metaData;
 236     }
 237
 238     /**
 239      * Return the list of encountered errors.
 240      *
 241      * @return array List of errors (empty array if none exists).
 242      */
 243     public function getErrors()
 244     {
 245         return $this->errors;
 246     }
 247 }