Differences

This shows you the differences between two versions of the page.

--- en:entwickler:plugin_manager [2026/02/01 16:58] – [Naming conventions] mightymcoder
+++ en:entwickler:plugin_manager [2026/02/08 12:14] (current) – [Singleton / Basic Handling] mightymcoder
@@ Line 9: / Line 9: @@
 plugins in Admidio.
+With the Plugin Manager it is now also possible to easily and quickly integrate your own custom overview plugins.
+A Basic //"Overview Plugin Example"// can by found here: [[https://github.com/Admidio/admidio-overview-plugin-example|Admidio Overview Plugin Example]]
 ======== Make your plugin compatible with the Plugin Manager (Admidio 5) ========
 To make your plugin compatible with the Plugin Manager certain requirements must first be met. These include:
   * [[en:entwickler:plugin_manager#naming_conventions|Naming conventions]]
   * A consistent [[en:entwickler:plugin_manager#folder_structure|folder structure]]
-  * A [[en:entwickler:plugin_manager#plugin_preferences_class|preference presenter class]] with a [[en:entwickler:plugin_manager#single_formpresenter_element|single FormPresenter element]] or with [[en:entwickler:plugin_manager#multiple_formpresenter_elements|multiple FormPresenter elements]]
-  * A [[en:entwickler:plugin_manager#plugin_class|plugin class]]
   * A JSON [[en:entwickler:plugin_manager#configuration_file|configuration file]]
+  * A [[en:entwickler:plugin_manager#main_plugin_class|main plugin class]] extending the //PluginAbstract// class
+  * A [[en:entwickler:plugin_manager#plugin_preferences_class|preference presenter class]] with a [[en:entwickler:plugin_manager#single_formpresenter_element|single FormPresenter element]] or with [[en:entwickler:plugin_manager#multiple_formpresenter_elements|multiple FormPresenter elements]] if your plugin preferences should be accessable via Admidios preferences panel
 ======= Naming conventions =======
-To use the new Plugin Manager some naming conventions must be observed:
+When using the new Plugin Manager, the following naming conventions must be observed:
-  - For better readability file and folder names containing multiple words should follow snake_case (underscore separated) notation.
+  - For better readability file and folder names containing multiple words should follow **//kebab-case//** (//dash separated//) notation.
-  - All folder and file names containing multiple words and are placed inside the //classes// folder should follow UpperCamelCase (PascalCase) notation.
+  - All folder and file names containing multiple words and are placed inside the //classes// folder should follow **//UpperCamelCase//** (//PascalCase//) notation.
   - No plugin file defining a class may contain delimiters such as //"-"// or //"_"// especially if it will be used via a class import.
 ======= Folder structure =======
@@ Line 27: / Line 30: @@
 ====== classes folder ======
+===== Main plugin class =====
+The main [[en:entwickler:plugin_manager#plugin_class|plugin class]] (e.g.: //Birthday//) must be placed directly in the //classes// folder.
 ===== Presenter classes =====
 ==== Plugin-specific classes ====
@@ Line 240: / Line 246: @@
 ===== Entity, Service and ValueObjects classes =====
 If the plugin has specific //Entity//, //Service//, or //ValueObjects// classes these should be placed in the corresponding subfolders as is done with the Admidio modules.
-===== Main plugin class =====
-The main [[en:entwickler:plugin_manager#plugin_class|plugin class]] (e.g.: //Birthday//) must be placed directly in the //classes// folder.
 ====== db_scripts folder ======
@@ Line 532: / Line 535: @@
 The //Plugin// class extends the basic functionality provided by the abstract class //PluginAbstract// and implements the //doRender// method.
-In its simplest implementation the //doRender// method can just call the //PagePresenter// //show// method:
+If there is nothing to render the //doRender// method can just return //true//:
 <code php>
-public static function doRender(?PagePresenter $page = null) : bool
+namespace Birthday\classes;
+use Admidio\Infrastructure\Plugins\PluginAbstract;
+use Admidio\UI\Presenter\PagePresenter;
+class Birthday extends PluginAbstract
 {
-    if (!isset($page)) {
+    public static function doRender(?PagePresenter $page = null) : bool
-        throw new Exception("The page parameter must be set.");
+    {
+        return true;
     }
-    $page->show();
+}
+</code>
-    return true;
+In its simplest implementation for displaying something the //doRender// method can just call the //PagePresenter// //show// method:
+<code php>
+namespace Birthday\classes;
+use Admidio\Infrastructure\Plugins\PluginAbstract;
+use Admidio\UI\Presenter\PagePresenter;
+class Birthday extends PluginAbstract
+{
+    public static function doRender(?PagePresenter $page = null) : bool
+    {
+        if (!isset($page)) {
+            throw new Exception("The page parameter must be set.");
+        }
+        $page->show();
+        return true;
+    }
 }
 </code>
@@ Line 571: / Line 598: @@
 methods documentation
 </WRAP>
+The //PluginAbstract// class is the base class for all plugins usable with the Plugin Manager.
+Provides:
+  * installation / uninstallation
+  * updates
+  * configuration handling
+  * dependency checks
+  * autoload registration
+  * visibility + activation control
+All custom plugins should extend this class.
+-----
+===== Singleton / Basic Handling =====
+^ Method ^ Description ^ Return ^
+| getInstance() | Returns the singleton instance of the plugin class | PluginAbstract |
+| <nowiki>__construct()</nowiki> | Protected constructor (singleton pattern) | void |
+| <nowiki>__clone()</nowiki> | Prevents cloning of the singleton | void |
+| <nowiki>__wakeup()</nowiki> | Prevents unserializing | void |
+-----
+===== Menu Integration / Preferences =====
+^ Method ^ Description ^ Return ^
+| addMenuEntry() | Adds the plugin menu entry to the database | void |
+| removeMenuEntry() | Removes the plugin menu entry from the database | void |
+| initPreferencePanelCallback() | Initializes plugin preference panel integration | void |
+-----
+===== Metadata / Identity =====
+^ Method ^ Description ^ Return ^
+| getName() | Returns the plugin name | string |
+| getIcon() | Returns the plugin icon from metadata | string |
+| getVersion() | Returns the plugin version | string |
+| getMetadata() | Returns the complete metadata definition | array |
+| getDependencies() | Returns declared dependencies | array |
+| getSupportedLanguages() | Returns supported languages | array |
+-----
+===== Static Files =====
+^ Method ^ Description ^ Return ^
+| getStaticFiles(?string $type = null, string $path = '') | Returns plugin static files (css/js/images/etc.) | array |
+Example:
+<code php>
+Plugin::getStaticFiles('css');
+</code>
+-----
+===== Configuration & Component Information =====
+^ Method ^ Description ^ Return ^
+| getPluginConfigValues() | Returns stored config values only (key => value) | array |
+| getPluginConfig() | Returns merged configuration (defaults + DB) | array |
+| getPluginPath() | Absolute filesystem path | string |
+| getComponentId() | Database component ID | int |
+| getComponentName() | Plugin folder name | string |
+| getPluginSequence() | Overview sorting sequence | int |
+-----
+===== Dependency Handling =====
+^ Method ^ Description ^ Return ^
+| checkDependencies() | Verifies all dependencies are available | bool |
+Internal helper:
+<code php>
+private static function findAdmidioClass(string $shortName): ?string
+</code>
+-----
+===== Installation State / Visibility =====
+^ Method ^ Description ^ Return ^
+| isInstalled() | Plugin exists in database | bool |
+| isActivated() | Installed and activated | bool |
+| isVisible() | Visible depending on config and login state | bool |
+| isOverviewPlugin() | Registered as overview plugin | bool |
+| isAdmidioPlugin() | Built-in overview plugin | bool |
+| isUpdateAvailable() | Installed version differs from metadata | bool |
+-----
+===== Autoloading =====
+^ Method ^ Description ^ Return ^
+| doClassAutoload(string $class) | Registers PSR-4 autoload mappings | bool |
+Example metadata:
+<code json>
+"autoload": {
+  "psr-4": {
+    "Vendor\\Plugin\\": "classes/"
+  }
+}
+</code>
+-----
+===== Lifecycle Methods =====
+==== doInstall(bool $addMenuEntry = true) ====
+Installs the plugin.
+Steps:
+  * store default config values
+  * execute install SQL scripts
+  * register component
+  * run update steps
+  * set version
+  * optionally create menu entry
+Returns: bool
+----
+==== doUninstall(bool $removeMenuEntry = true, array $options = array()) ====
+Removes the plugin completely.
+Steps:
+  * execute uninstall SQL scripts
+  * delete config values
+  * remove menu entries
+  * delete component
+  * reset version
+Returns: bool
+----
+==== doUpdate() ====
+Updates an installed plugin.
+Steps:
+  * add missing config defaults
+  * run update classes
+  * update stored version
+Returns: bool
+----
+==== initParams(array $params = array()) ====
+Optional initialization hook for plugins.
+Returns: bool
+-----
+===== Internal Helpers (private) =====
+^ Method ^ Description ^
+| readPluginMetadata() | Loads and parses metadata file |
+| getClassNameFromFile(string $file) | Extracts class name from PHP file |
+| toggleForeignKeyChecks(bool $enable) | Enables/disables MySQL foreign key checks during install/uninstall |