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 
155  public final function ConfigSetting($SettingName, $NewValue = NULL)
156  {
157  # if a new value was supplied for the setting
158  if (func_num_args() > 1)
159  {
160  # if this setting has a filter function specified
161  if (array_key_exists($SettingName, $this->CfgSetup)
162  && array_key_exists("SettingFilter",
163  $this->CfgSetup[$SettingName]))
164  {
165  # pass new value through filter function
166  $FilterMethod = $this->CfgSetup[$SettingName]["SettingFilter"];
167  $NewValue = $this->$FilterMethod($SettingName, $NewValue);
168  }
169 
170  # if caller requested that setting be cleared
171  if ($NewValue === NULL)
172  {
173  # clear setting
174  unset($this->Cfg[$SettingName]);
175  }
176  else
177  {
178  # save new value for setting
179  $this->Cfg[$SettingName] = $NewValue;
180  }
181 
182  # save new configuration settings
183  $DB = new Database();
184  $DB->Query("UPDATE PluginInfo SET Cfg = '"
185  .addslashes(serialize($this->Cfg))
186  ."' WHERE BaseName = '"
187  .addslashes($this->GetBaseName())."'");
188  }
189 
190  # return current value of setting to caller
191  return isset($this->Cfg[$SettingName]) ? $this->Cfg[$SettingName] : NULL;
192  }
193 
200  public function IsReady($NewValue = NULL)
201  {
202  # if new ready status was supplied
203  if ($NewValue !== NULL)
204  {
205  # make sure we are being called from the plugin manager
206  StdLib::CheckMyCaller("PluginManager",
207  "Attempt to update plugin ready status at %FILE%:%LINE%."
208  ." (Plugin ready status can only be set by PluginManager.)");
209 
210  # update plugin ready status
211  $this->Ready = $NewValue ? TRUE : FALSE;
212  }
213 
214  # return current ready status to caller
215  return $this->Ready;
216  }
217 
224  public function IsEnabled($NewValue = NULL)
225  {
226  # if new enabled status was suppled
227  if ($NewValue !== NULL)
228  {
229  # update enabled status in database
230  $this->Enabled = $NewValue ? TRUE : FALSE;
231  $DB = new Database();
232  $DB->Query("UPDATE PluginInfo"
233  ." SET Enabled = ".($NewValue ? "1" : "0")
234  ." WHERE BaseName = '".addslashes($this->GetBaseName())."'");
235  }
236 
237  # return current enabled status to caller
238  return $this->Enabled;
239  }
240 
248  public function IsInstalled($NewValue = NULL)
249  {
250  # if new install status was supplied
251  if ($NewValue !== NULL)
252  {
253  # make sure we are being called from the plugin manager
254  StdLib::CheckMyCaller("PluginManager",
255  "Attempt to update plugin install status at %FILE%:%LINE%."
256  ." (Plugin install status can only be set by PluginManager.)");
257 
258  # update installation setting in database
259  $this->Installed = $NewValue ? TRUE : FALSE;
260  $DB = new Database();
261  $DB->Query("UPDATE PluginInfo"
262  ." SET Installed = ".($NewValue ? "1" : "0")
263  ." WHERE BaseName = '".addslashes($this->GetBaseName())."'");
264  }
265 
266  # return installed status to caller
267  return $this->Installed;
268  }
269 
276  public function InstalledVersion($NewValue = NULL)
277  {
278  # if new version was supplied
279  if ($NewValue !== NULL)
280  {
281  # make sure we are being called from the plugin manager
282  StdLib::CheckMyCaller("PluginManager",
283  "Attempt to set installed version of plugin at %FILE%:%LINE%."
284  ." (Plugin installed version can only be set by PluginManager.)");
285 
286  # update version in database
287  $this->InstalledVersion = $NewValue;
288  $DB = new Database();
289  $DB->Query("UPDATE PluginInfo"
290  ." SET Version = '".addslashes($NewValue)."'"
291  ." WHERE BaseName = '".addslashes($this->GetBaseName())."'");
292  }
293 
294  # return current installed version to caller
295  return $this->InstalledVersion;
296  }
297 
302  public function GetName()
303  {
304  return $this->Name;
305  }
306 
312  public function GetDependencies()
313  {
314  return $this->Requires;
315  }
316 
323  final public function __construct()
324  {
325  # make sure we are being called from the plugin manager
326  StdLib::CheckMyCaller("PluginManager",
327  "Attempt to create plugin object at %FILE%:%LINE%."
328  ." (Plugins can only be instantiated by PluginManager.)");
329 
330  # register plugin
331  $this->Register();
332 
333  # load plugin info from database if necessary
334  if (!isset(self::$PluginInfoCache))
335  {
336  $DB = new Database();
337  $DB->Query("SELECT * FROM PluginInfo");
338  while ($Row = $DB->FetchRow())
339  {
340  self::$PluginInfoCache[$Row["BaseName"]] = $Row;
341  }
342  }
343 
344  # add plugin to database if not already in there
345  $BaseName = get_class($this);
346  if (!isset(self::$PluginInfoCache[$BaseName]))
347  {
348  if (!isset($DB))
349  {
350  $DB = new Database();
351  }
352  $Attribs = $this->GetAttributes();
353  $DB->Query("INSERT INTO PluginInfo"
354  ." (BaseName, Version, Enabled)"
355  ." VALUES ('".addslashes($BaseName)."', "
356  ." '".addslashes(
357  $Attribs["Version"])."', "
358  ." ".($Attribs["EnabledByDefault"]
359  ? 1 : 0).")");
360  $DB->Query("SELECT * FROM PluginInfo WHERE BaseName = '"
361  .addslashes($BaseName)."'");
362  self::$PluginInfoCache[$BaseName] = $DB->FetchRow();
363  }
364 
365  # set internal value
366  $Info = self::$PluginInfoCache[$BaseName];
367  $this->Enabled = $Info["Enabled"];
368  $this->Installed = $Info["Installed"];
369  $this->InstalledVersion = $Info["Version"];
370  $this->Cfg = unserialize($Info["Cfg"]);
371  }
372 
378  static final public function SetApplicationFramework($AF)
379  {
380  self::$AF = $AF;
381  }
382 
383 
384  # ----- PROTECTED INTERFACE ----------------------------------------------
385 
387  protected $Author = NULL;
389  protected $Description = NULL;
391  protected $Email = NULL;
393  protected $EnabledByDefault = FALSE;
395  protected $InitializeBefore = array();
397  protected $InitializeAfter = array();
401  protected $Instructions = NULL;
403  protected $Name = NULL;
405  protected $Version = NULL;
407  protected $Url = NULL;
408 
410  static protected $AF;
411 
419  protected $Requires = array();
420 
428  protected $CfgSetup = array();
429 
433  protected $CfgPage = NULL;
434 
435 
436  # ----- PRIVATE INTERFACE ------------------------------------------------
437 
439  private $Cfg;
441  private $Enabled = FALSE;
443  private $Installed = FALSE;
445  private $InstalledVersion = FALSE;
447  private $Ready = FALSE;
448 
450  private static $PluginInfoCache;
451 
457  final public function SetAllCfg($NewValues)
458  {
459  $this->Cfg = $NewValues;
460  }
462 }
463 
464 
Install()
Perform any work needed when the plugin is first installed (for example, creating database tables)...
Definition: Plugin.php:86
IsReady($NewValue=NULL)
Get/set whether the plugin is ready for use.
Definition: Plugin.php:200
$InitializeAfter
Plugins that should be initialized before us.
Definition: Plugin.php:397
static CheckMyCaller($DesiredCaller, $ExceptionMsg=NULL)
Check the caller of the current function.
Definition: StdLib.php:47
GetName()
Get full name of plugin.
Definition: Plugin.php:302
$Email
Contact email for the plugin&#39;s author.
Definition: Plugin.php:391
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:276
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:248
$EnabledByDefault
Whether the plugin should be enabled by default when installed.
Definition: Plugin.php:393
$Version
Version number of plugin in the format X.X.X (for example: 1.2.12).
Definition: Plugin.php:405
GetBaseName()
Get plugin base name.
Definition: Plugin.php:143
$Author
Name of the plugin&#39;s author.
Definition: Plugin.php:387
$InitializeBefore
Plugins that should be initialized after us.
Definition: Plugin.php:395
__construct()
Class constructor – FOR PLUGIN MANAGER USE ONLY.
Definition: Plugin.php:323
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:312
Electronic mail message.
Definition: Email.php:14
$CfgSetup
Associative array describing the configuration values for the plugin.
Definition: Plugin.php:428
$Requires
Array with plugin base (class) names for the index and minimum version numbers for the values...
Definition: Plugin.php:419
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
$CfgPage
Name of configuration page for plugin.
Definition: Plugin.php:433
$Description
Text description of the plugin.
Definition: Plugin.php:389
static $AF
Application framework.
Definition: Plugin.php:410
$Name
Proper (human-readable) name of plugin.
Definition: Plugin.php:403
Initialize()
Initialize the plugin.
Definition: Plugin.php:51
$Url
Web address for more information about the plugin.
Definition: Plugin.php:407
static SetApplicationFramework($AF)
Set the application framework to be referenced within plugins.
Definition: Plugin.php:378
IsEnabled($NewValue=NULL)
Get/set whether the plugin is enabled.
Definition: Plugin.php:224
ConfigSetting($SettingName, $NewValue=NULL)
Get/set plugin configuration setting.
Definition: Plugin.php:155
$Instructions
Instructions for configuring the plugin (displayed on the automatically-generated configuration page ...
Definition: Plugin.php:401
Uninstall()
Perform any work needed when the plugin is uninstalled.
Definition: Plugin.php:109