| commit | author | age | ||
| cc97ea | 1 | <?php |
| T | 2 | |
| 3 | /* | |
| 4 | +-----------------------------------------------------------------------+ | |
| 5 | | program/include/rcube_plugin_api.php | | |
| 6 | | | | |
| e019f2 | 7 | | This file is part of the Roundcube Webmail client | |
| 3a7dec | 8 | | Copyright (C) 2008-2011, The Roundcube Dev Team | |
| 7fe381 | 9 | | | |
| T | 10 | | Licensed under the GNU General Public License version 3 or | |
| 11 | | any later version with exceptions for skins & plugins. | | |
| 12 | | See the README file for a full license statement. | | |
| cc97ea | 13 | | | |
| T | 14 | | PURPOSE: | |
| 15 | | Plugins repository | | |
| 16 | | | | |
| 17 | +-----------------------------------------------------------------------+ | |
| 18 | | Author: Thomas Bruederli <roundcube@gmail.com> | | |
| 19 | +-----------------------------------------------------------------------+ | |
| 20 | ||
| 1d786c | 21 | $Id$ |
| cc97ea | 22 | |
| T | 23 | */ |
| 24 | ||
| 0c2596 | 25 | // location where plugins are loade from |
| A | 26 | if (!defined('RCMAIL_PLUGINS_DIR')) |
| 27 | define('RCMAIL_PLUGINS_DIR', INSTALL_PATH . 'plugins/'); | |
| 28 | ||
| 29 | ||
| cc97ea | 30 | /** |
| T | 31 | * The plugin loader and global API |
| 32 | * | |
| d062db | 33 | * @package PluginAPI |
| cc97ea | 34 | */ |
| T | 35 | class rcube_plugin_api |
| 36 | { | |
| 37 | static private $instance; | |
| 38 | ||
| 39 | public $dir; | |
| 40 | public $url = 'plugins/'; | |
| 0c2596 | 41 | public $task = ''; |
| cc97ea | 42 | public $output; |
| T | 43 | |
| 44 | public $handlers = array(); | |
| 45 | private $plugins = array(); | |
| 05a631 | 46 | private $tasks = array(); |
| cc97ea | 47 | private $actions = array(); |
| T | 48 | private $actionmap = array(); |
| 49 | private $objectsmap = array(); | |
| 50 | private $template_contents = array(); | |
| a366a3 | 51 | private $active_hook = false; |
| cc97ea | 52 | |
| e6ce00 | 53 | // Deprecated names of hooks, will be removed after 0.5-stable release |
| A | 54 | private $deprecated_hooks = array( |
| 55 | 'create_user' => 'user_create', | |
| 56 | 'kill_session' => 'session_destroy', | |
| 57 | 'upload_attachment' => 'attachment_upload', | |
| 58 | 'save_attachment' => 'attachment_save', | |
| 59 | 'get_attachment' => 'attachment_get', | |
| 60 | 'cleanup_attachments' => 'attachments_cleanup', | |
| 61 | 'display_attachment' => 'attachment_display', | |
| 62 | 'remove_attachment' => 'attachment_delete', | |
| 63 | 'outgoing_message_headers' => 'message_outgoing_headers', | |
| 64 | 'outgoing_message_body' => 'message_outgoing_body', | |
| 65 | 'address_sources' => 'addressbooks_list', | |
| 66 | 'get_address_book' => 'addressbook_get', | |
| 67 | 'create_contact' => 'contact_create', | |
| 119ad1 | 68 | 'save_contact' => 'contact_update', |
| A | 69 | 'contact_save' => 'contact_update', |
| e6ce00 | 70 | 'delete_contact' => 'contact_delete', |
| A | 71 | 'manage_folders' => 'folders_list', |
| 72 | 'list_mailboxes' => 'mailboxes_list', | |
| 73 | 'save_preferences' => 'preferences_save', | |
| 74 | 'user_preferences' => 'preferences_list', | |
| 75 | 'list_prefs_sections' => 'preferences_sections_list', | |
| 76 | 'list_identities' => 'identities_list', | |
| 77 | 'create_identity' => 'identity_create', | |
| 119ad1 | 78 | 'delete_identity' => 'identity_delete', |
| A | 79 | 'save_identity' => 'identity_update', |
| 80 | 'identity_save' => 'identity_update', | |
| b3ad48 | 81 | // to be removed after 0.8 |
| a2c495 | 82 | 'imap_init' => 'storage_init', |
| b3ad48 | 83 | 'mailboxes_list' => 'storage_folders', |
| e6ce00 | 84 | ); |
| A | 85 | |
| cc97ea | 86 | /** |
| T | 87 | * This implements the 'singleton' design pattern |
| 88 | * | |
| 5c461b | 89 | * @return rcube_plugin_api The one and only instance if this class |
| cc97ea | 90 | */ |
| T | 91 | static function get_instance() |
| 92 | { | |
| 93 | if (!self::$instance) { | |
| 94 | self::$instance = new rcube_plugin_api(); | |
| 95 | } | |
| 96 | ||
| 97 | return self::$instance; | |
| 98 | } | |
| 8ec1b9 | 99 | |
| A | 100 | |
| cc97ea | 101 | /** |
| T | 102 | * Private constructor |
| 103 | */ | |
| 104 | private function __construct() | |
| 105 | { | |
| 0c2596 | 106 | $this->dir = slashify(RCMAIL_PLUGINS_DIR); |
| A | 107 | } |
| 108 | ||
| 109 | ||
| 110 | /** | |
| 111 | * Initialize plugin engine | |
| 112 | * | |
| 113 | * This has to be done after rcmail::load_gui() or rcmail::json_init() | |
| 114 | * was called because plugins need to have access to rcmail->output | |
| 115 | * | |
| 116 | * @param object rcube Instance of the rcube base class | |
| 117 | * @param string Current application task (used for conditional plugin loading) | |
| 118 | */ | |
| 119 | public function init($app, $task = '') | |
| 120 | { | |
| 121 | $this->task = $task; | |
| 122 | $this->output = $app->output; | |
| 123 | ||
| 124 | // register an internal hook | |
| 125 | $this->register_hook('template_container', array($this, 'template_container_hook')); | |
| 126 | ||
| 127 | // maybe also register a shudown function which triggers shutdown functions of all plugin objects | |
| cc97ea | 128 | } |
| 8ec1b9 | 129 | |
| A | 130 | |
| cc97ea | 131 | /** |
| T | 132 | * Load and init all enabled plugins |
| 133 | * | |
| 929a50 | 134 | * This has to be done after rcmail::load_gui() or rcmail::json_init() |
| cc97ea | 135 | * was called because plugins need to have access to rcmail->output |
| 0c2596 | 136 | * |
| A | 137 | * @param array List of configured plugins to load |
| 138 | * @param array List of plugins required by the application | |
| cc97ea | 139 | */ |
| 0c2596 | 140 | public function load_plugins($plugins_enabled, $required_plugins = array()) |
| cc97ea | 141 | { |
| T | 142 | foreach ($plugins_enabled as $plugin_name) { |
| 0501b6 | 143 | $this->load_plugin($plugin_name); |
| cc97ea | 144 | } |
| 8ec1b9 | 145 | |
| cc97ea | 146 | // check existance of all required core plugins |
| 0c2596 | 147 | foreach ($required_plugins as $plugin_name) { |
| cc97ea | 148 | $loaded = false; |
| T | 149 | foreach ($this->plugins as $plugin) { |
| 150 | if ($plugin instanceof $plugin_name) { | |
| 151 | $loaded = true; | |
| 152 | break; | |
| 153 | } | |
| 154 | } | |
| 8ec1b9 | 155 | |
| cc97ea | 156 | // load required core plugin if no derivate was found |
| 0501b6 | 157 | if (!$loaded) |
| T | 158 | $loaded = $this->load_plugin($plugin_name); |
| d5d968 | 159 | |
| cc97ea | 160 | // trigger fatal error if still not loaded |
| T | 161 | if (!$loaded) { |
| 0c2596 | 162 | rcube::raise_error(array('code' => 520, 'type' => 'php', |
| 0501b6 | 163 | 'file' => __FILE__, 'line' => __LINE__, |
| T | 164 | 'message' => "Requried plugin $plugin_name was not loaded"), true, true); |
| cc97ea | 165 | } |
| T | 166 | } |
| 167 | } | |
| 0501b6 | 168 | |
| T | 169 | /** |
| 170 | * Load the specified plugin | |
| 171 | * | |
| 172 | * @param string Plugin name | |
| 173 | * @return boolean True on success, false if not loaded or failure | |
| 174 | */ | |
| 175 | public function load_plugin($plugin_name) | |
| 176 | { | |
| 177 | static $plugins_dir; | |
| 8ec1b9 | 178 | |
| 0501b6 | 179 | if (!$plugins_dir) { |
| T | 180 | $dir = dir($this->dir); |
| 181 | $plugins_dir = unslashify($dir->path); | |
| 182 | } | |
| 8ec1b9 | 183 | |
| 0501b6 | 184 | // plugin already loaded |
| T | 185 | if ($this->plugins[$plugin_name] || class_exists($plugin_name, false)) |
| 186 | return true; | |
| 8ec1b9 | 187 | |
| 0501b6 | 188 | $fn = $plugins_dir . DIRECTORY_SEPARATOR . $plugin_name . DIRECTORY_SEPARATOR . $plugin_name . '.php'; |
| T | 189 | |
| 190 | if (file_exists($fn)) { | |
| 191 | include($fn); | |
| 192 | ||
| 193 | // instantiate class if exists | |
| 194 | if (class_exists($plugin_name, false)) { | |
| 195 | $plugin = new $plugin_name($this); | |
| 196 | // check inheritance... | |
| 197 | if (is_subclass_of($plugin, 'rcube_plugin')) { | |
| 198 | // ... task, request type and framed mode | |
| 0c2596 | 199 | if ((!$plugin->task || preg_match('/^('.$plugin->task.')$/i', $this->task)) |
| A | 200 | && (!$plugin->noajax || (is_object($this->output) && $this->output->type == 'html')) |
| 8ec1b9 | 201 | && (!$plugin->noframe || empty($_REQUEST['_framed'])) |
| 0501b6 | 202 | ) { |
| T | 203 | $plugin->init(); |
| 204 | $this->plugins[$plugin_name] = $plugin; | |
| 205 | } | |
| 206 | return true; | |
| 207 | } | |
| 208 | } | |
| 209 | else { | |
| 0c2596 | 210 | rcube::raise_error(array('code' => 520, 'type' => 'php', |
| 0501b6 | 211 | 'file' => __FILE__, 'line' => __LINE__, |
| T | 212 | 'message' => "No plugin class $plugin_name found in $fn"), true, false); |
| 213 | } | |
| 214 | } | |
| 215 | else { | |
| 0c2596 | 216 | rcube::raise_error(array('code' => 520, 'type' => 'php', |
| 0501b6 | 217 | 'file' => __FILE__, 'line' => __LINE__, |
| T | 218 | 'message' => "Failed to load plugin file $fn"), true, false); |
| 219 | } | |
| 8ec1b9 | 220 | |
| 0501b6 | 221 | return false; |
| T | 222 | } |
| 8ec1b9 | 223 | |
| A | 224 | |
| cc97ea | 225 | /** |
| T | 226 | * Allows a plugin object to register a callback for a certain hook |
| 227 | * | |
| 5c461b | 228 | * @param string $hook Hook name |
| A | 229 | * @param mixed $callback String with global function name or array($obj, 'methodname') |
| cc97ea | 230 | */ |
| T | 231 | public function register_hook($hook, $callback) |
| 232 | { | |
| e6ce00 | 233 | if (is_callable($callback)) { |
| A | 234 | if (isset($this->deprecated_hooks[$hook])) { |
| 0c2596 | 235 | rcube::raise_error(array('code' => 522, 'type' => 'php', |
| e6ce00 | 236 | 'file' => __FILE__, 'line' => __LINE__, |
| A | 237 | 'message' => "Deprecated hook name. ".$hook.' -> '.$this->deprecated_hooks[$hook]), true, false); |
| 238 | $hook = $this->deprecated_hooks[$hook]; | |
| 239 | } | |
| cc97ea | 240 | $this->handlers[$hook][] = $callback; |
| e6ce00 | 241 | } |
| cc97ea | 242 | else |
| 0c2596 | 243 | rcube::raise_error(array('code' => 521, 'type' => 'php', |
| 10eedb | 244 | 'file' => __FILE__, 'line' => __LINE__, |
| A | 245 | 'message' => "Invalid callback function for $hook"), true, false); |
| cc97ea | 246 | } |
| 8ec1b9 | 247 | |
| 479af9 | 248 | /** |
| A | 249 | * Allow a plugin object to unregister a callback. |
| 250 | * | |
| 251 | * @param string $hook Hook name | |
| 252 | * @param mixed $callback String with global function name or array($obj, 'methodname') | |
| 253 | */ | |
| 254 | public function unregister_hook($hook, $callback) | |
| 255 | { | |
| 256 | $callback_id = array_search($callback, $this->handlers[$hook]); | |
| 257 | if ($callback_id !== false) { | |
| 258 | unset($this->handlers[$hook][$callback_id]); | |
| 259 | } | |
| 260 | } | |
| 261 | ||
| 8ec1b9 | 262 | |
| cc97ea | 263 | /** |
| T | 264 | * Triggers a plugin hook. |
| 265 | * This is called from the application and executes all registered handlers | |
| 266 | * | |
| 5c461b | 267 | * @param string $hook Hook name |
| A | 268 | * @param array $args Named arguments (key->value pairs) |
| cc97ea | 269 | * @return array The (probably) altered hook arguments |
| T | 270 | */ |
| 271 | public function exec_hook($hook, $args = array()) | |
| 272 | { | |
| 463a03 | 273 | if (!is_array($args)) |
| A | 274 | $args = array('arg' => $args); |
| 275 | ||
| cc97ea | 276 | $args += array('abort' => false); |
| a366a3 | 277 | $this->active_hook = $hook; |
| 8ec1b9 | 278 | |
| cc97ea | 279 | foreach ((array)$this->handlers[$hook] as $callback) { |
| T | 280 | $ret = call_user_func($callback, $args); |
| 281 | if ($ret && is_array($ret)) | |
| 282 | $args = $ret + $args; | |
| 8ec1b9 | 283 | |
| cc97ea | 284 | if ($args['abort']) |
| T | 285 | break; |
| 286 | } | |
| 8ec1b9 | 287 | |
| a366a3 | 288 | $this->active_hook = false; |
| cc97ea | 289 | return $args; |
| T | 290 | } |
| 291 | ||
| 292 | ||
| 293 | /** | |
| 294 | * Let a plugin register a handler for a specific request | |
| 295 | * | |
| 5c461b | 296 | * @param string $action Action name (_task=mail&_action=plugin.foo) |
| A | 297 | * @param string $owner Plugin name that registers this action |
| 298 | * @param mixed $callback Callback: string with global function name or array($obj, 'methodname') | |
| 299 | * @param string $task Task name registered by this plugin | |
| cc97ea | 300 | */ |
| 05a631 | 301 | public function register_action($action, $owner, $callback, $task = null) |
| cc97ea | 302 | { |
| T | 303 | // check action name |
| 05a631 | 304 | if ($task) |
| T | 305 | $action = $task.'.'.$action; |
| 306 | else if (strpos($action, 'plugin.') !== 0) | |
| cc97ea | 307 | $action = 'plugin.'.$action; |
| 2cd443 | 308 | |
| cc97ea | 309 | // can register action only if it's not taken or registered by myself |
| T | 310 | if (!isset($this->actionmap[$action]) || $this->actionmap[$action] == $owner) { |
| 311 | $this->actions[$action] = $callback; | |
| 312 | $this->actionmap[$action] = $owner; | |
| 313 | } | |
| 314 | else { | |
| 0c2596 | 315 | rcube::raise_error(array('code' => 523, 'type' => 'php', |
| 10eedb | 316 | 'file' => __FILE__, 'line' => __LINE__, |
| A | 317 | 'message' => "Cannot register action $action; already taken by another plugin"), true, false); |
| cc97ea | 318 | } |
| T | 319 | } |
| 320 | ||
| 321 | ||
| 322 | /** | |
| 323 | * This method handles requests like _task=mail&_action=plugin.foo | |
| 324 | * It executes the callback function that was registered with the given action. | |
| 325 | * | |
| 5c461b | 326 | * @param string $action Action name |
| cc97ea | 327 | */ |
| T | 328 | public function exec_action($action) |
| 329 | { | |
| 330 | if (isset($this->actions[$action])) { | |
| 331 | call_user_func($this->actions[$action]); | |
| 332 | } | |
| 333 | else { | |
| 0c2596 | 334 | rcube::raise_error(array('code' => 524, 'type' => 'php', |
| 10eedb | 335 | 'file' => __FILE__, 'line' => __LINE__, |
| A | 336 | 'message' => "No handler found for action $action"), true, true); |
| cc97ea | 337 | } |
| T | 338 | } |
| 339 | ||
| 340 | ||
| 341 | /** | |
| 342 | * Register a handler function for template objects | |
| 343 | * | |
| 5c461b | 344 | * @param string $name Object name |
| A | 345 | * @param string $owner Plugin name that registers this action |
| 346 | * @param mixed $callback Callback: string with global function name or array($obj, 'methodname') | |
| cc97ea | 347 | */ |
| T | 348 | public function register_handler($name, $owner, $callback) |
| 349 | { | |
| 350 | // check name | |
| 351 | if (strpos($name, 'plugin.') !== 0) | |
| 352 | $name = 'plugin.'.$name; | |
| 8ec1b9 | 353 | |
| cc97ea | 354 | // can register handler only if it's not taken or registered by myself |
| 0c2596 | 355 | if (is_object($this->output) && (!isset($this->objectsmap[$name]) || $this->objectsmap[$name] == $owner)) { |
| cc97ea | 356 | $this->output->add_handler($name, $callback); |
| T | 357 | $this->objectsmap[$name] = $owner; |
| 358 | } | |
| 359 | else { | |
| 0c2596 | 360 | rcube::raise_error(array('code' => 525, 'type' => 'php', |
| 10eedb | 361 | 'file' => __FILE__, 'line' => __LINE__, |
| 0c2596 | 362 | 'message' => "Cannot register template handler $name; already taken by another plugin or no output object available"), true, false); |
| cc97ea | 363 | } |
| T | 364 | } |
| 8ec1b9 | 365 | |
| A | 366 | |
| a366a3 | 367 | /** |
| 05a631 | 368 | * Register this plugin to be responsible for a specific task |
| T | 369 | * |
| 5c461b | 370 | * @param string $task Task name (only characters [a-z0-9_.-] are allowed) |
| A | 371 | * @param string $owner Plugin name that registers this action |
| 05a631 | 372 | */ |
| T | 373 | public function register_task($task, $owner) |
| 374 | { | |
| 375 | if ($task != asciiwords($task)) { | |
| 0c2596 | 376 | rcube::raise_error(array('code' => 526, 'type' => 'php', |
| 05a631 | 377 | 'file' => __FILE__, 'line' => __LINE__, |
| T | 378 | 'message' => "Invalid task name: $task. Only characters [a-z0-9_.-] are allowed"), true, false); |
| 379 | } | |
| 380 | else if (in_array($task, rcmail::$main_tasks)) { | |
| 0c2596 | 381 | rcube::raise_error(array('code' => 526, 'type' => 'php', |
| 05a631 | 382 | 'file' => __FILE__, 'line' => __LINE__, |
| T | 383 | 'message' => "Cannot register taks $task; already taken by another plugin or the application itself"), true, false); |
| 384 | } | |
| 385 | else { | |
| 386 | $this->tasks[$task] = $owner; | |
| 387 | rcmail::$main_tasks[] = $task; | |
| 388 | return true; | |
| 389 | } | |
| 8ec1b9 | 390 | |
| 05a631 | 391 | return false; |
| T | 392 | } |
| 393 | ||
| 394 | ||
| 395 | /** | |
| 396 | * Checks whether the given task is registered by a plugin | |
| 397 | * | |
| 5c461b | 398 | * @param string $task Task name |
| 05a631 | 399 | * @return boolean True if registered, otherwise false |
| T | 400 | */ |
| 401 | public function is_plugin_task($task) | |
| 402 | { | |
| 403 | return $this->tasks[$task] ? true : false; | |
| 404 | } | |
| 405 | ||
| 406 | ||
| 407 | /** | |
| a366a3 | 408 | * Check if a plugin hook is currently processing. |
| T | 409 | * Mainly used to prevent loops and recursion. |
| 410 | * | |
| 5c461b | 411 | * @param string $hook Hook to check (optional) |
| a366a3 | 412 | * @return boolean True if any/the given hook is currently processed, otherwise false |
| T | 413 | */ |
| 414 | public function is_processing($hook = null) | |
| 415 | { | |
| 416 | return $this->active_hook && (!$hook || $this->active_hook == $hook); | |
| 417 | } | |
| 8ec1b9 | 418 | |
| cc97ea | 419 | /** |
| T | 420 | * Include a plugin script file in the current HTML page |
| 5c461b | 421 | * |
| A | 422 | * @param string $fn Path to script |
| cc97ea | 423 | */ |
| T | 424 | public function include_script($fn) |
| 425 | { | |
| 0c2596 | 426 | if (is_object($this->output) && $this->output->type == 'html') { |
| eb6f19 | 427 | $src = $this->resource_url($fn); |
| cc97ea | 428 | $this->output->add_header(html::tag('script', array('type' => "text/javascript", 'src' => $src))); |
| T | 429 | } |
| 430 | } | |
| 431 | ||
| 8ec1b9 | 432 | |
| cc97ea | 433 | /** |
| T | 434 | * Include a plugin stylesheet in the current HTML page |
| 5c461b | 435 | * |
| A | 436 | * @param string $fn Path to stylesheet |
| cc97ea | 437 | */ |
| T | 438 | public function include_stylesheet($fn) |
| 439 | { | |
| 0c2596 | 440 | if (is_object($this->output) && $this->output->type == 'html') { |
| eb6f19 | 441 | $src = $this->resource_url($fn); |
| ba3377 | 442 | $this->output->include_css($src); |
| cc97ea | 443 | } |
| T | 444 | } |
| 8ec1b9 | 445 | |
| A | 446 | |
| cc97ea | 447 | /** |
| T | 448 | * Save the given HTML content to be added to a template container |
| 5c461b | 449 | * |
| A | 450 | * @param string $html HTML content |
| 451 | * @param string $container Template container identifier | |
| cc97ea | 452 | */ |
| T | 453 | public function add_content($html, $container) |
| 454 | { | |
| 455 | $this->template_contents[$container] .= $html . "\n"; | |
| 456 | } | |
| 8ec1b9 | 457 | |
| A | 458 | |
| cc97ea | 459 | /** |
| 8703b0 | 460 | * Returns list of loaded plugins names |
| A | 461 | * |
| 462 | * @return array List of plugin names | |
| 463 | */ | |
| 464 | public function loaded_plugins() | |
| 465 | { | |
| 466 | return array_keys($this->plugins); | |
| 467 | } | |
| 468 | ||
| 469 | ||
| 470 | /** | |
| cc97ea | 471 | * Callback for template_container hooks |
| 5c461b | 472 | * |
| A | 473 | * @param array $attrib |
| 474 | * @return array | |
| cc97ea | 475 | */ |
| T | 476 | private function template_container_hook($attrib) |
| 477 | { | |
| 478 | $container = $attrib['name']; | |
| 8448fc | 479 | return array('content' => $attrib['content'] . $this->template_contents[$container]); |
| cc97ea | 480 | } |
| 8ec1b9 | 481 | |
| A | 482 | |
| cc97ea | 483 | /** |
| T | 484 | * Make the given file name link into the plugins directory |
| 5c461b | 485 | * |
| A | 486 | * @param string $fn Filename |
| 487 | * @return string | |
| cc97ea | 488 | */ |
| eb6f19 | 489 | private function resource_url($fn) |
| cc97ea | 490 | { |
| 23a2ee | 491 | if ($fn[0] != '/' && !preg_match('|^https?://|i', $fn)) |
| cc97ea | 492 | return $this->url . $fn; |
| T | 493 | else |
| 494 | return $fn; | |
| 495 | } | |
| 496 | ||
| 497 | } | |
