CWIS Developer Documentation
Plugin.php
Go to the documentation of this file.
1 <?PHP
2 #
3 # FILE: PluginManager.php
4 #
5 # Part of the ScoutLib application support library
6 # Copyright 2009-2013 Edward Almasy and Internet Scout Research Group
7 # http://scout.wisc.edu
8 #
9 
13 abstract class Plugin
14 {
15 
16  # ----- PUBLIC INTERFACE -------------------------------------------------
17 
25  public abstract function Register();
26 
38  public function SetUpConfigOptions()
39  {
40  return NULL;
41  }
42 
51  public function Initialize()
52  {
53  return NULL;
54  }
55 
63  public function HookEvents()
64  {
65  return array();
66  }
67 
75  public function DeclareEvents()
76  {
77  return array();
78  }
79 
86  public function Install()
87  {
88  return NULL;
89  }
90 
99  public function Upgrade($PreviousVersion)
100  {
101  return NULL;
102  }
103 
109  public function Uninstall()
110  {
111  return NULL;
112  }
113 
118  public final function GetAttributes()
119  {
120  return array(
121  "Author" => $this->Author,
122  "CfgPage" => $this->CfgPage,
123  "CfgSetup" => $this->CfgSetup,
124  "Description" => $this->Description,
125  "Email" => $this->Email,
126  "EnabledByDefault" => $this->EnabledByDefault,
127  "InitializeAfter" => is_array($this->InitializeAfter)
128  ? $this->InitializeAfter : array($this->InitializeAfter),
129  "InitializeBefore" => is_array($this->InitializeBefore)
130  ? $this->InitializeBefore : array($this->InitializeBefore),
131  "Instructions" => $this->Instructions,
132  "Name" => $this->Name,
133  "Requires" => $this->Requires,
134  "Url" => $this->Url,
135  "Version" => $this->Version,
136  );
137  }
138 
143  public function GetBaseName()
144  {
145  return get_class($this);
146  }
147 
157  public final function ConfigSetting($SettingName, $NewValue = NULL)
158  {
159  # if a new value was supplied for the setting
160  if (func_num_args() > 1)
161  {
162  # if this setting has a filter function specified
163  if (array_key_exists($SettingName, $this->CfgSetup)
164  && array_key_exists("SettingFilter",
165  $this->CfgSetup[$SettingName]))
166  {
167  # pass new value through filter function
168  $FilterMethod = $this->CfgSetup[$SettingName]["SettingFilter"];
169  $NewValue = $this->$FilterMethod($SettingName, $NewValue);
170  }
171 
172  # if caller requested that setting be cleared
173  if ($NewValue === NULL)
174  {
175  # clear setting
176  unset($this->Cfg[$SettingName]);
177  }
178  else
179  {
180  # save new value for setting
181  $this->Cfg[$SettingName] = $NewValue;
182  }
183 
184  # save new configuration settings
185  $DB = new Database();
186  $DB->Query("UPDATE PluginInfo SET Cfg = '"
187  .addslashes(serialize($this->Cfg))
188  ."' WHERE BaseName = '"
189  .addslashes($this->GetBaseName())."'");
190  }
191 
192  # return current value of setting to caller
193  return isset($this->CfgOver[$SettingName]) ? $this->CfgOver[$SettingName]
194  : (isset($this->Cfg[$SettingName]) ? $this->Cfg[$SettingName] : NULL);
195  }
196 
203  public final function GetSavedConfigSetting($SettingName)
204  {
205  # return current saved value of setting to caller
206  return isset($this->Cfg[$SettingName]) ? $this->Cfg[$SettingName] : NULL;
207  }
208 
215  public final function GetConfigSettingType($SettingName)
216  {
217  return isset($this->CfgSetup[$SettingName])
218  ? $this->CfgSetup[$SettingName]["Type"] : NULL;
219  }
220 
228  public final function GetConfigSettingParameters($SettingName)
229  {
230  return isset($this->CfgSetup[$SettingName])
231  ? $this->CfgSetup[$SettingName] : NULL;
232  }
233 
242  public final function ConfigSettingOverride($SettingName, $Value)
243  {
244  # check that setting name was valid
245  if (!isset($this->CfgSetup[$SettingName]))
246  {
247  throw new InvalidArgumentException(
248  "Unknown setting name (".$SettingName.").");
249  }
250 
251  # save override value
252  $this->CfgOver[$SettingName] = $Value;
253  }
254 
261  public function IsReady($NewValue = NULL)
262  {
263  # if new ready status was supplied
264  if ($NewValue !== NULL)
265  {
266  # make sure we are being called from the plugin manager
267  StdLib::CheckMyCaller("PluginManager",
268  "Attempt to update plugin ready status at %FILE%:%LINE%."
269  ." (Plugin ready status can only be set by PluginManager.)");
270 
271  # update plugin ready status
272  $this->Ready = $NewValue ? TRUE : FALSE;
273  }
274 
275  # return current ready status to caller
276  return $this->Ready;
277  }
278 
288  public function IsEnabled($NewValue = NULL, $Persistent = TRUE)
289  {
290  # if new enabled status was suppled
291  if ($NewValue !== NULL)
292  {
293  # save new status locally
294  $this->Enabled = $NewValue ? TRUE : FALSE;
295 
296  # update enabled status in database if appropriate
297  if ($Persistent)
298  {
299  $DB = new Database();
300  $DB->Query("UPDATE PluginInfo"
301  ." SET Enabled = ".($NewValue ? "1" : "0")
302  ." WHERE BaseName = '".addslashes($this->GetBaseName())."'");
303  }
304  }
305 
306  # return current enabled status to caller
307  return $this->Enabled;
308  }
309 
317  public function IsInstalled($NewValue = NULL)
318  {
319  # if new install status was supplied
320  if ($NewValue !== NULL)
321  {
322  # make sure we are being called from the plugin manager
323  StdLib::CheckMyCaller("PluginManager",
324  "Attempt to update plugin install status at %FILE%:%LINE%."
325  ." (Plugin install status can only be set by PluginManager.)");
326 
327  # update installation setting in database
328  $this->Installed = $NewValue ? TRUE : FALSE;
329  $DB = new Database();
330  $DB->Query("UPDATE PluginInfo"
331  ." SET Installed = ".($NewValue ? "1" : "0")
332  ." WHERE BaseName = '".addslashes($this->GetBaseName())."'");
333  }
334 
335  # return installed status to caller
336  return $this->Installed;
337  }
338 
345  public function InstalledVersion($NewValue = NULL)
346  {
347  # if new version was supplied
348  if ($NewValue !== NULL)
349  {
350  # make sure we are being called from the plugin manager
351  StdLib::CheckMyCaller("PluginManager",
352  "Attempt to set installed version of plugin at %FILE%:%LINE%."
353  ." (Plugin installed version can only be set by PluginManager.)");
354 
355  # update version in database
356  $this->InstalledVersion = $NewValue;
357  $DB = new Database();
358  $DB->Query("UPDATE PluginInfo"
359  ." SET Version = '".addslashes($NewValue)."'"
360  ." WHERE BaseName = '".addslashes($this->GetBaseName())."'");
361  }
362 
363  # return current installed version to caller
364  return $this->InstalledVersion;
365  }
366 
371  public function GetName()
372  {
373  return $this->Name;
374  }
375 
381  public function GetDependencies()
382  {
383  return $this->Requires;
384  }
385 
392  final public function __construct()
393  {
394  # make sure we are being called from the plugin manager
395  StdLib::CheckMyCaller("PluginManager",
396  "Attempt to create plugin object at %FILE%:%LINE%."
397  ." (Plugins can only be instantiated by PluginManager.)");
398 
399  # register plugin
400  $this->Register();
401 
402  # load plugin info from database if necessary
403  if (!isset(self::$PluginInfoCache))
404  {
405  $DB = new Database();
406  $DB->Query("SELECT * FROM PluginInfo");
407  while ($Row = $DB->FetchRow())
408  {
409  self::$PluginInfoCache[$Row["BaseName"]] = $Row;
410  }
411  }
412 
413  # add plugin to database if not already in there
414  $BaseName = get_class($this);
415  if (!isset(self::$PluginInfoCache[$BaseName]))
416  {
417  if (!isset($DB))
418  {
419  $DB = new Database();
420  }
421  $Attribs = $this->GetAttributes();
422  $DB->Query("INSERT INTO PluginInfo"
423  ." (BaseName, Version, Enabled)"
424  ." VALUES ('".addslashes($BaseName)."', "
425  ." '".addslashes(
426  $Attribs["Version"])."', "
427  ." ".($Attribs["EnabledByDefault"]
428  ? 1 : 0).")");
429  $DB->Query("SELECT * FROM PluginInfo WHERE BaseName = '"
430  .addslashes($BaseName)."'");
431  self::$PluginInfoCache[$BaseName] = $DB->FetchRow();
432  }
433 
434  # set internal value
435  $Info = self::$PluginInfoCache[$BaseName];
436  $this->Enabled = $Info["Enabled"];
437  $this->Installed = $Info["Installed"];
438  $this->InstalledVersion = $Info["Version"];
439  $this->Cfg = unserialize($Info["Cfg"]);
440  }
441 
447  static final public function SetApplicationFramework($AF)
448  {
449  self::$AF = $AF;
450  }
451 
452 
453  # ----- PROTECTED INTERFACE ----------------------------------------------
454 
456  protected $Author = NULL;
458  protected $Description = NULL;
460  protected $Email = NULL;
462  protected $EnabledByDefault = FALSE;
464  protected $InitializeBefore = array();
466  protected $InitializeAfter = array();
470  protected $Instructions = NULL;
472  protected $Name = NULL;
474  protected $Version = NULL;
476  protected $Url = NULL;
477 
479  static protected $AF;
480 
488  protected $Requires = array();
489 
497  protected $CfgSetup = array();
498 
502  protected $CfgPage = NULL;
503 
504 
505  # ----- PRIVATE INTERFACE ------------------------------------------------
506 
508  private $Cfg;
510  private $CfgOver;
512  private $Enabled = FALSE;
514  private $Installed = FALSE;
516  private $InstalledVersion = FALSE;
518  private $Ready = FALSE;
519 
521  private static $PluginInfoCache;
522 
530  protected function CreateTables($Tables)
531  {
532  $DB = new Database();
533  foreach ($Tables as $TableName => $TableSql)
534  {
535  $Result = $DB->Query($TableSql);
536  if ($Result === FALSE)
537  {
538  if (strpos($TableName, get_class($this)) !== 0)
539  {
540  $TableName = get_class($this)."_".$TableName;
541  }
542  return "Unable to create ".$TableName." database table."
543  ." (ERROR: ".$DB->QueryErrMsg().")";
544  }
545  }
546 
547  return NULL;
548  }
549 
557  protected function DropTables($Tables)
558  {
559  $DB = new Database();
560  foreach ($Tables as $TableName => $TableSql)
561  {
562  if (strpos($TableName, get_class($this)) !== 0)
563  {
564  $TableName = get_class($this)."_".$TableName;
565  }
566  $DB->Query("DROP TABLE IF EXISTS ".$TableName);
567  }
568 
569  return NULL;
570  }
571 
577  final public function SetAllCfg($NewValues)
578  {
579  $this->Cfg = $NewValues;
580  }
582 }
583 
584 
Install()
Perform any work needed when the plugin is first installed (for example, creating database tables)...
Definition: Plugin.php:86
ConfigSettingOverride($SettingName, $Value)
Set override for configuration setting, that will be returned regardless of the current saved configu...
Definition: Plugin.php:242
IsReady($NewValue=NULL)
Get/set whether the plugin is ready for use.
Definition: Plugin.php:261
$InitializeAfter
Plugins that should be initialized before us.
Definition: Plugin.php:466
static CheckMyCaller($DesiredCaller, $ExceptionMsg=NULL)
Check the caller of the current function.
Definition: StdLib.php:69
GetName()
Get full name of plugin.
Definition: Plugin.php:371
$Email
Contact email for the plugin&#39;s author.
Definition: Plugin.php:460
GetConfigSettingType($SettingName)
Get type of a plugin configuration setting.
Definition: Plugin.php:215
SQL database abstraction object with smart query caching.
Definition: Database.php:22
Register()
Set the plugin attributes.
InstalledVersion($NewValue=NULL)
Get/set the last version recorded as installed.
Definition: Plugin.php:345
Upgrade($PreviousVersion)
Perform any work needed when the plugin is upgraded to a new version (for example, adding fields to database tables).
Definition: Plugin.php:99
IsInstalled($NewValue=NULL)
Get/set whether the plugin is installed.
Definition: Plugin.php:317
$EnabledByDefault
Whether the plugin should be enabled by default when installed.
Definition: Plugin.php:462
GetConfigSettingParameters($SettingName)
Get plugin configuration setting parameters.
Definition: Plugin.php:228
$Version
Version number of plugin in the format X.X.X (for example: 1.2.12).
Definition: Plugin.php:474
GetBaseName()
Get plugin base name.
Definition: Plugin.php:143
$Author
Name of the plugin&#39;s author.
Definition: Plugin.php:456
$InitializeBefore
Plugins that should be initialized after us.
Definition: Plugin.php:464
CreateTables($Tables)
Create database tables.
Definition: Plugin.php:530
__construct()
Class constructor – FOR PLUGIN MANAGER USE ONLY.
Definition: Plugin.php:392
HookEvents()
Hook methods to be called when specific events occur.
Definition: Plugin.php:63
GetDependencies()
Get list of plugins upon which this plugin depends (if any).
Definition: Plugin.php:381
Electronic mail message.
Definition: Email.php:14
$CfgSetup
Associative array describing the configuration values for the plugin.
Definition: Plugin.php:497
$Requires
Array with plugin base (class) names for the index and minimum version numbers for the values...
Definition: Plugin.php:488
SetUpConfigOptions()
Set up plugin configuration options.
Definition: Plugin.php:38
DeclareEvents()
Declare events defined by this plugin.
Definition: Plugin.php:75
Base class for all plugins.
Definition: Plugin.php:13
GetAttributes()
Retrieve plugin information.
Definition: Plugin.php:118
GetSavedConfigSetting($SettingName)
Get plugin configuration setting, ignoring any override value.
Definition: Plugin.php:203
$CfgPage
Name of configuration page for plugin.
Definition: Plugin.php:502
IsEnabled($NewValue=NULL, $Persistent=TRUE)
Get/set whether the plugin is enabled.
Definition: Plugin.php:288
$Description
Text description of the plugin.
Definition: Plugin.php:458
static $AF
Application framework.
Definition: Plugin.php:479
$Name
Proper (human-readable) name of plugin.
Definition: Plugin.php:472
Initialize()
Initialize the plugin.
Definition: Plugin.php:51
DropTables($Tables)
Drop database tables.
Definition: Plugin.php:557
$Url
Web address for more information about the plugin.
Definition: Plugin.php:476
static SetApplicationFramework($AF)
Set the application framework to be referenced within plugins.
Definition: Plugin.php:447
ConfigSetting($SettingName, $NewValue=NULL)
Get/set plugin configuration setting.
Definition: Plugin.php:157
$Instructions
Instructions for configuring the plugin (displayed on the automatically-generated configuration page ...
Definition: Plugin.php:470
Uninstall()
Perform any work needed when the plugin is uninstalled.
Definition: Plugin.php:109