Class: Plugins

Source Location: /blogs/inc/_misc/_plugins.class.php

Class Plugins

Class Overview

Plugins Class

This is where you can plug in some plugins :D

Located in /blogs/inc/_misc/_plugins.class.php [line 52]

Author(s):

Information Tags:

Todo:

A plugin might want to register allowed events (that it triggers itself) on installation..

Properties

Methods

[ Top ]

Direct descendents

Child Class	Description
Plugins_no_DB	A sub-class of Plugins, just to not load any DB info (which means Plugins and Events).
Plugins_admin	A Plugins object that loads all Plugins, not just the enabled ones. This is needed for the backoffice plugin management.

[ Top ]

Property Summary

static string	$sql_load_plugins_table
boolean	$is_admin_class
array	$plugin_errors	Errors associated to plugins (during loading), indexed by plugin_ID and error class ("register").

[ Top ]

Method Summary

Plugins	Plugins()	Constructor. Sets $plugins_path and load events.
boolean	are_events_available()	Check if the requested list of events is provided by any or one plugin.
boolean	call_by_code()	Call a specific plugin by its code.
NULL\|mixed	call_method()	Call a method on a Plugin.
NULL\|mixed	call_method_if_active()	Call a method on a Plugin if it is not deactivated.
int	count_regs()	Count # of registrations of same plugin.
void	discover()	Discover and register all available plugins.
void	forget_events()	Forget the events a Plugin has registered.
array	get_apply_rendering_values()	Get the list of values for when a rendering Plugin can apply (apply_rendering).
Plugin\|false	&get_by_classname()	Get a plugin by its classname.
Plugin\|false	&get_by_code()	Get a specific Plugin by its code.
Plugin\|false	&get_by_ID()	Get a specific plugin by its ID.
array	get_enabled_events()	Get a list of (enabled) events for a given Plugin ID.
array	get_list_by_all_events()	Get a list of plugins that provide all given events.
array	get_list_by_event()	Get a list of Plugins for a given event.
array	get_list_by_events()	Get a list of Plugins for a list of events. Every Plugin is only once in this list.
Plugin\|false	&get_next()	Get next plugin in the list.
void	get_object_from_cacheplugin_or_create()	Load an object from a Cache plugin or create a new one if we have a cache miss or no caching plugins.
array	get_registered_events()	Get a list of methods that are supported as events out of the Plugin's source file.
array	get_supported_events()	Get the list of supported/available events/hooks.
mixed	get_trigger_event()	Trigger an $event and return an index of $params.
mixed	get_trigger_event_first_true()	The same as get_trigger_event(), but stop when the first Plugin returns true.
boolean	has_event()	Has a plugin a specific event registered/enabled?
string\|Plugin	&install()	Install a plugin into DB.
NULL\|boolean	instantiate_Settings()	Instantiate Settings member of class PluginSettings for the given plugin, if it provides default settings (through Plugin::GetDefaultSettings()).
void	load_events()	(Re)load Plugin Events for enabled (normal use) or all (admin use) plugins.
void	load_plugins_table()	Load Plugins data from T_plugins (only once), ordered by priority.
string	quick()	Quick-render a string with a single plugin and format it for output.
string	render()	Render the content of an item.
void	restart()	Load plugins table and rewind iterator used by get_next().
boolean	save_events()	Save the events that the plugin provides into DB, while removing obsolete entries (that the plugin does not register anymore).
boolean	set_apply_rendering()	Set the apply_rendering value for a given Plugin ID.
boolean\|integer\|string	set_code()	Set the code for a given Plugin ID.
boolean	set_event_status()	Set the status of an event for a given Plugin.
void	set_Plugin_status()	Sets the status of a Plugin in DB and registers it into the internal indices when "enabled".
boolean\|integer	set_priority()	Set the priority for a given Plugin ID.
void	sort()	Sort the list of $Plugins.
void	sort_Plugin_name()	Callback function to sort plugins by name.
void	sort_Plugin_priority()	Callback function to sort plugins by priority (and classname, if they have same priority).
void	stop_propagation()	Stop propagation of events to next plugins in trigger_event().
void	trigger_event()	Call all plugins for a given event.
array	trigger_event_first_false()	Call all plugins for a given event, until the first one returns false.
array	trigger_event_first_return()	Call all plugins for a given event, until the first one returns a value (not NULL).
array	trigger_event_first_true()	Call all plugins for a given event, until the first one returns true.
integer\|NULL	trigger_karma_collect()	Trigger a karma collecting event in order to get Karma percentage.
boolean	uninstall()	Uninstall a plugin.
void	unregister()	Un-register a plugin.
array	validate_dependencies()	Validate dependencies of a Plugin.
array	validate_list()	Validate renderer list.

[ Top ]

Properties

static string $sql_load_plugins_table = '
SELECT plug_ID, plug_priority, plug_classname, plug_code, plug_apply_rendering, plug_status, plug_version, plug_spam_weight
FROM T_plugins
WHERE plug_status = "enabled"
ORDER BY plug_priority, plug_classname' [line 159]

API Tags:

Access:

protected

Redefined in descendants as:

Plugins_admin::$sql_load_plugins_table : Load all plugins (not just enabled ones).

[ Top ]

boolean $is_admin_class = false [line 169]

API Tags:

Access:

protected

Redefined in descendants as:

Plugins_admin::$is_admin_class

[ Top ]

array $plugin_errors = array() [line 179]

Errors associated to plugins (during loading), indexed by plugin_ID and error class ("register").

[ Top ]

Methods

Constructor Plugins [line 185]

Plugins Plugins(
)

Constructor. Sets $plugins_path and load events.

[ Top ]

are_events_available [line 2406]

boolean are_events_available(
array|string
$events, [boolean
$by_one_plugin = false] 
)

Check if the requested list of events is provided by any or one plugin.

Parameters:

array\|string	$events:	A single event or a list thereof
boolean	$by_one_plugin:	Make sure there's at least one plugin that provides them all? This is useful for event pairs like "CaptchaPayload" and "CaptchaValidated", which should be served by the same plugin.

[ Top ]

call_by_code [line 2116]

boolean call_by_code(
string
$code, [array
$params = array()] 
)

Call a specific plugin by its code.

This will call the SkinTag event handler.

Parameters:

string	$code:	plugin code
array	$params:	Associative array of parameters (gets passed to the plugin)

[ Top ]

call_method [line 1851]

NULL|mixed call_method(
integer
$plugin_ID, string
$method, array
&$params 
)

Call a method on a Plugin.

This makes sure that the Timer for the Plugin gets resumed.

Parameters:

integer	$plugin_ID:	Plugin ID
string	$method:	Method name.
array	&$params:	Params (by reference).

API Tags:

Return:

Return value of the plugin's method call or NULL if no such method.

[ Top ]

call_method_if_active [line 1895]

NULL|mixed call_method_if_active(
integer
$plugin_ID, string
$method, array
&$params 
)

Call a method on a Plugin if it is not deactivated.

This is a wrapper around call_method().

Parameters:

integer	$plugin_ID:	Plugin ID
string	$method:	Method name.
array	&$params:	Params (by reference).

API Tags:

Return:

Return value of the plugin's method call or NULL if no such method (or inactive).

[ Top ]

count_regs [line 1502]

int count_regs(
string
$classname 
)

Count # of registrations of same plugin.

Plugins with negative ID (auto-generated; not installed (yet)) will not get considered.

Parameters:

string

$classname:

class name

API Tags:

Return:

# of regs

[ Top ]

discover [line 377]

void discover(
)

Discover and register all available plugins.

[ Top ]

forget_events [line 1260]

void forget_events(

$plugin_ID 
)

Forget the events a Plugin has registered.

This gets used when unregistering a Plugin or if Plugin::AppendPluginRegister() returned false, which means "do not use it for subsequent events in the request".

Parameters:

$plugin_ID:

[ Top ]

get_apply_rendering_values [line 352]

array get_apply_rendering_values(
[boolean
$with_desc = false] 
)

Get the list of values for when a rendering Plugin can apply (apply_rendering).

Parameters:

boolean

$with_desc:

Return an associative array with description for the values?

Information Tags:

Todo:

Add descriptions.

[ Top ]

get_by_classname [line 2221]

Plugin|false &get_by_classname(

$classname 
)

Get a plugin by its classname.

Parameters:

$classname:

[ Top ]

get_by_code [line 2244]

Plugin|false &get_by_code(
string
$plugin_code 
)

Get a specific Plugin by its code.

Parameters:

string

$plugin_code:

plugin name

[ Top ]

get_by_ID [line 2177]

Plugin|false &get_by_ID(
integer
$plugin_ID 
)

Get a specific plugin by its ID.

This is the workhorse when it comes to lazy-instantiate a Plugin.

Parameters:

integer

$plugin_ID:

plugin ID

[ Top ]

get_enabled_events [line 2371]

array get_enabled_events(
integer
$plugin_ID 
)

Get a list of (enabled) events for a given Plugin ID.

Parameters:

integer

$plugin_ID:

Plugin ID

[ Top ]

get_list_by_all_events [line 2326]

array get_list_by_all_events(

$events 
)

Get a list of plugins that provide all given events.

Parameters:

$events:

API Tags:

Return:

The list of plugins, where the key is the plugin's ID

[ Top ]

get_list_by_event [line 2277]

array get_list_by_event(
string
$event 
)

Get a list of Plugins for a given event.

Parameters:

string

$event:

Event name

API Tags:

Return:

List of Plugins, where the key is the plugin's ID

[ Top ]

get_list_by_events [line 2302]

array get_list_by_events(
array
$events 
)

Get a list of Plugins for a list of events. Every Plugin is only once in this list.

Parameters:

array

$events:

Array of events

API Tags:

Return:

List of Plugins, where the key is the plugin's ID

[ Top ]

get_next [line 1526]

Plugin|false &get_next(
)

Get next plugin in the list.

NOTE: You'll have to call restart() or load_plugins_table() before using it.

API Tags:

Return:

(false if no more plugin).

[ Top ]

get_object_from_cacheplugin_or_create [line 2646]

void get_object_from_cacheplugin_or_create(
string
$objectName, [string
$eval_create_object = NULL] 
)

Load an object from a Cache plugin or create a new one if we have a cache miss or no caching plugins.

It registers a shutdown function, that refreshes the data to the cache plugin which is not optimal, but we have no hook to see if data retrieved from a DataObjectCache derived class has changed.

Parameters:

string	$objectName:	object name
string	$eval_create_object:	eval this to create the object. Default is to create an object of class $objectName.

[ Top ]

get_registered_events [line 2450]

array get_registered_events(

$Plugin 
)

Get a list of methods that are supported as events out of the Plugin's source file.

Parameters:

$Plugin:

[ Top ]

get_supported_events [line 232]

array get_supported_events(
)

Get the list of supported/available events/hooks.

Additional to the returned event methods (which can be disabled), there are internal ones which just get called on the plugin (and get not remembered in T_pluginevents), e.g.:

AfterInstall
AppendPluginRegister
BeforeEnable
BeforeDisable
BeforeInstall
BeforeUninstall
BeforeUninstallPayload
GetDefaultSettings
GetDefaultUserSettings
GetHtsrvMethods
PluginSettingsUpdateAction (Called as action before updating the plugin's settings)
PluginSettingsEditAction (Called as action before editing the plugin's settings)
PluginSettingsEditDisplayAfter (Called after standard plugin settings are displayed for editing)
PluginSettingsValidateSet (Called before setting a plugin's setting in the backoffice)
PluginUserSettingsUpdateAction (Called as action before updating the plugin's user settings)
PluginUserSettingsEditAction (Called as action before editing the plugin's settings)
PluginUserSettingsEditDisplayAfter (Called after displaying normal user settings)
PluginUserSettingsValidateSet (Called before setting a plugin's user setting in the backoffice)
PluginVersionChanged (Called when we detect a version change)

The max length of event names is 40 chars (T_pluginevents.pevt_event).

API Tags:

Return:

Name of event (key) => description (value)

Information Tags:

Todo:

Finish/Complete descriptions

[ Top ]

get_trigger_event [line 1722]

mixed get_trigger_event(
string
$event, [array
$params = NULL], [string
$get = 'data'] 
)

Trigger an $event and return an index of $params.

Parameters:

string	$event:	Event name, see Plugins::get_supported_events()
array	$params:	Associative array of parameters for the Plugin
string	$get:	Index of $params that should get returned

API Tags:

Return:

The requested index of $params

[ Top ]

get_trigger_event_first_true [line 1740]

mixed get_trigger_event_first_true(
string
$event, [array
$params = NULL], [string
$get = 'data'] 
)

The same as get_trigger_event(), but stop when the first Plugin returns true.

Parameters:

string	$event:	Event name, see Plugins::get_supported_events()
array	$params:	Associative array of parameters for the Plugin
string	$get:	Index of $params that should get returned

API Tags:

Return:

The requested index of $params

[ Top ]

has_event [line 2390]

boolean has_event(

$plugin_ID, 
$event 
)

Has a plugin a specific event registered/enabled?

Parameters:

	$plugin_ID:
	$event:

[ Top ]

install [line 519]

string|Plugin &install(
string
$classname, [string
$plug_status = 'enabled'], [string|NULL
$classfile_path = NULL] 
)

Install a plugin into DB.

Parameters:

string	$classname:	Classname of the plugin to install
string	$plug_status:	Initial DB Status of the plugin ("enabled", "disabled", "needs_config", "broken")
string\|NULL	$classfile_path:	Optional classfile path, if not default (used for tests).

API Tags:

Return:

The installed Plugin (perhaps with $install_dep_notes set) or a string in case of error.

[ Top ]

instantiate_Settings [line 1430]

NULL|boolean instantiate_Settings(
Plugin
&$Plugin, 
$set_type 
)

Instantiate Settings member of class PluginSettings for the given plugin, if it provides default settings (through Plugin::GetDefaultSettings()).

Parameters:

Plugin	&$Plugin:
	$set_type:

API Tags:

Return:

NULL, if no Settings

[ Top ]

load_events [line 2425]

void load_events(
)

(Re)load Plugin Events for enabled (normal use) or all (admin use) plugins.

Redefined in descendants as:

Plugins_no_DB::load_events() : No-operation.

[ Top ]

load_plugins_table [line 2138]

void load_plugins_table(
)

Load Plugins data from T_plugins (only once), ordered by priority.

This fills the needed indexes to lazy-instantiate a Plugin when requested.

Redefined in descendants as:

Plugins_no_DB::load_plugins_table() : No-operation.

[ Top ]

quick [line 2055]

string quick(
string
$plugin_code, array
$params 
)

Quick-render a string with a single plugin and format it for output.

Parameters:

string	$plugin_code:	Plugin code (must have render() method)
array	$params:	'data': Data to render 'format: format to output, see format_to_output()

API Tags:

Return:

Rendered string

[ Top ]

render [line 1992]

string render(
string
&$content, array
&$renderers, string
$format, array
$params 
)

Render the content of an item.

Parameters:

string	&$content:	content to render (by reference)
array	&$renderers:	renderer codes to use for opt-out, opt-in and lazy (by reference)
string	$format:	Output format, see format_to_output()
array	$params:	Additional params to the Render* methods (e.g. "Item" for items). Do not use "data" or "format" here, because it gets used internally.

API Tags:

Return:

rendered content

[ Top ]

restart [line 1558]

void restart(
)

Load plugins table and rewind iterator used by get_next().

[ Top ]

save_events [line 2505]

boolean save_events(
Plugin
$Plugin, [array|NULL
$enable_events = NULL], [array
$disable_events = NULL] 
)

Save the events that the plugin provides into DB, while removing obsolete entries (that the plugin does not register anymore).

Parameters:

Plugin	$Plugin:	Plugin to save events for
array\|NULL	$enable_events:	List of events to save as enabled for the Plugin. By default all provided events get saved as enabled. Pass array() to discover only new ones.
array	$disable_events:	List of events to save as disabled for the Plugin. By default, no events get disabled. Disabling an event takes priority over enabling.

API Tags:

Return:

True, if events have changed, false if not.

[ Top ]

set_apply_rendering [line 1385]

boolean set_apply_rendering(

$plugin_ID, 
$apply_rendering 
)

Set the apply_rendering value for a given Plugin ID.

It makes sure that the index is handled and writes it to DB.

Parameters:

	$plugin_ID:
	$apply_rendering:

API Tags:

Return:

true if set to new value, false in case of error or if already set to same value

[ Top ]

set_code [line 1286]

boolean|integer|string set_code(
string
$plugin_ID, string
$code 
)

Set the code for a given Plugin ID.

It makes sure that the index is handled and writes it to DB.

Parameters:

string	$plugin_ID:	Plugin ID
string	$code:	Code to set the plugin to

API Tags:

Return:

true, if already set to same value. string: error message (already in use, wrong format)

in case of setting it into DB (number of affected rows).

false, if invalid Plugin.

[ Top ]

set_event_status [line 2612]

boolean set_event_status(

$plugin_ID, 
$plugin_event, 
$enabled 
)

Set the status of an event for a given Plugin.

Parameters:

	$plugin_ID:
	$plugin_event:
	$enabled:

API Tags:

Return:

True, if status has changed; false if not

[ Top ]

set_Plugin_status [line 488]

void set_Plugin_status(
Plugin
&$Plugin, string
$status 
)

Sets the status of a Plugin in DB and registers it into the internal indices when "enabled".

Otherwise it gets unregisters, but only when we're not in Plugins_admin, because we want to keep it in then in our indices.

{@ object, not $admin_Plugins. }}

Parameters:

Plugin	&$Plugin:
string	$status:	New status ("enabled", "disabled", "needs_config", "broken")

[ Top ]

set_priority [line 1347]

boolean|integer set_priority(

$plugin_ID, 
$priority 
)

Set the priority for a given Plugin ID.

It makes sure that the index is handled and writes it to DB.

Parameters:

	$plugin_ID:
	$priority:

API Tags:

Return:

true, if already set to same value. false if another Plugin uses that priority already.

in case of setting it into DB.

[ Top ]

sort [line 417]

void sort(
[string
$order = 'priority'] 
)

Sort the list of $Plugins.

WARNING: do NOT sort by anything else than priority unless you're handling a list of NOT-YET-INSTALLED plugins!

Parameters:

string

$order:

Order: 'priority' (default), 'name'

[ Top ]

sort_Plugin_name [line 466]

void sort_Plugin_name(

&$a_ID, 
&$b_ID 
)

Callback function to sort plugins by name.

WARNING: do NOT sort by anything else than priority unless you're handling a list of NOT-YET-INSTALLED plugins

Parameters:

	&$a_ID:
	&$b_ID:

[ Top ]

sort_Plugin_priority [line 446]

void sort_Plugin_priority(

&$a_ID, 
&$b_ID 
)

Callback function to sort plugins by priority (and classname, if they have same priority).

Parameters:

	&$a_ID:
	&$b_ID:

[ Top ]

stop_propagation [line 1569]

void stop_propagation(
)

Stop propagation of events to next plugins in trigger_event().

[ Top ]

trigger_event [line 1581]

void trigger_event(
string
$event, [array
$params = NULL] 
)

Call all plugins for a given event.

Parameters:

string	$event:	event name, see Plugin::get_supported_events()
array	$params:	Associative array of parameters for the Plugin

[ Top ]

trigger_event_first_false [line 1649]

array trigger_event_first_false(
string
$event, [array
$params = NULL] 
)

Call all plugins for a given event, until the first one returns false.

Parameters:

string	$event:	event name, see Plugin::get_supported_events()
array	$params:	Associative array of parameters for the Plugin

API Tags:

Return:

The (modified) params array with key "plugin_ID" set to the last called plugin; Empty array if no Plugin returned true or no Plugin has this event registered.

[ Top ]

trigger_event_first_return [line 1686]

array trigger_event_first_return(
string
$event, [array
$params = NULL] 
)

Call all plugins for a given event, until the first one returns a value (not NULL).

Parameters:

string	$event:	event name, see Plugin::get_supported_events()
array	$params:	Associative array of parameters for the Plugin

API Tags:

Return:

The (modified) params array with key "plugin_ID" set to the last called plugin and 'plugin_return' set to the return value; Empty array if no Plugin returned true or no Plugin has this event registered.

[ Top ]

trigger_event_first_true [line 1614]

array trigger_event_first_true(
string
$event, [array
$params = NULL] 
)

Call all plugins for a given event, until the first one returns true.

Parameters:

string	$event:	event name, see Plugin::get_supported_events()
array	$params:	Associative array of parameters for the Plugin

API Tags:

Return:

The (modified) params array with key "plugin_ID" set to the last called plugin; Empty array if no Plugin returned true or no Plugin has this event registered.

[ Top ]

trigger_karma_collect [line 1757]

integer|NULL trigger_karma_collect(
string
$event, array
$params 
)

Trigger a karma collecting event in order to get Karma percentage.

Parameters:

string	$event:	Event
array	$params:	Params to the event

API Tags:

Return:

Spam Karma (-100 - 100); "100" means "absolutely spam"; NULL if no plugin gave us a karma value

[ Top ]

uninstall [line 642]

boolean uninstall(

$plugin_ID 
)

Uninstall a plugin.

Removes the Plugin, its Settings and Events from the database.

Parameters:

$plugin_ID:

API Tags:

Return:

True on success

[ Top ]

unregister [line 1203]

void unregister(

&$Plugin 
)

Un-register a plugin.

This does not un-install it from DB, just from the internal indexes.

Parameters:

&$Plugin:

[ Top ]

validate_dependencies [line 688]

array validate_dependencies(
Plugin
&$Plugin, string
$mode 
)

Validate dependencies of a Plugin.

Parameters:

Plugin	&$Plugin:
string	$mode:	Mode of check: either 'enable' or 'disable'

API Tags:

Return:

The key 'note' holds an array of notes (recommendations), the key 'error' holds a list of messages for dependency errors.

[ Top ]

validate_list [line 1913]

array validate_list(
[array
$renderers = array('default')] 
)

Validate renderer list.

Parameters:

array

$renderers:

renderer codes ('default' will include all "opt-out"-ones)

API Tags:

Return:

validated array

[ Top ]

Multilingual multiuser multiblog engine

Class: Plugins

Class Plugins

Packages

Classes

Files