The SandboxPluginmanager class combines plugin manager and event dispatcher to keep it simple.

Plugin manager

The plugin manager controls the plugin environment of the Sandbox Publisher. Beside storing the plugin folders, it includes plugin files, instantiates plugin classes and store those object instances. It can be accessed in local file, plugins and templates through the $this->pm object interface.

Adding folders

When a plugin class is requested for inclusion or instantiation, the class file is searched in all folders stored in a stack saved within the plugin manager object. Adding new folders to the stack will be done by

$this->pm->addFolder($folder);
// or
$this->pm->addFolder($folder, $sub);

• $folder is a string var of the path to the folder, the path can be an absolute server path or it can be relative to the Sandbox root directory
• $sub is boolean, set it to true when sub folders also should be saved to the stack, otherwise only the submitted folder is saved (default)

Include a plugin

For library plugins it makes sense to include their files but instantiate their classes by yourself in your own object variables. Just say that you need a plugin:

$this->pm->need('PluginClassName');
$myPl = new PluginClassName();

The parameter specifies the name of the plugin file without .php. It can include an absolute server path or a path relative to the Sandbox root directory. If the plugin class is included successfully the method will return the absolte path name of the directory the plugin class file is located in. Otherwise it will return a false.

Get object of plugin class

You can get the object of an plugin class and use it instantly.

$pluginObject = $this->pm->load('PluginClassName'); // without .php extension
$pluginObject->usePluginMethod();

There is even a shortcut for the code above: $this->pm->PluginClassName->usePluginMethod().

The load method will return the object of the instantiated plugin class, or on failure it will throw an exception. The difference between need plus manual instantiation and load is that load will return the same object all the time because objects of instantiated plugin classes are stored by the plugin manager. This might be important when the plugin need to know its earlier running history (or even to safe memory cache and time).

Event dispatcher

The event dispatcher is inlcuded in the plugin manager. Currently it has 2 methods:

• subscribe(string $eventname, string|object $pluginclass, string $handlermethod): this method is used to subscribe event handler methods to events. The event handler method must be a method from a plugin class. The plugin class can be specified by its name or directly by the object. Right now the subscription list for every event is saved as a stack, later subscriptions came behind prior subscriptions.
• publish(string $eventname, [mixed reference $data]): this method is used to publish events and optionally to deliver data to event handlers, data must be passed as reference (&$reference). The event is dispatched to handlers in the same order how they have been saved to the stack.

Subscribe an event handler

Publish an event

Other sources

• API documentation (coming soon)
• ListOfEvents