Class: Plugins

Source Location: /blogs/inc/plugins/model/_plugins.class.php

Class Plugins

Class Overview

Plugins Class

This is where you can plug in some plugins :D

Located in /blogs/inc/plugins/model/_plugins.class.php [line 56]

Author(s):

Information Tags:

Todo:

dh> Currently when a plugin goes into "broken" status (e.g. file not readable), it is "disabled" afterwards. This should rather remember the old status (e.g. "enabled") and make it enabled again.

Properties

Methods

[ Top ]

Direct descendents

Child Class	Description
Plugins_admin	A Plugins object that loads all Plugins, not just the enabled ones.

[ Top ]

Property Summary

static string	$sql_load_plugins_table	SQL to use in load_plugins_table(). Gets overwritten for Plugins_admin.
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.
void	count_regs()
void	forget_events()	Forget the events a Plugin has registered.
Plugin	&get_by_classname()	Get a plugin by its classname.
Plugin	&get_by_code()	Get a specific Plugin by its code.
Plugin	&get_by_ID()	Get a specific plugin by its ID.
string	get_classfile_path()	Get path of a given Plugin classname.
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	&get_next()	Get next plugin in the list.
boolean	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_Plugins_in_group()	Will return an array that contents are references to plugins that have the same group, regardless of the sub_group.
array	get_Plugins_in_sub_group()	Will return an array that contents are references to plugins that have the same group and sub_group.
array	get_plugin_groups()	Get a list of available Plugin groups.
mixed	get_trigger_event()	Trigger an event and return an index of params.
mixed	get_trigger_event_first_return()	Trigger an event and return the first return value of a plugin.
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 and enabled?
void	init_settings()	Init Plugin::$Settings and Plugin::$UserSettings, either by unsetting them for PHP5's overloading or instantiating them for PHP4.
Plugin	&instantiate()	Callback, which gets used for Results.
boolean	instantiate_Settings()	Instantiate Settings object (class PluginSettings) for the given plugin.
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.
Plugin	&register()	Register a plugin.
string	render()	Render the content of an item by calling the relevant renderer plugins.
void	restart()	Load plugins table and rewind iterator used by get_next().
boolean	set_apply_rendering()	Set the apply_rendering value for a given Plugin ID.
boolean	set_Plugin_status()	Sets the status of a Plugin in DB and registers it into the internal indices when "enabled".
void	stop_propagation()	Stop propagation of events to next plugins in trigger_event().
array	trigger_collect()	Trigger an event and return an array of all return values of the relevant plugins.
boolean	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) (and $search is fulfilled, if given).
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	unregister()	Un-register a plugin.
array	validate_list()	Validate renderer list.
array	validate_renderer_list()	Validate renderer list.

[ Top ]

Properties

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

SQL to use in load_plugins_table(). Gets overwritten for Plugins_admin.

API Tags:

Access:

protected

Redefined in descendants as:

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

[ Top ]

array $plugin_errors = array() [line 155]

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

[ Top ]

Methods

Constructor Plugins [line 161]

Plugins Plugins(
)

Constructor. Sets $plugins_path and load events.

[ Top ]

are_events_available [line 1696]

boolean are_events_available(
array|string
$events, [boolean
$require_all_in_same_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	$require_all_in_same_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 1266]

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

Call a specific plugin by its code.

This will call the Plugin::SkinTag() event handler.

Parameters:

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

[ Top ]

call_method [line 1191]

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 1246]

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().

fp> why doesn't call_method always check if it's deactivated?

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 1892]

void count_regs(

$classname 
)

Parameters:

$classname:

API Tags:

Deprecated:

by Plugins_admin::count_regs()

Redefined in descendants as:

Plugins_admin::count_regs() : Count # of registrations of same plugin.

[ Top ]

forget_events [line 646]

void forget_events(
integer
$plugin_ID 
)

Forget the events a Plugin has registered.

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

Parameters:

integer

$plugin_ID:

Plugin ID

[ Top ]

get_by_classname [line 1502]

Plugin &get_by_classname(
string
$classname 
)

Get a plugin by its classname.

Parameters:

string

$classname:

API Tags:

Return:

(false in case of error)

[ Top ]

get_by_code [line 1525]

Plugin &get_by_code(
string
$plugin_code 
)

Get a specific Plugin by its code.

Parameters:

string

$plugin_code:

plugin code

API Tags:

Return:

(false in case of error)

[ Top ]

get_by_ID [line 1457]

Plugin &get_by_ID(
integer
$plugin_ID 
)

Get a specific plugin by its ID.

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

Parameters:

integer

$plugin_ID:

plugin ID

API Tags:

Return:

(false in case of error)

[ Top ]

get_classfile_path [line 300]

string get_classfile_path(
string
$classname 
)

Get path of a given Plugin classname.

Parameters:

string

$classname:

Classname

API Tags:

Return:

Path

[ Top ]

get_enabled_events [line 1655]

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 1609]

array get_list_by_all_events(

$events 
)

Get a list of plugins that provide all given events.

Parameters:

$events:

API Tags:

Return:

plugin_ID => & Plugin

[ Top ]

get_list_by_event [line 1558]

array get_list_by_event(
string
$event 
)

Get a list of Plugins for a given event.

Parameters:

string

$event:

Event name

API Tags:

Return:

plugin_ID => & Plugin

[ Top ]

get_list_by_events [line 1584]

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:

plugin_ID => & Plugin

[ Top ]

get_next [line 797]

Plugin &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 1746]

boolean 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.

API Tags:

Return:

True, if retrieved from cache; false if not

[ Top ]

get_Plugins_in_group [line 207]

array get_Plugins_in_group(

$group 
)

Will return an array that contents are references to plugins that have the same group, regardless of the sub_group.

Parameters:

$group:

[ Top ]

get_Plugins_in_sub_group [line 229]

array get_Plugins_in_sub_group(

$group, [
$sub_group = ''] 
)

Will return an array that contents are references to plugins that have the same group and sub_group.

Parameters:

	$group:
	$sub_group:

[ Top ]

get_plugin_groups [line 182]

array get_plugin_groups(
)

Get a list of available Plugin groups.

[ Top ]

get_trigger_event [line 1009]

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

Trigger an event and return an index of params.

This is handy to collect return values from all plugins hooking an event.

Parameters:

string	$event:	Event name, see Plugins_admin::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_return [line 1044]

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

Trigger an event and return the first return value of a plugin.

Parameters:

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

API Tags:

Return:

NULL if no Plugin returned something or the return value of the first Plugin

[ Top ]

get_trigger_event_first_true [line 1027]

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_admin::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 1680]

boolean has_event(
integer
$plugin_ID, string
$event 
)

Has a plugin a specific event registered and enabled?

Parameters:

integer	$plugin_ID:
string	$event:

Information Tags:

Todo:

fp> The plugin should discover its events itself / This question should be asked to the Plugin itself. dh> Well, "discover" means to look up if it has a given method; this does not appear to belong into the Plugin class. A plugin won't also really know if some event is enabled or disabled.

[ Top ]

init_settings [line 668]

void init_settings(
Plugin
&$Plugin 
)

Init Plugin::$Settings and Plugin::$UserSettings, either by unsetting them for PHP5's overloading or instantiating them for PHP4.

This only gets used for installed plugins, but we're initing it for PHP 5.1, to trigger a helpful error, when e.g. Plugin::Settings gets accessed in PluginInit().

Parameters:

Plugin

&$Plugin:

[ Top ]

instantiate [line 1795]

Plugin &instantiate(

$row 
)

Callback, which gets used for Results.

Parameters:

$row:

API Tags:

Return:

(false in case of error)

[ Top ]

instantiate_Settings [line 704]

boolean instantiate_Settings(
Plugin
&$Plugin, string
$set_type 
)

Instantiate Settings object (class PluginSettings) for the given plugin.

The plugin must provide setting definitions (through Plugin::GetDefaultSettings() OR Plugin::GetDefaultUserSettings()).

Parameters:

Plugin	&$Plugin:
string	$set_type:	settings type: "Settings" or "UserSettings"

API Tags:

Return:

NULL, if no Settings

Information Tags:

Todo:

dh> there should be only one instance of Plugin(User)Settings, which would allow to query the DB at once. Defaults would need to be handled by Plugin(User)Settings::get_default() then.

[ Top ]

load_events [line 1715]

void load_events(
)

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

Redefined in descendants as:

Plugins_admin::load_events() : (Re)load Plugin Events for enabled (normal use) or all (admin use) plugins.
Plugins_admin_no_DB::load_events() : No-operation.

[ Top ]

load_plugins_table [line 1418]

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_admin_no_DB::load_plugins_table() : No-operation.

[ Top ]

quick [line 1361]

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

Information Tags:

Todo:

rename

[ Top ]

Plugin &register(
string
$classname, [int
$ID = 0], [int
$priority = -1], [array
$apply_rendering = NULL], [string
$classfile_path = NULL], [boolean
$must_exists = true] 
)

Register a plugin.

This handles the indexes, dynamically unregisters a Plugin that does not exist (anymore) and instantiates the Plugin's (User)Settings.

Parameters:

string	$classname:	name of plugin class to instantiate and register
int	$ID:	ID in database (0 if not installed)
int	$priority:	Priority in database (-1 to keep default)
array	$apply_rendering:	When should rendering apply? (NULL to keep default)
string	$classfile_path:	Path of the .php class file of the plugin.
boolean	$must_exists:	Must the plugin exist (classfile_path and classname)? This is used internally to be able to unregister a non-existing plugin.

API Tags:

Return:	Plugin ref to newly created plugin; string in case of error
Access:	protected

[ Top ]

render [line 1294]

string render(
string
&$content, array
$renderers, string
$format, array
$params, [
$event_prefix = 'Render'] 
)

Render the content of an item by calling the relevant renderer plugins.

Parameters:

string	&$content:	content to render (by reference)
array	$renderers:	renderer codes to use for opt-out, opt-in and lazy
string	$format:	Output format, see format_to_output(). Only 'htmlbody', 'entityencoded', 'xml' and 'text' are supported.
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.
	$event_prefix:

API Tags:

Return:

rendered content

[ Top ]

restart [line 781]

void restart(
)

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

[ Top ]

set_apply_rendering [line 1909]

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
Deprecated:	by Plugins_admin::set_apply_rendering()

Redefined in descendants as:

Plugins_admin::set_apply_rendering() : Set the apply_rendering value for a given Plugin ID.

[ Top ]

set_Plugin_status [line 260]

boolean 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 unregistered, 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")

API Tags:

Return:

True on success, false on failure.

[ Top ]

stop_propagation [line 830]

void stop_propagation(
)

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

[ Top ]

trigger_collect [line 1066]

array trigger_collect(
string
$event, [array
$params = NULL], [boolean
$ignore_empty = true] 
)

Trigger an event and return an array of all return values of the relevant plugins.

Parameters:

string	$event:	Event name, see Plugins_admin::get_supported_events()
array	$params:	Associative array of parameters for the Plugin
boolean	$ignore_empty:	Ignore empty() return values?

API Tags:

Return:

List of return values, indexed by Plugin ID

[ Top ]

trigger_event [line 843]

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

Call all plugins for a given event.

Parameters:

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

API Tags:

Return:

True, if at least one plugin has been called.

[ Top ]

trigger_event_first_false [line 914]

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 Plugins_admin::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 954]

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

Call all plugins for a given event, until the first one returns a value (not NULL) (and $search is fulfilled, if given).

Parameters:

string	$event:	event name, see Plugins_admin::get_supported_events()
array\|NULL	$params:	Associative array of parameters for the Plugin
array\|NULL	$search:	If provided, the return value gets checks against this criteria. Can be: ( 'in_array' => 'needle' )

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 879]

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 Plugins_admin::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 1097]

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 ]

unregister [line 596]

boolean unregister(
Plugin
&$Plugin, [boolean
$force = false] 
)

Un-register a plugin.

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

Parameters:

Plugin	&$Plugin:
boolean	$force:	Force unregistering (ignored here, but used in Plugins_admin)

API Tags:

Return:

True, if unregistered

Redefined in descendants as:

Plugins_admin::unregister() : Un-register a plugin, only if forced.

[ Top ]

validate_list [line 1923]

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 of renderer codes
Deprecated:	by Plugins_admin::validate_renderer_list()

[ Top ]

validate_renderer_list [line 1807]

array validate_renderer_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 of renderer codes

[ Top ]

Multilingual multiuser multiblog engine

Class: Plugins

Class Plugins

Packages

Classes

Files