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