CWIS Developer Documentation

- Home
- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

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
531 protected function CreateTables($Tables, $DB = NULL)
532 {
533 if ($DB === NULL) { $DB = new Database(); }
534 foreach ($Tables as $TableName => $TableSql)
535 {
536 $Result = $DB->Query($TableSql);
537 if ($Result === FALSE)
538 {
539 if (strpos($TableName, get_class($this)) !== 0)
540 {
541 $TableName = get_class($this)."_".$TableName;
542 }
543 return "Unable to create ".$TableName." database table."
544 ." (ERROR: ".$DB->QueryErrMsg().")";
545 }
546 }
547
548 return NULL;
549 }
550
560 protected function CreateMissingTables($Tables)
561 {
562 $DB = new Database();
563 $SqlErrorsWeCanIgnore = array(
564 "/CREATE TABLE /i" => "/Table '[a-z0-9_]+' already exists/i");
565 $DB->SetQueryErrorsToIgnore($SqlErrorsWeCanIgnore);
566 return $this->CreateTables($Tables, $DB);
567 }
568
576 protected function DropTables($Tables)
577 {
578 $DB = new Database();
579 foreach ($Tables as $TableName => $TableSql)
580 {
581 if (strpos($TableName, get_class($this)) !== 0)
582 {
583 $TableName = get_class($this)."_".$TableName;
584 }
585 $DB->Query("DROP TABLE IF EXISTS ".$TableName);
586 }
587
588 return NULL;
589 }
590
596 final public function SetAllCfg($NewValues)
597 {
598 $this->Cfg = $NewValues;
599 }
601 }
602
603
Plugin\Install
Install()
Perform any work needed when the plugin is first installed (for example, creating database tables)...
Definition: Plugin.php:86
Plugin\ConfigSettingOverride
ConfigSettingOverride($SettingName, $Value)
Set override for configuration setting, that will be returned regardless of the current saved configu...
Definition: Plugin.php:242
Plugin\IsReady
IsReady($NewValue=NULL)
Get/set whether the plugin is ready for use.
Definition: Plugin.php:261
Plugin\$InitializeAfter
$InitializeAfter
Plugins that should be initialized before us.
Definition: Plugin.php:466
StdLib\CheckMyCaller
static CheckMyCaller($DesiredCaller, $ExceptionMsg=NULL)
Check the caller of the current function.
Definition: StdLib.php:69
Plugin\GetName
GetName()
Get full name of plugin.
Definition: Plugin.php:371
Plugin\$Email
$Email
Contact email for the plugin&#39;s author.
Definition: Plugin.php:460
Plugin\GetConfigSettingType
GetConfigSettingType($SettingName)
Get type of a plugin configuration setting.
Definition: Plugin.php:215
Database
SQL database abstraction object with smart query caching.
Definition: Database.php:22
Plugin\Register
Register()
Set the plugin attributes.
Plugin\InstalledVersion
InstalledVersion($NewValue=NULL)
Get/set the last version recorded as installed.
Definition: Plugin.php:345
Plugin\Upgrade
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
Plugin\IsInstalled
IsInstalled($NewValue=NULL)
Get/set whether the plugin is installed.
Definition: Plugin.php:317
Plugin\$EnabledByDefault
$EnabledByDefault
Whether the plugin should be enabled by default when installed.
Definition: Plugin.php:462
Plugin\GetConfigSettingParameters
GetConfigSettingParameters($SettingName)
Get plugin configuration setting parameters.
Definition: Plugin.php:228
Plugin\$Version
$Version
Version number of plugin in the format X.X.X (for example: 1.2.12).
Definition: Plugin.php:474
Plugin\GetBaseName
GetBaseName()
Get plugin base name.
Definition: Plugin.php:143
Plugin\$Author
$Author
Name of the plugin&#39;s author.
Definition: Plugin.php:456
Plugin\$InitializeBefore
$InitializeBefore
Plugins that should be initialized after us.
Definition: Plugin.php:464
Plugin\__construct
__construct()
Class constructor – FOR PLUGIN MANAGER USE ONLY.
Definition: Plugin.php:392
Plugin\HookEvents
HookEvents()
Hook methods to be called when specific events occur.
Definition: Plugin.php:63
Plugin\GetDependencies
GetDependencies()
Get list of plugins upon which this plugin depends (if any).
Definition: Plugin.php:381
Email
Electronic mail message.
Definition: Email.php:14
Plugin\$CfgSetup
$CfgSetup
Associative array describing the configuration values for the plugin.
Definition: Plugin.php:497
Plugin\$Requires
$Requires
Array with plugin base (class) names for the index and minimum version numbers for the values...
Definition: Plugin.php:488
Plugin\SetUpConfigOptions
SetUpConfigOptions()
Set up plugin configuration options.
Definition: Plugin.php:38
Plugin\DeclareEvents
DeclareEvents()
Declare events defined by this plugin.
Definition: Plugin.php:75
Plugin\CreateTables
CreateTables($Tables, $DB=NULL)
Create database tables.
Definition: Plugin.php:531
Plugin
Base class for all plugins.
Definition: Plugin.php:13
PHP
PHP
Definition: RSSClient--Test.php:12
Plugin\GetAttributes
GetAttributes()
Retrieve plugin information.
Definition: Plugin.php:118
Plugin\GetSavedConfigSetting
GetSavedConfigSetting($SettingName)
Get plugin configuration setting, ignoring any override value.
Definition: Plugin.php:203
Plugin\CreateMissingTables
CreateMissingTables($Tables)
Create missing database tables.
Definition: Plugin.php:560
Plugin\$CfgPage
$CfgPage
Name of configuration page for plugin.
Definition: Plugin.php:502
Plugin\IsEnabled
IsEnabled($NewValue=NULL, $Persistent=TRUE)
Get/set whether the plugin is enabled.
Definition: Plugin.php:288
Plugin\$Description
$Description
Text description of the plugin.
Definition: Plugin.php:458
Plugin\$AF
static $AF
Application framework.
Definition: Plugin.php:479
Plugin\$Name
$Name
Proper (human-readable) name of plugin.
Definition: Plugin.php:472
Plugin\Initialize
Initialize()
Initialize the plugin.
Definition: Plugin.php:51
Plugin\DropTables
DropTables($Tables)
Drop database tables.
Definition: Plugin.php:576
Plugin\$Url
$Url
Web address for more information about the plugin.
Definition: Plugin.php:476
Plugin\SetApplicationFramework
static SetApplicationFramework($AF)
Set the application framework to be referenced within plugins.
Definition: Plugin.php:447
Plugin\ConfigSetting
ConfigSetting($SettingName, $NewValue=NULL)
Get/set plugin configuration setting.
Definition: Plugin.php:157
Plugin\$Instructions
$Instructions
Instructions for configuring the plugin (displayed on the automatically-generated configuration page ...
Definition: Plugin.php:470
Plugin\Uninstall
Uninstall()
Perform any work needed when the plugin is uninstalled.
Definition: Plugin.php:109