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
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
Plugin\Install
Install()
Perform any work needed when the plugin is first installed (for example, creating database tables)...
Definition: Plugin.php:86
Plugin\IsReady
IsReady($NewValue=NULL)
Get/set whether the plugin is ready for use.
Definition: Plugin.php:200
Plugin\$InitializeAfter
$InitializeAfter
Plugins that should be initialized before us.
Definition: Plugin.php:397
StdLib\CheckMyCaller
static CheckMyCaller($DesiredCaller, $ExceptionMsg=NULL)
Check the caller of the current function.
Definition: StdLib.php:47
Plugin\GetName
GetName()
Get full name of plugin.
Definition: Plugin.php:302
Plugin\$Email
$Email
Contact email for the plugin&#39;s author.
Definition: Plugin.php:391
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:276
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:248
Plugin\$EnabledByDefault
$EnabledByDefault
Whether the plugin should be enabled by default when installed.
Definition: Plugin.php:393
Plugin\$Version
$Version
Version number of plugin in the format X.X.X (for example: 1.2.12).
Definition: Plugin.php:405
Plugin\GetBaseName
GetBaseName()
Get plugin base name.
Definition: Plugin.php:143
Plugin\$Author
$Author
Name of the plugin&#39;s author.
Definition: Plugin.php:387
Plugin\$InitializeBefore
$InitializeBefore
Plugins that should be initialized after us.
Definition: Plugin.php:395
Plugin\__construct
__construct()
Class constructor – FOR PLUGIN MANAGER USE ONLY.
Definition: Plugin.php:323
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:312
Email
Electronic mail message.
Definition: Email.php:14
Plugin\$CfgSetup
$CfgSetup
Associative array describing the configuration values for the plugin.
Definition: Plugin.php:428
Plugin\$Requires
$Requires
Array with plugin base (class) names for the index and minimum version numbers for the values...
Definition: Plugin.php:419
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
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\$CfgPage
$CfgPage
Name of configuration page for plugin.
Definition: Plugin.php:433
Plugin\$Description
$Description
Text description of the plugin.
Definition: Plugin.php:389
Plugin\$AF
static $AF
Application framework.
Definition: Plugin.php:410
Plugin\$Name
$Name
Proper (human-readable) name of plugin.
Definition: Plugin.php:403
Plugin\Initialize
Initialize()
Initialize the plugin.
Definition: Plugin.php:51
Plugin\$Url
$Url
Web address for more information about the plugin.
Definition: Plugin.php:407
Plugin\SetApplicationFramework
static SetApplicationFramework($AF)
Set the application framework to be referenced within plugins.
Definition: Plugin.php:378
Plugin\IsEnabled
IsEnabled($NewValue=NULL)
Get/set whether the plugin is enabled.
Definition: Plugin.php:224
Plugin\ConfigSetting
ConfigSetting($SettingName, $NewValue=NULL)
Get/set plugin configuration setting.
Definition: Plugin.php:155
Plugin\$Instructions
$Instructions
Instructions for configuring the plugin (displayed on the automatically-generated configuration page ...
Definition: Plugin.php:401
Plugin\Uninstall
Uninstall()
Perform any work needed when the plugin is uninstalled.
Definition: Plugin.php:109