]>
Commit | Line | Data |
---|---|---|
1 | <?php | |
2 | ||
3 | namespace Shaarli\Plugin; | |
4 | ||
5 | use Shaarli\Bookmark\Bookmark; | |
6 | use Shaarli\Config\ConfigManager; | |
7 | use Shaarli\Plugin\Exception\PluginFileNotFoundException; | |
8 | use Shaarli\Plugin\Exception\PluginInvalidRouteException; | |
9 | ||
10 | /** | |
11 | * Class PluginManager | |
12 | * | |
13 | * Use to manage, load and execute plugins. | |
14 | */ | |
15 | class PluginManager | |
16 | { | |
17 | /** | |
18 | * List of authorized plugins from configuration file. | |
19 | * | |
20 | * @var array $authorizedPlugins | |
21 | */ | |
22 | private $authorizedPlugins = []; | |
23 | ||
24 | /** | |
25 | * List of loaded plugins. | |
26 | * | |
27 | * @var array $loadedPlugins | |
28 | */ | |
29 | private $loadedPlugins = []; | |
30 | ||
31 | /** @var array List of registered routes. Contains keys: | |
32 | * - `method`: HTTP method, GET/POST/PUT/PATCH/DELETE | |
33 | * - `route` (path): without prefix, e.g. `/up/{variable}` | |
34 | * It will be later prefixed by `/plugin/<plugin name>/`. | |
35 | * - `callable` string, function name or FQN class's method, e.g. `demo_plugin_custom_controller`. | |
36 | */ | |
37 | protected $registeredRoutes = []; | |
38 | ||
39 | /** | |
40 | * @var ConfigManager Configuration Manager instance. | |
41 | */ | |
42 | protected $conf; | |
43 | ||
44 | /** | |
45 | * @var array List of plugin errors. | |
46 | */ | |
47 | protected $errors; | |
48 | ||
49 | /** @var callable[]|null Preloaded list of hook function for filterSearchEntry() */ | |
50 | protected $filterSearchEntryHooks = null; | |
51 | ||
52 | /** | |
53 | * Plugins subdirectory. | |
54 | * | |
55 | * @var string $PLUGINS_PATH | |
56 | */ | |
57 | public static $PLUGINS_PATH = 'plugins'; | |
58 | ||
59 | /** | |
60 | * Plugins meta files extension. | |
61 | * | |
62 | * @var string $META_EXT | |
63 | */ | |
64 | public static $META_EXT = 'meta'; | |
65 | ||
66 | /** | |
67 | * Constructor. | |
68 | * | |
69 | * @param ConfigManager $conf Configuration Manager instance. | |
70 | */ | |
71 | public function __construct(&$conf) | |
72 | { | |
73 | $this->conf = $conf; | |
74 | $this->errors = []; | |
75 | } | |
76 | ||
77 | /** | |
78 | * Load plugins listed in $authorizedPlugins. | |
79 | * | |
80 | * @param array $authorizedPlugins Names of plugin authorized to be loaded. | |
81 | * | |
82 | * @return void | |
83 | */ | |
84 | public function load($authorizedPlugins) | |
85 | { | |
86 | $this->authorizedPlugins = $authorizedPlugins; | |
87 | ||
88 | $dirs = glob(self::$PLUGINS_PATH . '/*', GLOB_ONLYDIR); | |
89 | $dirnames = array_map('basename', $dirs); | |
90 | foreach ($this->authorizedPlugins as $plugin) { | |
91 | $index = array_search($plugin, $dirnames); | |
92 | ||
93 | // plugin authorized, but its folder isn't listed | |
94 | if ($index === false) { | |
95 | continue; | |
96 | } | |
97 | ||
98 | try { | |
99 | $this->loadPlugin($dirs[$index], $plugin); | |
100 | } catch (PluginFileNotFoundException $e) { | |
101 | error_log($e->getMessage()); | |
102 | } catch (\Throwable $e) { | |
103 | $error = $plugin . t(' [plugin incompatibility]: ') . $e->getMessage(); | |
104 | $this->errors = array_unique(array_merge($this->errors, [$error])); | |
105 | } | |
106 | } | |
107 | } | |
108 | ||
109 | /** | |
110 | * Execute all plugins registered hook. | |
111 | * | |
112 | * @param string $hook name of the hook to trigger. | |
113 | * @param array $data list of data to manipulate passed by reference. | |
114 | * @param array $params additional parameters such as page target. | |
115 | * | |
116 | * @return void | |
117 | */ | |
118 | public function executeHooks($hook, &$data, $params = []) | |
119 | { | |
120 | $metadataParameters = [ | |
121 | 'target' => '_PAGE_', | |
122 | 'loggedin' => '_LOGGEDIN_', | |
123 | 'basePath' => '_BASE_PATH_', | |
124 | 'rootPath' => '_ROOT_PATH_', | |
125 | 'bookmarkService' => '_BOOKMARK_SERVICE_', | |
126 | ]; | |
127 | ||
128 | foreach ($metadataParameters as $parameter => $metaKey) { | |
129 | if (array_key_exists($parameter, $params)) { | |
130 | $data[$metaKey] = $params[$parameter]; | |
131 | } | |
132 | } | |
133 | ||
134 | foreach ($this->loadedPlugins as $plugin) { | |
135 | $hookFunction = $this->buildHookName($hook, $plugin); | |
136 | ||
137 | if (function_exists($hookFunction)) { | |
138 | try { | |
139 | $data = call_user_func($hookFunction, $data, $this->conf); | |
140 | } catch (\Throwable $e) { | |
141 | $error = $plugin . t(' [plugin incompatibility]: ') . $e->getMessage(); | |
142 | $this->errors = array_unique(array_merge($this->errors, [$error])); | |
143 | } | |
144 | } | |
145 | } | |
146 | ||
147 | foreach ($metadataParameters as $metaKey) { | |
148 | unset($data[$metaKey]); | |
149 | } | |
150 | } | |
151 | ||
152 | /** | |
153 | * Load a single plugin from its files. | |
154 | * Call the init function if it exists, and collect errors. | |
155 | * Add them in $loadedPlugins if successful. | |
156 | * | |
157 | * @param string $dir plugin's directory. | |
158 | * @param string $pluginName plugin's name. | |
159 | * | |
160 | * @return void | |
161 | * @throws \Shaarli\Plugin\Exception\PluginFileNotFoundException - plugin files not found. | |
162 | */ | |
163 | private function loadPlugin($dir, $pluginName) | |
164 | { | |
165 | if (!is_dir($dir)) { | |
166 | throw new PluginFileNotFoundException($pluginName); | |
167 | } | |
168 | ||
169 | $pluginFilePath = $dir . '/' . $pluginName . '.php'; | |
170 | if (!is_file($pluginFilePath)) { | |
171 | throw new PluginFileNotFoundException($pluginName); | |
172 | } | |
173 | ||
174 | $conf = $this->conf; | |
175 | include_once $pluginFilePath; | |
176 | ||
177 | $initFunction = $pluginName . '_init'; | |
178 | if (function_exists($initFunction)) { | |
179 | $errors = call_user_func($initFunction, $this->conf); | |
180 | if (!empty($errors)) { | |
181 | $this->errors = array_merge($this->errors, $errors); | |
182 | } | |
183 | } | |
184 | ||
185 | $registerRouteFunction = $pluginName . '_register_routes'; | |
186 | $routes = null; | |
187 | if (function_exists($registerRouteFunction)) { | |
188 | $routes = call_user_func($registerRouteFunction); | |
189 | } | |
190 | ||
191 | if ($routes !== null) { | |
192 | foreach ($routes as $route) { | |
193 | if (static::validateRouteRegistration($route)) { | |
194 | $this->registeredRoutes[$pluginName][] = $route; | |
195 | } else { | |
196 | throw new PluginInvalidRouteException($pluginName); | |
197 | } | |
198 | } | |
199 | } | |
200 | ||
201 | $this->loadedPlugins[] = $pluginName; | |
202 | } | |
203 | ||
204 | /** | |
205 | * Construct normalize hook name for a specific plugin. | |
206 | * | |
207 | * Format: | |
208 | * hook_<plugin_name>_<hook_name> | |
209 | * | |
210 | * @param string $hook hook name. | |
211 | * @param string $pluginName plugin name. | |
212 | * | |
213 | * @return string - plugin's hook name. | |
214 | */ | |
215 | public function buildHookName($hook, $pluginName) | |
216 | { | |
217 | return 'hook_' . $pluginName . '_' . $hook; | |
218 | } | |
219 | ||
220 | /** | |
221 | * Retrieve plugins metadata from *.meta (INI) files into an array. | |
222 | * Metadata contains: | |
223 | * - plugin description [description] | |
224 | * - parameters split with ';' [parameters] | |
225 | * | |
226 | * Respects plugins order from settings. | |
227 | * | |
228 | * @return array plugins metadata. | |
229 | */ | |
230 | public function getPluginsMeta() | |
231 | { | |
232 | $metaData = []; | |
233 | $dirs = glob(self::$PLUGINS_PATH . '/*', GLOB_ONLYDIR | GLOB_MARK); | |
234 | ||
235 | // Browse all plugin directories. | |
236 | foreach ($dirs as $pluginDir) { | |
237 | $plugin = basename($pluginDir); | |
238 | $metaFile = $pluginDir . $plugin . '.' . self::$META_EXT; | |
239 | if (!is_file($metaFile) || !is_readable($metaFile)) { | |
240 | continue; | |
241 | } | |
242 | ||
243 | $metaData[$plugin] = parse_ini_file($metaFile); | |
244 | $metaData[$plugin]['order'] = array_search($plugin, $this->authorizedPlugins); | |
245 | ||
246 | if (isset($metaData[$plugin]['description'])) { | |
247 | $metaData[$plugin]['description'] = t($metaData[$plugin]['description']); | |
248 | } | |
249 | // Read parameters and format them into an array. | |
250 | if (isset($metaData[$plugin]['parameters'])) { | |
251 | $params = explode(';', $metaData[$plugin]['parameters']); | |
252 | } else { | |
253 | $params = []; | |
254 | } | |
255 | $metaData[$plugin]['parameters'] = []; | |
256 | foreach ($params as $param) { | |
257 | if (empty($param)) { | |
258 | continue; | |
259 | } | |
260 | ||
261 | $metaData[$plugin]['parameters'][$param]['value'] = ''; | |
262 | // Optional parameter description in parameter.PARAM_NAME= | |
263 | if (isset($metaData[$plugin]['parameter.' . $param])) { | |
264 | $metaData[$plugin]['parameters'][$param]['desc'] = t($metaData[$plugin]['parameter.' . $param]); | |
265 | } | |
266 | } | |
267 | } | |
268 | ||
269 | return $metaData; | |
270 | } | |
271 | ||
272 | /** | |
273 | * @return array List of registered custom routes by plugins. | |
274 | */ | |
275 | public function getRegisteredRoutes(): array | |
276 | { | |
277 | return $this->registeredRoutes; | |
278 | } | |
279 | ||
280 | /** | |
281 | * @return array List of registered filter_search_entry hooks | |
282 | */ | |
283 | public function getFilterSearchEntryHooks(): ?array | |
284 | { | |
285 | return $this->filterSearchEntryHooks; | |
286 | } | |
287 | ||
288 | /** | |
289 | * Return the list of encountered errors. | |
290 | * | |
291 | * @return array List of errors (empty array if none exists). | |
292 | */ | |
293 | public function getErrors() | |
294 | { | |
295 | return $this->errors; | |
296 | } | |
297 | ||
298 | /** | |
299 | * Apply additional filter on every search result of BookmarkFilter calling plugins hooks. | |
300 | * | |
301 | * @param Bookmark $bookmark To check. | |
302 | * @param array $context Additional info about search context, depends on the search source. | |
303 | * | |
304 | * @return bool True if the result must be kept in search results, false otherwise. | |
305 | */ | |
306 | public function filterSearchEntry(Bookmark $bookmark, array $context): bool | |
307 | { | |
308 | if ($this->filterSearchEntryHooks === null) { | |
309 | $this->loadFilterSearchEntryHooks(); | |
310 | } | |
311 | ||
312 | if ($this->filterSearchEntryHooks === []) { | |
313 | return true; | |
314 | } | |
315 | ||
316 | foreach ($this->filterSearchEntryHooks as $filterSearchEntryHook) { | |
317 | if ($filterSearchEntryHook($bookmark, $context) === false) { | |
318 | return false; | |
319 | } | |
320 | } | |
321 | ||
322 | return true; | |
323 | } | |
324 | ||
325 | /** | |
326 | * filterSearchEntry() method will be called for every search result, | |
327 | * so for performances we preload existing functions to invoke them directly. | |
328 | */ | |
329 | protected function loadFilterSearchEntryHooks(): void | |
330 | { | |
331 | $this->filterSearchEntryHooks = []; | |
332 | ||
333 | foreach ($this->loadedPlugins as $plugin) { | |
334 | $hookFunction = $this->buildHookName('filter_search_entry', $plugin); | |
335 | ||
336 | if (function_exists($hookFunction)) { | |
337 | $this->filterSearchEntryHooks[] = $hookFunction; | |
338 | } | |
339 | } | |
340 | } | |
341 | ||
342 | /** | |
343 | * Checks whether provided input is valid to register a new route. | |
344 | * It must contain keys `method`, `route`, `callable` (all strings). | |
345 | * | |
346 | * @param string[] $input | |
347 | * | |
348 | * @return bool | |
349 | */ | |
350 | protected static function validateRouteRegistration(array $input): bool | |
351 | { | |
352 | if ( | |
353 | !array_key_exists('method', $input) | |
354 | || !in_array(strtoupper($input['method']), ['GET', 'PUT', 'PATCH', 'POST', 'DELETE']) | |
355 | ) { | |
356 | return false; | |
357 | } | |
358 | ||
359 | if (!array_key_exists('route', $input) || !preg_match('#^[a-z\d/\.\-_]+$#', $input['route'])) { | |
360 | return false; | |
361 | } | |
362 | ||
363 | if (!array_key_exists('callable', $input)) { | |
364 | return false; | |
365 | } | |
366 | ||
367 | return true; | |
368 | } | |
369 | } |