From ea6d989c5f76831ecc264ca18f34edaf590e2fbe Mon Sep 17 00:00:00 2001 From: Pierrick Le Gall Date: Sat, 29 Apr 2023 17:16:50 +0200 Subject: [PATCH] copy of the page from DokuWiki --- Plugin-developpement.md | 201 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 201 insertions(+) create mode 100644 Plugin-developpement.md diff --git a/Plugin-developpement.md b/Plugin-developpement.md new file mode 100644 index 0000000..1eaf4a6 --- /dev/null +++ b/Plugin-developpement.md @@ -0,0 +1,201 @@ +# Plugin developpement + +Plugins are designed to extend the Piwigo features. + +You will find in the +[Skeleton](https://github.com/Piwigo/Piwigo-Skeleton) a good bootstrap for you plugin. + +## Plugin architecture + +A plugin can hook into the core of Piwigo by registering **event +handlers** with Piwigo. An **event handler** is nothing more than a +function that Piwigo will call. + +``` php +register_event_handler('delete_user', 'my_action_on_delete_user'); +``` + +In this case, 'delete_user' is the name of the event to which the plugin +will hook. Piwigo will automatically call your function when a user is +deleted. + +Piwigo will trigger **notices** and **changes**. The only difference +from a coding perspective is that you are required to return a value in +the case of an event (this return value will be used later by Piwigo). + +An example of **trigger_notify** is 'delete_user' or 'delete_elements'. +Your plugin can take any required actions when a user is deleted by +registering an event handler for 'delete_user'. While handling actions +you are not expected to directly return a value that will be used by +Piwigo, but you can modify any global variable in order to change the +general behaviour. + +An example of **trigger_change** is 'render_user_comment_content'. +Piwigo will give in input the raw content of a comment, you can modify +it at your will (for example allow bbcode or add smilies) and return the +value: + +``` php +register_event_handler('render_user_comment_content', 'my_function'); +function my_function($content) +{ + $content = str_replace(':)', ':)', $content); + return $content; //<-- NOTE: this is how you return the value to Piwigo +} +``` + +A complete reference of core triggers is available at +**tools/triggers_list.php** into your Piwigo installation, or +[here](http://piwigo.us/dev/mistic100/triggers) (not always up to date). + +## Taxonomy of a plugin + +The minimal plugin is a file called main.inc.php (in the directory +plugins/my_plugin if your plugin is called my_plugin). It MUST have the +header below: + +``` php + +``` + +Note that the version number is saved into database, so keep it short +and in a good style ( 1.1 or 1.a.b ...) + +## DO and DONT + +While nobody will impose a coding standard here are some things you +should consider: + +### Name collisions + +PHP does not allow several function names to be defined at the same +time. Keep in mind that your plugin will need to work with other plugins +activated, as well as the core of Piwigo, so please avoid function names +such as 'send', 'delete', 'delete_user'... You have two options: + +A. Prefix function names with something unique: +'download_multi_delete_user', 'download_multi_delete_elements', etc... + +B. Use objects and classes + +``` php +// static EXAMPLE +class MyClass +{ + function on_delete_user() { ... } +} +add_event_handler('delete_user', array('MyClass', 'on_delete_user')); + +// object EXAMPLE +class MyClass +{ + function on_delete_user() { ... } +} + +$myObj = new MyClass(); +add_event_handler('delete_user', array(&$myObj, 'on_delete_user') ); +``` + +### Extensions compatibility + +If your plugin adds or load custom tpl, to the public part, you should +let to the theme the ability to define their own tpl file. If your +plugin defines a new index page, like *index.php?/xxxx*, +`$page['title']`, `$page['body_id']` and `$page['section']` needs to be +defined with custom values by the plugin, using the +**loc_end_section_init** trigger. This is useful for other plugins and +themes, in order to declare what type of page is currently running. + +### Code size + +When Piwigo loads the plugins, it will include every main.inc.php. Don't +put in your main.inc.php 3000 lines of code just to add a page on the +administration menu. Split you main.inc.php in several files and feel +free to add include_once inside functions defined in main.inc.php as +much as you want. + +Also use the lazy loading feature of **add_event_handler** (Piwigo 2.7 +and above) + +``` php +// without lazy loading, necessary code is loaded immediately +include_once(SKELETON_PATH . 'include/events.inc.php'); + +add_event_handler('rare_trigger', 'my_function'); + +// with lazy loading, code loaded only id needed +add_event_handler('rare_trigger', 'my_function', 50, + SKELETON_PATH . 'include/events.inc.php'); +``` + +### Do not 'die()' + +If you call functions such as die or exit within your plugin, keep in +mind that the final user will have no other choice than modify his +config file so that no plugin is loaded or modify the #plugins table (if +he knows that the cause is your plugin). So please whenever something is +wrong, the plugins should display a message for the administrators and +silently do nothing. + +### What can be done when main.inc.php is executed ? + +Piwigo will include main.inc.php at some point during the +initialization. At this time, do not make any assumption that the user +is logged in, the language is defined, the template is created, etc. The +only safe assumptions are: + +- the connection to the database has been established +- the configuration has been loaded +- you can safely call add_event_handler, remove_event_handler. For all + other cases, you must hook the event 'init'. The 'init' event is + triggered only once and at that point the common initialization of + the current page is finished + +## Plugin maintenance + +When a plugin is installed, activated, deactivated or uninstalled, +Piwigo will allow you to take some special steps by executing some php +code. If you have a php file named **maintain.inc.php** or +**maintain.class.php** in your plugin directory, Piwigo will include +this file and will call some maintenance functions. + +#### Piwigo 2.7 and above + +Maintenance functions have to be declared in **maintain.class.php** by +class extending **PluginMaintain** : + +``` php +/** + * PLUGINID must be replaced by the directory name of your plugin + */ +class PLUGINID_maintain extends PluginMaintain +{ + function install($plugin_version, &$errors=array()) { ... } + function activate($plugin_version, &$errors=array()) { ... } + function update($old_version, $new_version, &$errors=array()) { ... } + function deactivate() { ... } + function uninstall() { ... } +} +``` + +#### Piwigo 2.6 and bellow + +Maintenance functions are declared in **maintain.inc.php** and are all +optional : + +``` php +function plugin_install($plugin_id, $plugin_version, &$errors) { ... } +function plugin_activate($plugin_id, $plugin_version, &$errors) { ... } +function plugin_deactivate($plugin_id) { ... } +function plugin_uninstall($plugin_id) { ... } +``` \ No newline at end of file