Roundcubemail devel
view | history | commit | commitdiff
alecpl
2010-09-25 e019f2d0f2dc2fbfa345ab5d7ae85e67bfdd76b8
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                     |
A 8  | Copyright (C) 2008-2009, Roundcube Dev. - Switzerland                 |
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;
34   
35   public $handlers = array();
36   private $plugins = array();
05a631 37   private $tasks = array();
cc97ea 38   private $actions = array();
T 39   private $actionmap = array();
40   private $objectsmap = array();
41   private $template_contents = array();
42   
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    *
79    * @return object rcube_plugin_api The one and only instance if this class
80    */
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;
d5d968 110
cc97ea 111     $plugins_dir = dir($this->dir);
d5d968 112     $plugins_dir = unslashify($plugins_dir->path);
cc97ea 113     $plugins_enabled = (array)$rcmail->config->get('plugins', array());
d5d968 114
cc97ea 115     foreach ($plugins_enabled as $plugin_name) {
d5d968 116       $fn = $plugins_dir . DIRECTORY_SEPARATOR . $plugin_name . DIRECTORY_SEPARATOR . $plugin_name . '.php';
A 117
cc97ea 118       if (file_exists($fn)) {
T 119         include($fn);
d5d968 120
cc97ea 121         // instantiate class if exists
T 122         if (class_exists($plugin_name, false)) {
123           $plugin = new $plugin_name($this);
124           // check inheritance and task specification
9b94eb 125           if (is_subclass_of($plugin, 'rcube_plugin') && (!$plugin->task || preg_match('/^('.$plugin->task.')$/i', $rcmail->task))) {
cc97ea 126             $plugin->init();
T 127             $this->plugins[] = $plugin;
128           }
129         }
130         else {
10eedb 131           raise_error(array('code' => 520, 'type' => 'php',
A 132         'file' => __FILE__, 'line' => __LINE__,
133         'message' => "No plugin class $plugin_name found in $fn"), true, false);
cc97ea 134         }
T 135       }
136       else {
10eedb 137         raise_error(array('code' => 520, 'type' => 'php',
A 138       'file' => __FILE__, 'line' => __LINE__,
139       'message' => "Failed to load plugin file $fn"), true, false);
cc97ea 140       }
T 141     }
142     
143     // check existance of all required core plugins
144     foreach ($this->required_plugins as $plugin_name) {
145       $loaded = false;
146       foreach ($this->plugins as $plugin) {
147         if ($plugin instanceof $plugin_name) {
148           $loaded = true;
149           break;
150         }
151       }
152       
153       // load required core plugin if no derivate was found
154       if (!$loaded) {
d5d968 155         $fn = $plugins_dir . DIRECTORY_SEPARATOR . $plugin_name . DIRECTORY_SEPARATOR . $plugin_name . '.php';
A 156
cc97ea 157         if (file_exists($fn)) {
912bbb 158           include_once($fn);
cc97ea 159           
T 160           if (class_exists($plugin_name, false)) {
161             $plugin = new $plugin_name($this);
162             // check inheritance
163             if (is_subclass_of($plugin, 'rcube_plugin')) {
912bbb 164           if (!$plugin->task || preg_match('/('.$plugin->task.')/i', $rcmail->task)) {
A 165                 $plugin->init();
166                 $this->plugins[] = $plugin;
167               }
168           $loaded = true;
cc97ea 169             }
T 170           }
171         }
172       }
173       
174       // trigger fatal error if still not loaded
175       if (!$loaded) {
10eedb 176         raise_error(array('code' => 520, 'type' => 'php',
A 177       'file' => __FILE__, 'line' => __LINE__,
178       'message' => "Requried plugin $plugin_name was not loaded"), true, true);
cc97ea 179       }
T 180     }
181
182     // register an internal hook
183     $this->register_hook('template_container', array($this, 'template_container_hook'));
184     
185     // maybe also register a shudown function which triggers shutdown functions of all plugin objects
186   }
187   
188   
189   /**
190    * Allows a plugin object to register a callback for a certain hook
191    *
192    * @param string Hook name
193    * @param mixed String with global function name or array($obj, 'methodname')
194    */
195   public function register_hook($hook, $callback)
196   {
e6ce00 197     if (is_callable($callback)) {
A 198       if (isset($this->deprecated_hooks[$hook])) {
199         raise_error(array('code' => 522, 'type' => 'php',
200           'file' => __FILE__, 'line' => __LINE__,
201           'message' => "Deprecated hook name. ".$hook.' -> '.$this->deprecated_hooks[$hook]), true, false);
202         $hook = $this->deprecated_hooks[$hook];
203       }
cc97ea 204       $this->handlers[$hook][] = $callback;
e6ce00 205     }
cc97ea 206     else
10eedb 207       raise_error(array('code' => 521, 'type' => 'php',
A 208         'file' => __FILE__, 'line' => __LINE__,
209         'message' => "Invalid callback function for $hook"), true, false);
cc97ea 210   }
T 211   
212   
213   /**
214    * Triggers a plugin hook.
215    * This is called from the application and executes all registered handlers
216    *
217    * @param string Hook name
218    * @param array Named arguments (key->value pairs)
219    * @return array The (probably) altered hook arguments
220    */
221   public function exec_hook($hook, $args = array())
222   {
463a03 223     if (!is_array($args))
A 224       $args = array('arg' => $args);
225
cc97ea 226     $args += array('abort' => false);
a366a3 227     $this->active_hook = $hook;
cc97ea 228     
T 229     foreach ((array)$this->handlers[$hook] as $callback) {
230       $ret = call_user_func($callback, $args);
231       if ($ret && is_array($ret))
232         $args = $ret + $args;
233       
234       if ($args['abort'])
235         break;
236     }
237     
a366a3 238     $this->active_hook = false;
cc97ea 239     return $args;
T 240   }
241
242
243   /**
244    * Let a plugin register a handler for a specific request
245    *
246    * @param string Action name (_task=mail&_action=plugin.foo)
247    * @param string Plugin name that registers this action
248    * @param mixed Callback: string with global function name or array($obj, 'methodname')
05a631 249    * @param string Task name registered by this plugin
cc97ea 250    */
05a631 251   public function register_action($action, $owner, $callback, $task = null)
cc97ea 252   {
T 253     // check action name
05a631 254     if ($task)
T 255       $action = $task.'.'.$action;
256     else if (strpos($action, 'plugin.') !== 0)
cc97ea 257       $action = 'plugin.'.$action;
T 258     
259     // can register action only if it's not taken or registered by myself
260     if (!isset($this->actionmap[$action]) || $this->actionmap[$action] == $owner) {
261       $this->actions[$action] = $callback;
262       $this->actionmap[$action] = $owner;
263     }
264     else {
10eedb 265       raise_error(array('code' => 523, 'type' => 'php',
A 266         'file' => __FILE__, 'line' => __LINE__,
267         'message' => "Cannot register action $action; already taken by another plugin"), true, false);
cc97ea 268     }
T 269   }
270
271
272   /**
273    * This method handles requests like _task=mail&_action=plugin.foo
274    * It executes the callback function that was registered with the given action.
275    *
276    * @param string Action name
277    */
278   public function exec_action($action)
279   {
280     if (isset($this->actions[$action])) {
281       call_user_func($this->actions[$action]);
282     }
283     else {
10eedb 284       raise_error(array('code' => 524, 'type' => 'php',
A 285         'file' => __FILE__, 'line' => __LINE__,
286         'message' => "No handler found for action $action"), true, true);
cc97ea 287     }
T 288   }
289
290
291   /**
292    * Register a handler function for template objects
293    *
294    * @param string Object name
295    * @param string Plugin name that registers this action
296    * @param mixed Callback: string with global function name or array($obj, 'methodname')
297    */
298   public function register_handler($name, $owner, $callback)
299   {
300     // check name
301     if (strpos($name, 'plugin.') !== 0)
302       $name = 'plugin.'.$name;
303     
304     // can register handler only if it's not taken or registered by myself
305     if (!isset($this->objectsmap[$name]) || $this->objectsmap[$name] == $owner) {
306       $this->output->add_handler($name, $callback);
307       $this->objectsmap[$name] = $owner;
308     }
309     else {
10eedb 310       raise_error(array('code' => 525, 'type' => 'php',
A 311         'file' => __FILE__, 'line' => __LINE__,
312         'message' => "Cannot register template handler $name; already taken by another plugin"), true, false);
cc97ea 313     }
T 314   }
315   
a366a3 316   
T 317   /**
05a631 318    * Register this plugin to be responsible for a specific task
T 319    *
320    * @param string Task name (only characters [a-z0-9_.-] are allowed)
321    * @param string Plugin name that registers this action
322    */
323   public function register_task($task, $owner)
324   {
325     if ($task != asciiwords($task)) {
326       raise_error(array('code' => 526, 'type' => 'php',
327         'file' => __FILE__, 'line' => __LINE__,
328         'message' => "Invalid task name: $task. Only characters [a-z0-9_.-] are allowed"), true, false);
329     }
330     else if (in_array($task, rcmail::$main_tasks)) {
331       raise_error(array('code' => 526, 'type' => 'php',
332         'file' => __FILE__, 'line' => __LINE__,
333         'message' => "Cannot register taks $task; already taken by another plugin or the application itself"), true, false);
334     }
335     else {
336       $this->tasks[$task] = $owner;
337       rcmail::$main_tasks[] = $task;
338       return true;
339     }
340     
341     return false;
342   }
343
344
345   /**
346    * Checks whether the given task is registered by a plugin
347    *
348    * @return boolean True if registered, otherwise false
349    */
350   public function is_plugin_task($task)
351   {
352     return $this->tasks[$task] ? true : false;
353   }
354
355
356   /**
a366a3 357    * Check if a plugin hook is currently processing.
T 358    * Mainly used to prevent loops and recursion.
359    *
360    * @param string Hook to check (optional)
361    * @return boolean True if any/the given hook is currently processed, otherwise false
362    */
363   public function is_processing($hook = null)
364   {
365     return $this->active_hook && (!$hook || $this->active_hook == $hook);
366   }
367   
cc97ea 368   /**
T 369    * Include a plugin script file in the current HTML page
370    */
371   public function include_script($fn)
372   {
373     if ($this->output->type == 'html') {
eb6f19 374       $src = $this->resource_url($fn);
cc97ea 375       $this->output->add_header(html::tag('script', array('type' => "text/javascript", 'src' => $src)));
T 376     }
377   }
378
379   /**
380    * Include a plugin stylesheet in the current HTML page
381    */
382   public function include_stylesheet($fn)
383   {
384     if ($this->output->type == 'html') {
eb6f19 385       $src = $this->resource_url($fn);
cc97ea 386       $this->output->add_header(html::tag('link', array('rel' => "stylesheet", 'type' => "text/css", 'href' => $src)));
T 387     }
388   }
389   
390   /**
391    * Save the given HTML content to be added to a template container
392    */
393   public function add_content($html, $container)
394   {
395     $this->template_contents[$container] .= $html . "\n";
396   }
397   
398   /**
399    * Callback for template_container hooks
400    */
401   private function template_container_hook($attrib)
402   {
403     $container = $attrib['name'];
8448fc 404     return array('content' => $attrib['content'] . $this->template_contents[$container]);
cc97ea 405   }
T 406   
407   /**
408    * Make the given file name link into the plugins directory
409    */
eb6f19 410   private function resource_url($fn)
cc97ea 411   {
23a2ee 412     if ($fn[0] != '/' && !preg_match('|^https?://|i', $fn))
cc97ea 413       return $this->url . $fn;
T 414     else
415       return $fn;
416   }
417
418 }
419