Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
| en:entwickler:plugin_manager [2026/02/01 16:51] – [Main plugin file] mightymcoder | en:entwickler:plugin_manager [2026/10/23 23:22] (current) – kainhofer | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| ========= Plugin Manager ========= | ========= Plugin Manager ========= | ||
| - | {{ : | ||
| - | The Plugin Manager module provides a simple user interface and standardized procedures for | ||
| - | * installing, | ||
| - | * uninstalling, | ||
| - | * updating, | ||
| - | * managing and | ||
| - | * integrating | ||
| - | plugins in Admidio. | ||
| - | ======== Make your plugin compatible with the Plugin Manager | + | The Plugin Manager |
| - | To make your plugin compatible with the Plugin Manager certain requirements must first be met. These include: | + | and what has to happen to move them from one state to the next. It provides |
| - | * [[en: | + | |
| - | * A consistent [[en: | + | |
| - | * A [[en: | + | |
| - | * A [[en: | + | |
| - | * A JSON [[en: | + | |
| - | ======= Naming conventions ======= | + | * a **plugin administration** page under //Administration → Extensions// for installing, enabling, disabling, updating and removing plugins, |
| - | To use the new PluginManager some naming conventions must be observed: | + | |
| - | - For better readability file and folder names containing multiple words should follow snake_case (underscore separated) notation. | + | * an **upload** for a plugin that arrives as a ZIP archive, |
| - | - All folder and file names containing multiple words and are placed inside the //classes// folder should follow UpperCamelCase (PascalCase) notation. | + | * a **runtime** that loads the enabled plugins into every request, and |
| - | | + | * a set of **admidio |
| - | ======= Folder structure ======= | + | |
| - | The basic folder structure | + | |
| - | {{: | + | |
| - | ====== classes folder ====== | + | <WRAP center round important 80%> |
| - | ===== Presenter classes ===== | + | This page describes |
| - | ==== Plugin-specific classes ==== | + | that was introduced for Admidio 5.0 and is not compatible with it — see |
| - | Inside | + | [[en: |
| + | </WRAP> | ||
| - | ==== Plugin preferences class ==== | + | A complete, commented example plugin is part of the Admidio distribution: |
| - | === Single FormPresenter element === | + | **plugins/hello-world/**. It shows every convention in one place, each of them usable on its own, |
| - | If the plugin provides preferences there should be a class //" | + | and its own ``README.md`` is the short form of this page. Copy that directory, rename it, and you |
| + | have a working plugin. | ||
| - | | + | ======= What a plugin is ======= |
| - | Below is an example snippet of the // | + | A plugin |
| - | < | + | file **plugin.php**. Nothing else is required. A plugin that only registers a hook is exactly those |
| - | public static function createBirthdayForm(Smarty $smarty): string | + | two files: no class, no base class, no interface, no settings, no page and no language file. |
| - | { | + | |
| - | global $gL10n, $gCurrentSession; | + | |
| - | $pluginBirthday = Birthday:: | + | The **directory name is the plugin ID** and the only identity a plugin ever has. It is used in |
| - | | + | preference names, in URLs and in the components table, so it must consist of lowercase letters, |
| + | digits and single hyphens | ||
| + | duplicated by another plugin without any consequence. | ||
| - | $formBirthday | + | ====== Folder structure ====== |
| - | ' | + | |
| - | $pluginBirthday:: | + | |
| - | SecurityUtils:: | + | |
| - | null, | + | |
| - | array(' | + | |
| - | ); | + | |
| - | $selectBoxEntries = array( | + | <code text> |
| - | ' | + | plugins/ |
| - | ' | + | ├── plugin.json |
| - | ' | + | ├── plugin.php |
| - | ); | + | ├── cli.php |
| + | ├── modules/ | ||
| + | ├── src/ | ||
| + | ├── languages/ | ||
| + | ├── templates/ | ||
| + | ├── assets/ | ||
| + | ├── db_scripts/ | ||
| + | └── tests/ | ||
| + | </ | ||
| - | $formBirthday-> | + | None of the subdirectories has to exist and **none of them has to be declared** in the manifest. |
| - | ' | + | They are conventions the core looks for. |
| - | Language:: | + | |
| - | $selectBoxEntries, | + | |
| - | array( | + | |
| - | ' | + | |
| - | ' | + | |
| - | ' | + | |
| - | ) | + | |
| - | ); | + | |
| - | $formBirthday-> | + | ====== Naming conventions ====== |
| - | ' | + | |
| - | Language:: | + | |
| - | $formValues[' | + | |
| - | array(' | + | |
| - | ); | + | |
| - | [...] | + | - Folder and file names containing multiple words use **// |
| + | - Class files below the autoload directory (conventionally //src//) use **// | ||
| + | - The plugin ID — the directory name — is lowercase letters, digits and single hyphens. | ||
| - | $formBirthday-> | + | ======= The manifest ======= |
| - | ' | + | |
| - | $gL10n-> | + | |
| - | array(' | + | |
| - | ); | + | |
| - | $formBirthday-> | + | Each plugin has to provide a JSON manifest **plugin.json**. Only ``name`` and ``version`` really |
| - | | + | matter to the core; everything else is optional. A manifest that cannot be read, is not valid JSON |
| - | | + | or declares no version makes the plugin **broken**: it is still listed and can still be removed, but |
| + | it is never loaded and cannot be installed. | ||
| + | |||
| + | ^ Key ^ Mandatory ^ Description ^ | ||
| + | | ``name`` | X | Display name. May be a language string ID such as ``PLG_BIRTHDAY_PLUGIN_NAME``. | | ||
| + | | ``version`` | X | Version of the files. Compared against the installed version to detect an update. | | ||
| + | | ``description`` | | Short description shown in the plugin administration. May be a language string ID. | | ||
| + | | ``author`` | | The author of the plugin. | | ||
| + | | ``url`` | | A URL to a wiki page or a project page. | | ||
| + | | ``icon`` | | Bootstrap icon name, e.g. ``bi-cake2``. | | ||
| + | | ``menu`` | | ``false`` suppresses the menu entry below // | ||
| + | | ``requires`` | | Version constraints and dependencies, | ||
| + | | ``autoload`` | | PSR-4 mappings, as namespace prefix => directory inside the plugin. | | ||
| + | | ``preferences`` | | Where the settings panel of the plugin appears: ``section`` and ``sequence``. | | ||
| + | | ``settings`` | | The preferences the plugin owns. | | ||
| + | |||
| + | A manifest may carry further keys of its own; they are kept and are readable through | ||
| + | ``$plugin->manifest``. | ||
| + | |||
| + | ====== requires ====== | ||
| + | |||
| + | <code json> | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| } | } | ||
| </ | </ | ||
| + | A constraint is a **space separated list of terms that all have to match**, e.g. ``>=5.1 <6.0``. | ||
| + | A term is an operator (``>=``, ``>``, ``<=``, ``<``, ``=``, ``!=``) followed by a version; a term | ||
| + | without an operator means ``>=``. | ||
| - | === Multiple FormPresenter elements === | + | ``admidio``, |
| - | With Admidio 5 the preference page has been redesigned. It is now possible to display multiple " | + | plugin broken, so it cannot |
| - | In your PluginPreferencePresenter class you can now define multiple FormPresenter elements and add different preferences | + | ``modules`` is deliberately **not** a requirement. A switched-off Admidio module is neither the |
| + | plugin' | ||
| + | switched on again. The plugin administration therefore tells the administrator about it instead of | ||
| + | refusing | ||
| + | ``photos``, ``messages``), | ||
| - | < | + | ====== autoload ====== |
| - | public static function createBirthdayForm(Smarty $smarty): string | + | |
| + | < | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | The prefix must **not** start with ``Admidio\``, | ||
| + | shadowed, and the directory has to stay inside the plugin directory. Both are verified when the | ||
| + | manifest is read; a violation makes the plugin broken. | ||
| + | |||
| + | ====== preferences ====== | ||
| + | |||
| + | <code json> | ||
| + | " | ||
| + | </ | ||
| + | |||
| + | ``section`` names one of the preference tabs and ``sequence`` places the panel inside it. The tabs | ||
| + | are ``system``, ``login_security``, | ||
| + | ``overview_extensions`` and ``extensions``. A plugin is not restricted to the last two: a module that | ||
| + | used to be part of the Admidio core keeps its own tab once it becomes a plugin. A plugin that names | ||
| + | no section, or one that no longer exists, lands in ``extensions``. | ||
| + | |||
| + | ====== settings ====== | ||
| + | |||
| + | The ``settings`` object declares the preferences the plugin owns. They become **ordinary Admidio | ||
| + | preferences** when the plugin is loaded, get a row in every organization when it is installed and are | ||
| + | removed again when it is uninstalled. | ||
| + | |||
| + | Each setting declares a ``type`` | ||
| + | ``default``, | ||
| + | Admidio to **build the settings form by itself**, so a plugin only writes a preferences presenter | ||
| + | when it wants more than the manifest can express. | ||
| + | |||
| + | A setting **without** a ``label`` is not put into that form. A preference the plugin owns is not | ||
| + | necessarily one this form edits — the position of an overview widget is edited in the overview | ||
| + | preferences, | ||
| + | |||
| + | An ``enum`` lists its permitted values, and may instead name them so that the generated form has | ||
| + | something readable to show: | ||
| + | |||
| + | <code json> | ||
| + | " | ||
| + | " | ||
| + | </ | ||
| + | |||
| + | An ``integer`` may bound what the generated form offers with ``min``, ``max`` and ``step``. The | ||
| + | value is stored as an integer either way; a bound only restricts the input field. | ||
| + | |||
| + | <code json> | ||
| + | " | ||
| + | </ | ||
| + | |||
| + | Three preference names are conventions the core understands: | ||
| + | |||
| + | ^ Preference ^ Meaning ^ | ||
| + | | ``plugin_< | ||
| + | | ``< | ||
| + | | ``< | ||
| + | |||
| + | In ``< | ||
| + | |||
| + | ====== A complete manifest ====== | ||
| + | |||
| + | <code json> | ||
| { | { | ||
| - | | + | |
| - | + | | |
| - | | + | |
| - | ' | + | " |
| - | | + | " |
| - | | + | " |
| - | null, | + | " |
| - | | + | |
| - | | + | " |
| - | | + | }, |
| - | | + | " |
| - | ' | + | |
| - | ' | + | |
| - | ); | + | |
| - | $formBirthday-> | + | |
| - | | + | " |
| - | | + | " |
| - | | + | " |
| - | | + | " |
| - | ); | + | |
| - | + | | |
| - | [...] | + | " |
| - | + | " | |
| - | $formBirthday-> | + | " |
| - | | + | " |
| - | | + | " |
| - | | + | " |
| - | ); | + | }, |
| - | + | " | |
| - | | + | " |
| - | | + | |
| - | + | | |
| - | [...] | + | " |
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | | ||
| + | } | ||
| </ | </ | ||
| - | Now you can define a new FormPresenter for the second " | + | ======= The entry file ======= |
| + | |||
| + | **plugin.php** registers what the plugin contributes and returns nothing. There is **no plugin | ||
| + | class, no interface and no base class**. It runs inside the fully initialized Admidio request, so it | ||
| + | can call any public Admidio API — normally it registers hooks: | ||
| <code php> | <code php> | ||
| - | $formBirthday2= new FormPresenter( | + | <?php |
| - | ' | + | use Admidio\Hooks\Hooks; |
| - | | + | use AdmidioPlugin\HelloWorld\Greeting; |
| - | | + | |
| - | | + | /* |
| - | array('class' => ' | + | * This file is included by the plugin |
| - | | + | * Admidio bootstrap it could do nothing anyway; the guard only turns a PHP error into a message. |
| - | + | */ | |
| - | [...] | + | if (realpath($_SERVER['SCRIPT_FILENAME'] ?? '' |
| - | + | exit('This page may not be called directly!'); | |
| - | $formBirthday2-> | + | } |
| - | | + | |
| - | $gL10n-> | + | Hooks:: |
| - | array(' | + | |
| - | | + | |
| - | + | ||
| - | [...] | + | |
| </ | </ | ||
| - | This form cannot be added to smarty with the // | + | A plugin with more to announce puts that into a class of its own and calls it from the entry file, |
| + | which is what the built-in plugins do: | ||
| <code php> | <code php> | ||
| - | [...] | + | use AdmidioPlugin\Birthday\Birthday; |
| - | + | ||
| - | | + | Birthday:: |
| - | $gCurrentSession-> | + | |
| - | + | ||
| - | [..] | + | |
| </ | </ | ||
| - | You can add as many forms as you like using this method. | + | The entry file is included in a scope of its own, so a variable it assigns cannot collide with |
| + | anything in the loader. Top-level code should stay cheap: it runs in **every request** of every | ||
| + | organization the plugin is enabled for. | ||
| - | When all forms are added to smarty you can use a " | + | ====== What loading a plugin means ====== |
| + | |||
| + | Loading one plugin means four things and nothing else: | ||
| + | |||
| + | - its ``autoload`` mappings become resolvable classes, | ||
| + | - its **languages/ | ||
| + | - its ``settings`` and the preference that enables it are registered as ordinary Admidio preferences, | ||
| + | - its **plugin.php** is included once. | ||
| + | |||
| + | A plugin that fails while it is being loaded is **reported and skipped**. A broken extension must not | ||
| + | be able to take the whole installation down, because then it could not be disabled any more. This is | ||
| + | the opposite of the policy for hooks, where a failing callback fails the operation it extends: an | ||
| + | operation | ||
| + | |||
| + | ======= Hooks ======= | ||
| + | |||
| + | Hooks are the general extension mechanism of Admidio and the normal way for a plugin to change what | ||
| + | the core does. Three primitives are offered by ``Admidio\Hooks\Hooks``: | ||
| + | |||
| + | ^ Primitive ^ Purpose ^ Dispatch ^ | ||
| + | | **Action** | Notify that something is happening or has happened. Every callback is called, return values are ignored. | ``Hooks:: | ||
| + | | **Filter** | Transform a value. Every callback receives the result of the previous one. | ``Hooks:: | ||
| + | | **Resolver** | Ask for one answer. Callbacks are asked in priority order until one returns something other than ``null``. | ``Hooks::resolve()`` | | ||
| <code php> | <code php> | ||
| - | [...] | + | // transform a value |
| - | + | Hooks:: | |
| - | | + | |
| - | $cards = array( | + | }); |
| - | array('title' | + | |
| - | array(' | + | // observe an event |
| + | Hooks:: | ||
| + | |||
| + | // ask for one answer | ||
| + | Hooks:: | ||
| + | </ | ||
| + | |||
| + | A lower priority runs earlier, registrations of the same priority run in registration order. A | ||
| + | callback may be registered with an explicit ID — the last argument in the examples on this page is | ||
| + | the plugin ID — which is unique within one hook regardless of the priority, so registering the same | ||
| + | ID again replaces the previous registration. Exceptions of a callback are logged and rethrown: a | ||
| + | failing extension fails the operation it extends instead of leaving it half done. | ||
| + | |||
| + | ======= The overview widget ======= | ||
| + | |||
| + | The overview page used to include one PHP file per plugin through a Smarty function, so a plugin | ||
| + | could only contribute there by being a file at a place the core knew. **A widget is now an ordinary | ||
| + | hook**: the overview asks for the widgets, and every plugin that wants one adds it. | ||
| + | |||
| + | A plugin that follows the Admidio conventions — one widget, an ``_overview_sequence`` preference for | ||
| + | its position and a ``_plugin_enabled`` preference for who may see it — does not write that hook | ||
| + | itself but calls ``PluginWidget:: | ||
| + | |||
| + | <code php> | ||
| + | PluginWidget:: | ||
| + | ' | ||
| + | )); | ||
| + | </code> | ||
| + | |||
| + | ^ Option ^ Default ^ | ||
| + | | ``name`` | The name of the plugin, translated if it is a language string ID | | ||
| + | | ``icon`` | The icon of the plugin | | ||
| + | | ``sequencePreference`` | ``< | ||
| + | | ``enabledPreference`` | ``< | ||
| + | | ``sequence`` | Position of a widget whose preference has no value | | ||
| + | |||
| + | The render callback receives the overview page and the plugin and returns the HTML of the widget, or | ||
| + | an empty string for a widget that has nothing to show. ``PluginWidget:: | ||
| + | of the plugin | ||
| + | |||
| + | The **declaration** is what the overview preferences list, so a widget that is switched off is still | ||
| + | shown there and can be switched on again. | ||
| + | |||
| + | A plugin that needs more control adds the hook itself: | ||
| + | |||
| + | <code php> | ||
| + | Hooks:: | ||
| + | global $gValidLogin, $gL10n; | ||
| + | |||
| + | if (!$gValidLogin) { | ||
| + | | ||
| + | } | ||
| + | |||
| + | $plugin = PluginRegistry:: | ||
| + | $widgets[] = array( | ||
| + | | ||
| + | | ||
| + | | ||
| + | ' | ||
| ); | ); | ||
| - | | + | |
| - | $smarty-> | + | |
| - | | + | }); |
| - | } | + | |
| </ | </ | ||
| - | The corresponding wrapper template is shown below: | + | ======= |
| - | <code smarty> | + | A plugin that brings preferences shows them in the Admidio preferences, |
| - | {foreach $cards as $index => $card} | + | names. It used to get there by being **scanned for**: the core looked through the autoload |
| - | < | + | directories for a file called ``*PreferencesPresenter.php`` and guessed the method to call from its |
| - | < | + | class name. **A panel is now declared**, like a widget, so that a plugin says what it offers instead |
| - | < | + | of the core deducing it from file names. |
| - | {include | + | |
| - | </ | + | For a plugin whose form is generated from the manifest, the manifest is all there is: |
| - | </div> | + | |
| - | {/foreach} | + | <code json> |
| + | " | ||
| </ | </ | ||
| - | This template creates cards for each form element defined in the //$cards// variable and loads the corresponding template file. It is necessary to pass the index of the zero-based | + | A plugin that builds its form itself registers |
| - | These are: | + | |
| - | * // | + | <code php> |
| - | * // | + | Hooks:: |
| - | * // | + | PluginPanel:: |
| - | * // | + | static function (array |
| - | * // | + | global $gL10n; |
| + | |||
| + | $panels[] = array( | ||
| + | ' | ||
| + | ' | ||
| + | ' | ||
| + | ' | ||
| + | ' | ||
| + | ); | ||
| + | |||
| + | return $panels; | ||
| + | }, | ||
| + | PluginPanel:: | ||
| + | 1, | ||
| + | $plugin-> | ||
| + | ); | ||
| + | </code> | ||
| + | |||
| + | The panel takes its section | ||
| + | only a plugin that declares | ||
| + | |||
| + | The ``create`` callback receives the ``PreferencesPresenter`` and returns the HTML of the panel. It | ||
| + | is only called for the panel the administrator actually opens, because the preferences page fetches | ||
| + | one panel per request. | ||
| + | |||
| + | The settings of a plugin are additionally reachable as a dialog from the plugin administration | ||
| + | itself, so a plugin does not have to be found in the preferences tabs to be configured. | ||
| + | |||
| + | ======= Pages ======= | ||
| - | This following example shows a possible implementation | + | **modules/ |
| + | ``admFuncVariableIsValid()``, ``PagePresenter``, | ||
| + | ``handleException()``. Nothing about it is plugin-specific. | ||
| - | <code smarty> | + | Only the files **directly below** ``modules/ |
| - | <form {foreach $attributes[$dataIndex] as $attribute} | + | recursively, |
| - | | + | the entry file, the classes below ``src/`` — is refused if it is requested directly. |
| - | {/foreach}> | + | |
| - | {include ' | + | A page is always reachable at its real location: |
| - | {include ' | + | |
| - | {include ' | + | |
| - | {include ' | + | |
| - | {include ' | + | |
| - | {include ' | + | |
| - | {include ' | + | |
| - | {include ' | + | |
| - | {include ' | + | |
| - | {include ' | + | |
| - | {include ' | + | |
| - | {include ' | + | |
| - | {include ' | + | |
| - | {include ' | + | |
| - | {include ' | + | |
| - | | + | <code text> |
| - | </form> | + | plugins/hello-world/ |
| - | {$javascript[$dataIndex]} | + | |
| </ | </ | ||
| - | This makes it possible to show seperate forms on the same page. There are no limits to the display options whether as cards (as in the example), tabs, or accordions. With this approach each available Bootstrap/ | + | When the administrator switches |
| + | publishes it under the ordinary module URL: | ||
| - | ===== Entity, Service | + | <code text> |
| - | If the plugin | + | modules/ |
| + | </ | ||
| + | |||
| + | Admidio has no front controller and no rewrite rules — every module URL is a real file — so | ||
| + | publishing writes one generated stub per page, which loads the Admidio bootstrap and hands over to | ||
| + | the page inside the plugin. The page itself is unchanged and works through either URL, because | ||
| + | ``__DIR__`` is per file: the relative includes of the page still resolve against its real location. | ||
| + | Because this writes into the Admidio core tree, which a Git-managed or read-only deployment does not | ||
| + | want, it is **off by default**. A generated directory carries a marker file naming the plugin it | ||
| + | belongs to, and nothing without that marker is ever deleted, so a core module directory cannot be | ||
| + | removed by a plugin whatever the plugin is called. | ||
| + | |||
| + | <WRAP center round tip 80%> | ||
| + | Never hardcode either form — ask ``$plugin-> | ||
| + | </ | ||
| + | |||
| + | A plugin with a page gets a menu entry below // | ||
| + | pages are not destinations — the calendar answers one month of itself for its own buttons — says | ||
| + | ``" | ||
| + | |||
| + | ======= Languages, templates | ||
| + | |||
| + | * **languages/ | ||
| + | * **templates/** is added to the Smarty template search path. ``$plugin-> | ||
| + | * **assets/** holds css, js and images. ``$plugin-> | ||
| - | ===== Main plugin class ===== | + | ======= Database scripts ======= |
| - | The main [[en: | + | |
| - | ====== | + | **db_scripts/** is optional and holds |
| - | This folder | + | |
| - | In addition to database scripts update scripts (e.g.: // | + | * ``install.sql`` — run when the plugin is installed, |
| + | * ``uninstall.sql`` — run when the plugin | ||
| + | * ``update_x_y.xml`` — the update scripts, structured exactly like Admidio's own. | ||
| - | Similar to Admidio' | + | The update scripts |
| + | steps. | ||
| + | is the first ``autoload`` prefix of the manifest followed by ``Service\``, | ||
| + | ``" | ||
| + | ``AdmidioPlugin\HelloWorld\Service\UpdateStepsCode`` in ``src/Service/UpdateStepsCode.php``: | ||
| - | The class implementation should look like this: | ||
| <code php> | <code php> | ||
| final class UpdateStepsCode | final class UpdateStepsCode | ||
| { | { | ||
| - | /** | ||
| - | * @var Database | ||
| - | */ | ||
| private static Database $db; | private static Database $db; | ||
| - | /** | ||
| - | * Set the database | ||
| - | * @param Database $database The database instance | ||
| - | */ | ||
| public static function setDatabase(Database $database) | public static function setDatabase(Database $database) | ||
| { | { | ||
| Line 269: | Line 461: | ||
| } | } | ||
| - | | + | public static function /*[method name used in update_x_y.xml]*/() |
| - | * @throws Exception | + | |
| - | */ | + | |
| - | | + | |
| { | { | ||
| [...] | [...] | ||
| Line 279: | Line 468: | ||
| </ | </ | ||
| - | ====== | + | ======= Command line tasks ======= |
| - | This folder contains the plugin-specific translation files. | + | |
| - | ====== templates folder ====== | + | A plugin owns the CLI command namespace named after its directory, exactly like a module. Where a |
| - | To move away from the deprecated | + | module registers its commands in ``modules/< |
| + | **plugins/< | ||
| + | so the autoload mappings, settings | ||
| + | metadata and callbacks; the command itself runs later, after the actor and the component have been | ||
| + | authorized. | ||
| - | ====== Root plugin folder ====== | ||
| - | | ||
| - | | ||
| - | ===== Main plugin file ===== | ||
| - | Inside the root plugin folder a main plugin file is required. This file can contain plugin-specific logic (similar to Admidio’s module entry files) or simply initialize the [[en: | ||
| <code php> | <code php> | ||
| - | <?php | + | CliTaskRegistry:: |
| - | use Birthday\classes\Birthday; | + | ' |
| + | ' | ||
| + | array(Greeting:: | ||
| + | 'Print the greeting of the plugin.', | ||
| + | ' | ||
| + | ); | ||
| + | </ | ||
| - | /** | + | A command name must have the form ``extension: |
| - | | + | cannot replace a command that is already registered, and a broken ``cli.php`` is reported without |
| - | * Birthday | + | taking the rest of the command line down. |
| - | * | + | |
| - | * The plugin lists all users who have birthday in a defined timespan. | + | |
| - | * | + | |
| - | * @copyright The Admidio Team | + | |
| - | * @see https://www.admidio.org/ | + | |
| - | * @license https://www.gnu.org/ | + | |
| - | | + | |
| - | */ | + | |
| - | try { | + | ====== The plugin:* commands ====== |
| - | require_once(__DIR__ . '/ | + | |
| - | $pluginBirthday = Birthday:: | + | The plugin manager itself is fully available from the command line: |
| - | $pluginBirthday-> | + | |
| - | } catch (Throwable $e) { | + | ^ Command ^ Purpose ^ |
| - | echo $e-> | + | | ``plugin: |
| - | } | + | | ``plugin: |
| - | </ | + | | ``plugin: |
| + | | ``plugin: | ||
| + | | ``plugin: | ||
| + | | ``plugin: | ||
| + | | ``plugin: | ||
| + | | ``plugin: | ||
| + | | ``plugin: | ||
| + | | ``plugin: | ||
| + | | ``plugin: | ||
| + | | ``plugin: | ||
| - | ===== Plugin configuration file ===== | + | ======= The lifecycle ======= |
| - | Each plugin must provide a JSON configuration file containing basic plugin information and configuration (see: [[en: | + | |
| + | A plugin has **two independent states**: | ||
| - | ======= Configuration file ======= | + | * **installed** is global, because the database schema of a plugin is global. It is a row in the components table with ``com_type |
| - | Each plugin | + | * **enabled** is per organization, |
| - | ^ Key: ^ Mandatory: ^ Description: | + | The plugin |
| - | | " | + | |
| - | | " | + | |
| - | | " | + | |
| - | | " | + | |
| - | | " | + | |
| - | | " | + | |
| - | | " | + | |
| - | | " | + | |
| - | | " | + | |
| - | | " | + | |
| - | | " | + | |
| - | | " | + | |
| - | | " | + | |
| - | The following example shows the structure based on the " | + | ^ State ^ Meaning ^ |
| - | <code json> | + | | ``available`` | The files are there, but the plugin |
| - | { | + | | ``disabled`` | Installed, but not enabled for the current organization. | |
| - | " | + | | ``enabled`` | Installed and enabled for the current organization. | |
| - | " | + | | ``update`` | Installed, but the files declare a newer version |
| - | "version": "1.0.0", | + | | ``broken`` | The manifest is missing, malformed or the requirements are not met. | |
| - | " | + | | ``orphaned`` | Installed in the database, but the files are gone. | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | } | + | |
| - | }, | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | ], | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | }, | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | }, | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | }, | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | }, | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | }, | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | }, | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | }, | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | }, | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | }, | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | }, | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | }, | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | }, | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | }, | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | } | + | |
| - | } | + | |
| - | } ], | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | }, | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | }, | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | }, | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | }, | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | }, | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | }, | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | }, | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | }, | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | }, | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | }, | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | }, | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | }, | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | " | + | |
| - | } | + | |
| - | } | + | |
| - | } | + | |
| - | </ | + | |
| - | ======= Plugin class ======= | + | The operations are deliberately separate |
| - | The //Plugin// class extends the basic functionality provided by the abstract class // | + | |
| - | In its simplest implementation | + | ^ Operation ^ Scope ^ Touches data ^ |
| - | <code php> | + | | install | installation | creates the schema and the preferences of the plugin | |
| - | public static function doRender(? | + | | update | installation | runs ``db_scripts/update_x_y.xml`` up to the new version | |
| - | { | + | | enable | organization | nothing, only the preference that loads the plugin | |
| - | if (!isset($page)) { | + | | disable | organization | nothing | |
| - | throw new Exception(" | + | | remove | installation | removes the preferences, |
| - | } | + | |
| - | $page-> | + | |
| - | return true; | + | **Disabling is therefore always safe and reversible.** Enabling a plugin that was never installed |
| - | } | + | installs it first, so the administrator has one decision to make and not two. Removing is the only |
| - | </ | + | destructive operation there is: it takes the plugin away from **every** organization at once, runs |
| + | ``uninstall.sql`` and deletes the files. A plugin of the Admidio distribution is refused, because the | ||
| + | next core update would put its files back and quietly undo the decision. | ||
| - | All methods provided by // | + | Reading a plugin |
| - | <code php> | + | incompatible manifest produces a plugin whose ``error`` describes the problem, so the plugin |
| - | public static function getPluginConfig() : array | + | administration can list, disable and remove a broken plugin instead of breaking with it. The reason |
| - | { | + | comes from the manifest reader and from ``checkRequirements()``, which answer |
| - | // get the plugin config from the parent class | + | developer, so it is shown as the diagnostic it is and not as a translated member-facing message. |
| - | $config = parent:: | + | |
| - | // if the key equals ' | + | ======= Distributing a plugin ======= |
| - | if (array_key_exists(' | + | |
| - | && $config[' | + | |
| - | $config[' | + | |
| - | } | + | |
| - | if (array_key_exists(' | + | ====== The archive ====== |
| - | && $config[' | + | |
| - | $config[' | + | |
| - | } | + | |
| - | return $config; | + | ``admidio plugin: |
| - | } | + | holds a single top-level directory named after the plugin ID, and it is checked with the very gate |
| - | </ | + | the installer uses before it is handed back. |
| + | |||
| + | These are left out of the archive: ``.git``, ``.svn``, ``.hg``, ``node_modules``, | ||
| + | ``tests``, ``phpunit.xml``, | ||
| + | ``Thumbs.db``, | ||
| + | the tests of every plugin that is present, and a distributed one would run in installations that | ||
| + | have nothing to do with developing the plugin. | ||
| + | |||
| + | Everything an archive contains is written by somebody the installation does not know, so it is | ||
| + | checked before a single byte of it reaches the plugins directory. An archive may hold at most 5000 | ||
| + | entries, 32 MB compressed and 128 MB extracted, and a failure at any point removes the temporary | ||
| + | directory rather than leaving a partial plugin behind. | ||
| + | |||
| + | ====== The plugin store ====== | ||
| + | |||
| + | The store is one JSON file on a web server — by default ``plugins.json`` next to the ``update.txt`` | ||
| + | that the version check already reads. Admidio fetches it, caches it in ``adm_my_files`` and refreshes | ||
| + | it at most once a day or when an administrator asks. The remote call never happens while a page is | ||
| + | being built, and a catalogue that cannot be reached or cannot be understood makes the store | ||
| + | unavailable rather than breaking the page. | ||
| + | |||
| + | ``plugin: | ||
| + | then run the update scripts — which is all that is needed for a plugin whose files somebody replaced | ||
| + | by hand. Updating is one action whatever the plugin needs. | ||
| + | |||
| + | ====== Tests ====== | ||
| + | |||
| + | Every test suite of Admidio also reads ``plugins/ | ||
| + | it lives and with the same command as the core. The example plugin ships | ||
| + | ``plugins/hello-world/ | ||
| + | |||
| + | ======= API reference ======= | ||
| + | |||
| + | All classes live in the namespace ``Admidio\Infrastructure\Plugins``. | ||
| + | |||
| + | ====== Plugin ====== | ||
| + | |||
| + | One plugin as it exists on disk. Reading it never executes plugin | ||
| + | |||
| + | ^ Property ^ Description ^ | ||
| + | | ``id`` | Plugin ID, which is the directory name | | ||
| + | | ``path`` | Absolute path of the plugin directory | | ||
| + | | ``manifest`` | The decoded manifest, so a plugin may carry metadata the class does not interpret | | ||
| + | | ``name``, ``description``, | ||
| + | | ``autoload`` | PSR-4 mappings, as prefix => absolute directory | | ||
| + | | ``settings`` | The preferences the plugin owns, as name => definition | | ||
| + | | ``requires`` | ``admidio``, | ||
| + | | ``preferences`` | ``section`` and ``sequence`` of the settings panel | | ||
| + | | ``error`` | Why the plugin cannot be used, or ``null`` | | ||
| + | |||
| + | ^ Method ^ Description ^ Return ^ | ||
| + | | ``read(string $directory)`` | Read the plugin in a directory | Plugin | | ||
| + | | ``isValidId(string $id)`` | Whether a directory name is a usable plugin ID | bool | | ||
| + | | ``isValid()`` | Whether the plugin can be used at all | bool | | ||
| + | | ``getEntryFile()`` | Absolute path of ``plugin.php`` | string | | ||
| + | | ``getDirectory(string $directory)`` | Absolute path of a conventional subdirectory, | ||
| + | | ``getPages()`` / ``hasPages()`` | The PHP files directly below ``modules/ | ||
| + | | ``wantsMenuEntry()`` | Whether the plugin should get a menu entry | bool | | ||
| + | | ``getUrl(string $page = '' | ||
| + | | ``getSettingValues()`` | Every declared preference with its value, cast to the declared type | array | | ||
| + | | ``renderTemplate(PagePresenter $page, string $template, array $variables)`` | Render a template of the plugin | string | | ||
| + | | ``getAssetUrl(string $file)`` | URL of a file below ``assets/`` | string | | ||
| + | | ``getEnabledSettingName()`` | ``plugin_< | ||
| + | | ``getAccessSettingName()`` | ``< | ||
| + | | ``checkRequirements(array $installedPlugins)`` | One English diagnostic per unsatisfied requirement | array | | ||
| + | | ``getDisabledModules()`` | The Admidio modules the plugin needs that are switched off | array | | ||
| + | | ``versionMatches(string $version, string $constraint)`` | Check a version against a constraint | bool | | ||
| + | |||
| + | ====== PluginRegistry ====== | ||
| + | |||
| + | The only place that answers "which plugins are there" and "may this one run". It never includes | ||
| + | plugin code. Discovery and the installation states are read once per request. | ||
| + | |||
| + | ^ Method ^ Description ^ Return ^ | ||
| + | | ``all()`` | Every plugin below ``plugins/ | ||
| + | | ``get(string $id)`` | One plugin, or ``null`` | ?Plugin | | ||
| + | | ``getState(Plugin or string $plugin)`` | One of the six ``STATE_*`` constants | string | | ||
| + | | ``isInstalled(string $id)`` | Installed in this installation | bool | | ||
| + | | ``isEnabled(string $id)`` | Enabled for the current organization | bool | | ||
| + | | ``isBuiltIn(string $id)`` | A plugin of the Admidio distribution | bool | | ||
| + | | ``getInstalledVersion(string $id)`` | The version the database records | string | | ||
| + | | ``getComponentId(string $id)`` / ``getComponentUuid(string $id)`` | Component record of the plugin | int / string | | ||
| + | | ``getEnabledOrganizations(string $id)`` | Which organizations have it enabled | array | | ||
| + | | ``getLoadable()`` | The plugins that may be loaded in this request | array | | ||
| + | | ``getEnabledVersions()`` | pluginId => version of every installed and enabled plugin | array | | ||
| + | | ``getOwnerOfSetting(string $name)`` | Which plugin owns a preference | ?Plugin | | ||
| + | | ``requireEnabled(string $id)`` | Refuse the request unless the plugin is enabled | Plugin | | ||
| + | | ``requirePage(string $id, string $page)`` | Guard a plugin page | void | | ||
| + | | ``getScriptPluginId()`` | The plugin the running script belongs to | ?string | | ||
| + | |||
| + | ====== PluginLoader ====== | ||
| + | |||
| + | Loads the plugins that are enabled for the current request. | ||
| + | |||
| + | ^ Method ^ Description ^ Return ^ | ||
| + | | ``loadEnabled()`` | Load every enabled plugin | void | | ||
| + | | ``load(Plugin $plugin)`` | Load one plugin | bool | | ||
| + | | ``getLoaded()`` / ``isLoaded(string $id)`` | What was loaded in this request | array / bool | | ||
| + | | ``getFailures()`` | pluginId => why it could not be loaded | array | | ||
| + | | ``getTemplateDirectories()`` | The template search path contributed by plugins | array | | ||
| + | | ``registerLanguages(Plugin $plugin)`` | Add the language directory of a plugin | void | | ||
| + | |||
| + | ====== PluginInstaller ====== | ||
| + | |||
| + | ^ Method ^ Description ^ Return ^ | ||
| + | | ``install(Plugin $plugin, bool $addMenuEntry = true)`` | Run ``install.sql``, | ||
| + | | ``update(Plugin $plugin)`` | Run the update scripts up to the version the files declare | void | | ||
| + | | ``updateWithNewerFiles(Plugin $plugin)`` | Fetch newer files where the store publishes them, then update | Plugin | | ||
| + | | ``remove(Plugin or string $plugin)`` | Remove the plugin from every organization, | ||
| + | | ``enable(Plugin $plugin)`` / ``disable(Plugin $plugin)`` | The per-organization decision | void | | ||
| + | | ``getPreferenceNames(Plugin $plugin)`` | Every preference the plugin owns | array | | ||
| + | |||
| + | ====== PluginWidget ====== | ||
| + | |||
| + | ^ Method ^ Description ^ Return ^ | ||
| + | | ``register(Plugin $plugin, callable $render, array $options)`` | Declare the widget and add the hook that renders it | void | | ||
| + | | ``render(PagePresenter $page, Plugin $plugin, string $template, array $variables)`` | Render a template as the widget body | string | | ||
| + | | ``getDeclarations()`` | Every declared widget, whether visible in this request or not | array | | ||
| + | | ``isVisible(string $preference)`` / ``getAccess(string $preference)`` | Who may see the widget | bool / int | | ||
| + | | ``getSequence(string $preference, | ||
| + | | Constants | ``HOOK``, ``DEFAULT_SEQUENCE``, | ||
| + | |||
| + | ====== PluginPanel ====== | ||
| + | |||
| + | ^ Method ^ Description ^ Return ^ | ||
| + | | ``collect()`` | Every declared preferences panel | array | | ||
| + | | ``inSection(string $section)`` | The panels of one preference tab | array | | ||
| + | | ``get(string $id)`` | One panel declaration | ?array | | ||
| + | | ``create(string $id, PreferencesPresenter $presenter)`` | Build the HTML of one panel | string | | ||
| + | | ``normalizeId(string $id)`` | The panel ID a plugin ID maps to | string | | ||
| + | |||
| + | ====== PluginPages ====== | ||
| + | |||
| + | ^ Method ^ Description ^ Return ^ | ||
| + | | ``isAllowed()`` | Whether ``plugin_module_pages`` permits publishing | bool | | ||
| + | | ``isWritable()`` | Whether the modules directory can be written | bool | | ||
| + | | ``getObstacle(Plugin $plugin)`` | Why a plugin cannot be published, or ``null`` | ?string | | ||
| + | | ``isPublished(Plugin or string $plugin)`` | Whether the stubs exist | bool | | ||
| + | | ``getUrl(Plugin $plugin, string $page)`` | The URL that is currently live | string | | ||
| + | | ``publish(Plugin $plugin)`` / ``unpublish(Plugin or string $plugin)`` | Write or remove the stubs | bool / void | | ||
| + | | ``reconcile()`` / ``syncAll()`` | Bring the modules directory in line with the preference | array | | ||
| + | | Constants | ``SETTING`` (``plugin_module_pages``), | ||
| + | |||
| + | ====== PluginStore ====== | ||
| + | |||
| + | ^ Method ^ Description ^ Return ^ | ||
| + | | ``getPlugins()`` | What the catalogue publishes for this Admidio | array | | ||
| + | | ``getEntry(string $id)`` | One catalogue entry | ?array | | ||
| + | | ``getNewerRelease(string $id)`` | A published release newer than the installed one | ?array | | ||
| + | | ``install(string $id)`` / ``updateFiles(string $id)`` | Fetch and place the files | string | | ||
| + | | ``refresh()`` | Fetch the catalogue now | array | | ||
| + | | ``getUrl()`` / ``isDeveloperCatalogue()`` / ``getError()`` | Where it comes from and why it failed | string / bool / ?string | | ||
| + | |||
| + | ====== PluginPackage ====== | ||
| + | |||
| + | ^ Method ^ Description ^ Return ^ | ||
| + | | ``install(string $archivePath, | ||
| + | | ``describe(string $archivePath)`` | The plugin an archive holds | Plugin | | ||
| + | | ``create(Plugin $plugin, string $directory)`` | Build the distributable archive | string | | ||
| + | | ``inspect(string $archivePath)`` | The gate: everything it rejects is rejected before a file is written | string | | ||
| + | | Constants | ``MAX_ARCHIVE_BYTES``, | ||
| + | |||
| + | ======= What changed since the first plugin manager ======= | ||
| + | |||
| + | The plugin manager of Admidio 5.0 was built around a ``PluginAbstract`` base class and a | ||
| + | ``plugin.json`` that described it. The runtime was replaced, and a plugin written for it has to be | ||
| + | converted. The differences that matter to a plugin author: | ||
| + | |||
| + | ^ Then ^ Now ^ | ||
| + | | A main plugin class extending ``PluginAbstract``, | ||
| + | | The main file was named by ``mainFile``, | ||
| + | | ``" | ||
| + | | ``" | ||
| + | | ``" | ||
| + | | A preferences presenter was found by scanning the autoload directories for ``*PreferencesPresenter.php`` | The panel is declared through the ``PluginPanel`` hook, or generated from the manifest and not written at all | | ||
| + | | ``" | ||
| + | | ``classes/ | ||
| + | | Install and uninstall were one pair of operations | Four distinct operations: install and update are installation-wide, | ||
| + | | ``db-install.sql`` / ``db-uninstall.sql`` | ``install.sql`` / ``uninstall.sql`` in ``db_scripts/ | ||
| + | | Plugins were installed by copying files | Plugin store, ZIP upload and ``admidio plugin:*`` commands | | ||
| + | |||
| + | The generated settings form is the largest simplification: | ||
| + | preference fields declares them in the manifest and writes no presenter, no template and no form | ||
| + | code at all. | ||
| - | ======== PluginAbstract class ======== | ||
| - | <WRAP center round todo 60%> | ||
| - | methods documentation | ||
| - | </ | ||
