PluginCollection
in package

NWiki

Plugin management

This class managed Plugins, and also includes plugin utility methods.

Constants

API_ERROR = 'error': API Event handler status code indicating execution failure
API_OK = 'ok': API Event handler status code indicating succesful execution
NOOP = NULL: Event handler return code indicating that event was **NOT** handled.
OK = false: Event handler return code indicating that event was handled.
OKSTOP = true: Event handler return code indicating that event was handled and event processing should be stopped.

Properties

$handlers : array<string|int, mixed>: List of event hanlders
$media_classes : mixed: List of media handler classes
$mediatypes : mixed: Used to quickly identified registered handlers
$plugins : mixed: List of loaded plugins

Methods

apiError() : bool|null: sets up a API handler as returning an error.
autoload() : void: Autoload event handlers
devt() : array<string|int, mixed>: Utility function to send read-only events
dispatchEvent() : bool: Dispatch events
loadPlugins() : void: Load plugins in plugin paths
mediaExt() : string|null: Check the media handler for the page
path() : string: Return the file path to the a Plugin source
pluginPath() : array<string|int, mixed>: translates configured plugin path into list of directories
registerEvent() : void: Register an event handler
registerMedia() : void: Register a new media type

API_ERROR

API Event handler status code indicating execution failure


    public
        string
    API_ERROR
    = 'error'

API_OK

API Event handler status code indicating succesful execution


    public
        string
    API_OK
    = 'ok'

NOOP

Event handler return code indicating that event was **NOT** handled.


    public
        bool|null
    NOOP
    = NULL

OK

Event handler return code indicating that event was handled.


    public
        bool|null
    OK
    = false

OKSTOP

Event handler return code indicating that event was handled and event processing should be stopped.


    public
        bool|null
    OKSTOP
    = true

$handlers

List of event hanlders


    public
    static    array<string|int, mixed>
    $handlers
     = []

$media_classes

List of media handler classes


    public
    static    mixed
    $media_classes
     = []

$mediatypes

Used to quickly identified registered handlers


    public
    static    mixed
    $mediatypes
     = []

$plugins

List of loaded plugins


    public
    static    mixed
    $plugins
     = []

apiError()

sets up a API handler as returning an error.


    public
            static        apiError(array<string|int, mixed> &$ev, string $msg[, array<string|int, mixed> $opts = ['status' => self::API_ERROR, 'rc' => self::OK] ]) : bool|null

To be used by an API handler when detecting an error. Example call:

return Plugins::apiError($event, 'Example error');

$opts

rc ?bool - return code, Plugins::OK, Plugins::OKSTOP, Plugins::NOOP.
status string - Status to set the event too. Defaults to Plugins::API_ERROR.

Parameters

$ev : array<string|int, mixed>: Event array
$msg : string: Error message
$opts : array<string|int, mixed> = ['status' => self::API_ERROR, 'rc' => self::OK]: Options

Return values

bool|null —

Returns self::OK by default. Otherwise the value of $opts[rc]

autoload()

Autoload event handlers


    public
            static        autoload(string $class) : void

It will look in the doc strings of the methods for the given class looking for a tag:

Parameters

$class : string: Class name to autoload

devt()

Utility function to send read-only events


    public
            static    &    devt([array<string|int, mixed> $content = [] ]) : array<string|int, mixed>

When calling dispatchEvent, you can use this to generate an event array that only contains read-only data.

Example usage:

Plugins::dispatchEvent($wiki, 'test-event', Plugins:devt([ 'option1' => 1, 'option2' => 2 ]));

Parameters

$content : array<string|int, mixed> = []: array containing data that will be placed on the newly created event.

Return values

array<string|int, mixed> —

reference to the event.

dispatchEvent()

Dispatch events


    public
            static        dispatchEvent(NacoWikiApp $wiki, string $event[, array<string|int, mixed> &$data = NULL ]) : bool

It will call the hooks for the given $event. Data to the hook is passed through the $data array. When calling dispatchEvent if no data needs to be received, you can leave this argument empty. Otherwise you need to pass an array preloaded with any input data. The results will be received throug the same array.

For read-only events you can use PluginCollection::devt static function to pass read-only arguments.

Parameters

$wiki : NacoWikiApp: current wiki instance
$event : string: event name that we are dispatching
$data : array<string|int, mixed> = NULL: nullable data for given event

Return values

bool —

true if event was handled, otherwise false.

loadPlugins()

Load plugins in plugin paths


    public
            static        loadPlugins(array<string|int, mixed> $cfg) : void

It will use the $cfg[plugins][enabled] and $cfg[plugins][disabled] list to enable or disable the listed pluigns.

The default is to load all plugins.
If a disable list is provided it is used as a blacklist to stop the given plugins to be loaded.
If a enable list, only the plugins in the list are enabled.
If both enable and disable are given, it first will use the enable list, then use the disable list.

Both for enable and disable lists, it is taken either as an array listing plugin names, or a string containing comma separated plugin names.

In the plugin loading process, the loadPlugin method will use require_once to load the plugin file. Then it will call the load method for all the classes that were created by the plugin file, if they exist.

The plugin class then can use the PluginCollection functions to register events or media handlers. Also, the PluginCollection autoload method can be used.

Parameters

$cfg : array<string|int, mixed>: Wiki configuration

mediaExt()

Check the media handler for the page


    public
            static        mediaExt(string $page) : string|null

Parameters

$page : string: page to look-up the media handler for

Return values

string|null —

normalized file extension or NULL

path()

Return the file path to the a Plugin source


    public
            static        path([string $file = NULL ]) : string

This is a convenience function used to determine the folder where a Plugin stores files.

It will first look if there is a folder with the same name as the source without the .php extension. If that failes, it will use the dirname of the source php file.

Parameters

$file : string = NULL: File to look up. If not specified it will simply return the plugin directory path

Return values

string

pluginPath()

translates configured plugin path into list of directories


    public
            static        pluginPath(array<string|int, mixed> $cfg) : array<string|int, mixed>

Given the NacoWiki configuration, it will return an array containing directories where to look for plugins.

The default is APP_DIR/plugins.

Parameters

$cfg : array<string|int, mixed>: Configuration array

Return values

array<string|int, mixed> —

List of plugin directories

registerEvent()


    public
            static        registerEvent(string $event, mixed $callable) : void

Parameters

$event : string
$callable : mixed

registerMedia()


    public
            static        registerMedia(string|array<string|int, mixed> $ext, string $class[, null|string|array<string|int, mixed> $handler = NULL ]) : void

It will define the given extension (or extensions) as a media type and will add these methods as event hooks:

view => view:[ext]
- read => read:[ext]
- render => render:[ext]
- layout => layout:[ext]
missing => missing:[ext]
edit => edit:[ext]
save => save:[ext]
preSave => preSave:[ext]
postSave => postSave:[ext]

Not all methods are needed, media handlers only need to provide the methods needed, otherwise NacoWiki will provide a suitable default. Note that if a view method is provided, it will be called first, bypassing read, render and layout.

Methods need to be defined with these prototypes:

static function view(\NacoWikiApp $wiki, array &$data) : ?bool;
static function read(\NacoWikiApp $wiki, array &$data) : ?bool;
static function render(\NacoWikiApp $wiki, array &$data) : ?bool;
static function layout(\NacoWikiApp $wiki, array &$data) : ?bool;
static function missing(\NacoWikiApp $wiki, array &$data) : ?bool;
static function edit(\NacoWikiApp $wiki, array &$data) : ?bool;
static function preSave(\NacoWikiApp $wiki, array &$data) : ?bool;
static function save(\NacoWikiApp $wiki, array &$data) : ?bool;
static function postSave(\NacoWikiApp $wiki, array &$data) : ?bool;

Parameters

$ext : string|array<string|int, mixed>: -- file extension or array listing file extensions
$class : string: -- class name handling this media type
$handler : null|string|array<string|int, mixed> = NULL: -- how media types are handled

PluginCollection in package NWiki

Table of Contents

Constants

Properties

Methods

Constants

API_ERROR

API_OK

NOOP

OK

OKSTOP

Properties

$handlers

$media_classes

$mediatypes

$plugins

Methods

apiError()

$opts

Parameters

Return values

autoload()

Parameters

Tags

devt()

Parameters

Return values

dispatchEvent()

Parameters

Return values

loadPlugins()

Parameters

Tags

mediaExt()

Parameters

Return values

path()

Parameters

Return values

pluginPath()

Parameters

Return values

registerEvent()

Parameters

registerMedia()

Parameters

PluginCollection
in package

NWiki