Class: Plugins_admin

Source Location: /qp_inc/plugins/model/_plugins_admin.class.php

Class Plugins_admin

Class Overview

A Plugins object that loads all Plugins, not just the enabled ones.

This is needed for the backoffice plugin management.

This extends the basic Plugins by adding all the functionnality needed for administering plugins in addition to just using the already enabled plugins.

Located in /qp_inc/plugins/model/_plugins_admin.class.php [line 40]

Plugins
   |
   --Plugins_admin

Properties

$sql_load_plugins_table

Methods

[ Top ]

Descendants

Child Class	Description
Plugins_admin_no_DB	A sub-class of Plugins_admin which will not load any DB info (i-e: Plugins and Events).

[ Top ]

Inherited Properties, Constants, and Methods

Inherited Properties

Inherited Methods

Inherited Constants

Inherited From Plugins

Plugins::$plugin_errors

Inherited From Plugins

Plugins::Plugins()

Constructor. Sets $plugins_path and load events.

Plugins::are_events_available()

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

Plugins::call_by_code()

T-Tag: Call a specific plugin by its code.

Plugins::call_method()

Call a method on a Plugin.

Plugins::call_method_if_active()

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

Plugins::forget_events()

Forget the events a Plugin has registered.

Plugins::get_by_classname()

Get a plugin by its classname.

Plugins::get_by_code()

Get a specific Plugin by its code.

Plugins::get_by_ID()

Get a specific plugin by its ID.

Plugins::get_enabled_events()

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

Plugins::get_list_by_all_events()

Get a list of plugins that provide all given events.

Plugins::get_list_by_event()

Get a list of Plugins for a given event.

Plugins::get_list_by_events()

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

Plugins::get_next()

Get next plugin in the list.

Plugins::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.

Plugins::get_Plugins_in_group()

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

Plugins::get_Plugins_in_sub_group()

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

Plugins::get_plugin_groups()

Get a list of available Plugin groups.

Plugins::get_trigger_event()

Trigger an event and return an index of params.

Plugins::get_trigger_event_first_return()

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

Plugins::get_trigger_event_first_true()

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

Plugins::has_event()

Has a plugin a specific event registered and enabled?

Plugins::init_settings()

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

Plugins::instantiate()

Callback, which gets used for Results.

Plugins::instantiate_Settings()

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

Plugins::load_events()

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

Plugins::load_plugins_table()

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

Plugins::quick()

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

Plugins::register()

Register a plugin.

Plugins::render()

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

Plugins::restart()

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

Plugins::set_Plugin_status()

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

Plugins::stop_propagation()

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

Plugins::trigger_collect()

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

Plugins::trigger_event()

Call all plugins for a given event.

Plugins::trigger_event_first_false()

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

Plugins::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).

Plugins::trigger_event_first_true()

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

Plugins::trigger_karma_collect()

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

Plugins::unregister()

Un-register a plugin.

Plugins::validate_renderer_list()

Validate renderer list.

[ Top ]

Property Summary

mixed

$sql_load_plugins_table

Load all plugins (not just enabled ones).

[ Top ]

Method Summary

int\|array	count_regs()	Count # of registrations of same plugin. Optionally returns the sequence number to be used for the next instance of a plugin as well.
void	discover()	Discover and register all available plugins in the $plugins_path folder/subfolders.
string	filter_contents()	Filter (post) contents by calling the relevant filter plugins.
array	get_apply_rendering_values()	Get the list of all possible values for apply_rendering (defines when a rendering Plugin can apply).
array	get_registered_events()	Discover plugin events from its source file.
array	get_supported_events()	Get the list of all events/hooks supported by the plugin framework.
Plugin	&install()	Install a plugin into DB.
void	load_events()	(Re)load Plugin Events for enabled (normal use) or all (admin use) plugins.
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.
boolean\|integer	set_priority()	Set the priority for a given Plugin ID.
void	sort()	Sort the list of plugins.
void	sort_Plugin_group()	Callback function to sort plugins by group, sub-group and name.
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).
string	unfilter_contents()	UnFilter (post) contents by calling the relevant filter plugins.
boolean	uninstall()	Uninstall a plugin.
boolean	unregister()	Un-register a plugin, only if forced.
array	validate_dependencies()	Validate dependencies of a Plugin.

[ Top ]

Properties

mixed $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
ORDER BY plug_priority, plug_classname' [line 45]

Load all plugins (not just enabled ones).

Redefinition of:

Plugins::$sql_load_plugins_table: SQL to use in load_plugins_table(). Gets overwritten for Plugins_admin.

[ Top ]

Methods

count_regs [line 299]

int|array count_regs(
string
$classname, [boolean
$get_seq_number = false] 
)

Count # of registrations of same plugin. Optionally returns the sequence number to be used for the next instance of a plugin as well.

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

Parameters:

string	$classname:	class name
boolean	$get_seq_number:	Return next sequence number as well (will be 1 if there are no other instances of this plugin).

API Tags:

Return:

# of regs or array( $regs, $next_seq_number ) if $get_seq_number is true

[ Top ]

discover [line 333]

void discover(
)

Discover and register all available plugins in the $plugins_path folder/subfolders.

[ Top ]

filter_contents [line 1421]

string filter_contents(
string
&$title, array
&$content, 
$renderers 
)

Filter (post) contents by calling the relevant filter plugins.

Works very much like render() except that it's called at insert/update time and BEFORE validation. Gives an opportunity to do some serious cleanup on what the user has typed.

This uses the lost of renderers, because filtering may need to work in conjunction with rendering, e-g: code display: you want to filter out tags before validation and later you want to render color/fixed font. For brute force filtering, use 'always' or 'stealth' modes.

Parameters:

string	&$title:	content to render (by reference)
array	&$content:	renderer codes to use for opt-out, opt-in and lazy
	$renderers:

API Tags:

Return:	rendered content
See:	Plugins::render()

[ Top ]

get_apply_rendering_values [line 394]

array get_apply_rendering_values(
[boolean
$with_desc = false] 
)

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

Parameters:

boolean

$with_desc:

Return an associative array with description for the values?

Information Tags:

Todo:

Add descriptions.

[ Top ]

get_registered_events [line 428]

array get_registered_events(

$Plugin 
)

Discover plugin events from its source file.

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

Parameters:

$Plugin:

Information Tags:

Todo:

Extend to get list of defined classes and global functions and check this list before sourcing/including a Plugin! (prevent fatal error)

[ Top ]

get_supported_events [line 88]

array get_supported_events(
)

Get the list of all events/hooks supported by the plugin framework.

Also puts in additional events provided by plugins. fp> please provide an example/use case

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
BeforeEnable
BeforeDisable
BeforeInstall
BeforeUninstall
BeforeUninstallPayload
DisplayTemplate (called on a template from GetProvidedTemplates())
ExecCronJob
GetDefaultSettings
GetDefaultUserSettings
GetExtraEvents
GetSrvcMethods
PluginInit
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)
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)

[ Top ]

install [line 504]

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

Install a plugin into DB.

NOTE: this won't install necessary DB changes and not trigger Plugin::AfterInstall!

Parameters:

string	$classname:	Classname of the plugin to install
string	$plug_status:	Initial DB Status of the plugin ("enabled", "disabled", "needs_config", "broken")
string	$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 ]

load_events [line 705]

void load_events(
)

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

This is the same as Plugins::load_events() except that it loads all Plugins (not just enabled ones)

Redefinition of:

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

Redefined in descendants as:

Plugins_admin_no_DB::load_events() : No-operation.

[ Top ]

save_events [line 734]

boolean save_events(
Plugin
$Plugin, [array
$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	$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 857]

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

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

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_priority [line 1009]

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

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_group [line 1119]

void sort_Plugin_group(

&$a_ID, 
&$b_ID 
)

Callback function to sort plugins by group, sub-group and name.

Those, which have a group get sorted above the ones without one.

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_name [line 1103]

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

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 ]

unfilter_contents [line 1476]

string unfilter_contents(
string
&$title, string
&$content, array
$renderers 
)

UnFilter (post) contents by calling the relevant filter plugins.

This is the opposite of filter_content. It is used to restore some specifcs before editing text. For example, this can be used to replace complex sequences of tags with a custome meta-tag, e-g: <strong> can become <s> for convenient editing.

This uses the list of renderers, because un/filtering may need to work in conjunction with rendering, e-g: code display: you want to filter in/out tags before validation and later you want to render color/fixed font. For brute force unfiltering, use 'always' or 'stealth' modes.

Parameters:

string	&$title:	title to render (by reference)
string	&$content:	content to render (by reference)
array	$renderers:	renderer codes to use for opt-out, opt-in and lazy

API Tags:

Return:	rendered content
See:	Plugins::render()
See:	Plugins::filter()

Information Tags:

Todo:

fp> it would probably make sense to do the unfiltering in reverse order compared to filtering

[ Top ]

uninstall [line 649]

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

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

Un-register a plugin, only if forced.

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

Parameters:

Plugin	&$Plugin:
boolean	$force:	Force unregistering

API Tags:

Return:

True, if unregistered

Redefinition of:

Plugins::unregister(): Un-register a plugin.

[ Top ]

validate_dependencies [line 1158]

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 ]

hic sunt dracones

	plugins

[ class tree: plugins ] [ index: plugins ] [ all elements ]