New plugin system based on Laravel Package Development (#12998)

* use Blade view and Eloquent models for plugins * move views * fix style * fix style * revert mistake * Update Plugin.php delete test property "name" * rename plugin function to settings * last but not least - rename in Test.php * Rename Test to Example * fix typo * fix style * fix style * fix style * fix style - I hate tabs... * Extract view calls * fix method calls and style * Move Models the the abstract class * fix style * Convert to traits * Change the Example description * Fix style * Fix style * Fix style * Convert plugin function to Model static methods and delete .inc.php * fix style * fix style * Use scope * final methods blows up legacy code * Config > \LibreNMS\Config * convert the static string to a static method * Correct placement in the page * fix tabs * fix style * Rename from tait to hook to make it easier to understand and be complient * rename file * Typo * Started to change the docu * change to a more usefully Device_Overview example * and activate of course * PluginManager * fix .gitignore * only php files in the root folder * corrected .gitignore with all files :) * Rename the Hooks and ExampleClass for better readability * Fix style * Fix style * Exception handling (especially if DB is not present) * Fix style and update schema * fix indentation * actually correct indent * fix migration collation check include utf8mb4_bin * stop phpstan whining * A view lines documentation * add typeHints * Allow return null on handle * lint * fix return types * fix logic of column collation check * Fix MenuEntryHook * switch to longtext instead of json type for now :D * try phpstan on PHP 7.3 * set phpstan target version to 7.3 * all the typehints * optional * more * Use namespace to prevent view collisions disambiguate plugin and hook no magic guessing of names in PluginManager, bad assumptions remove unused plugins from the DB * cleanup plugin menu * cleanup on shutdown and ignore but log query error on cleanup * instanceof must be called against an instance * Allow multiple hooks per plugin * Port plugin ui code to Laravel * page instead of settings for v1 plugins * actually working settings pages a little url cleanup plugin/admin -> plugin/settings * fix style * Add page hook * PHPstan * Try to fix Illuminate\Http\RedirectResponse * typehint * Rewrite the doc * Fix style Co-authored-by: PipoCanaja <38363551+PipoCanaja@users.noreply.github.com> Co-authored-by: Tony Murray <murraytony@gmail.com>
2024-10-07 16:52:45 +00:00 · 2021-10-19 13:53:28 +02:00
parent 2d5d7e14ed
commit 98ed6bb9dc
50 changed files with 1440 additions and 215 deletions
--- a/doc/Extensions/Plugin-System.md
+++ b/doc/Extensions/Plugin-System.md
@@ -3,13 +3,99 @@ path: blob/master/doc/

 # Developing for the Plugin System

-This will most likely be deprecated in favour of adding the possible
-extensions to the core code base.
+With plugins you can extend LibreNMS with special functions that are
+specific to your setup or are not relevant or interesting for all community members.

-This documentation will hopefully give you a basis for how to write a
-plugin for LibreNMS. A test plugin is included in LibreNMS distribution.
+You are able to intervene in defined places in the behavior of
+the website, without it coming to problems with future updates.

-# Generic structure
+This documentation will give you a basis for writing a plugin for
+LibreNMS. An example plugin is included in the LibreNMS distribution.
+
+
+# Version 2 Plugin System structure
+
+Plugins in version 2 need to be installed into app/Plugins
+
+The structure of a plugin is follows:
+
+```
+app/Plugins
+            /PluginName
+                       /DeviceOverview.php
+                       /Menu.php
+                       /Page.php
+                       /PortTab.php
+                       /Settings.php
+                       /resources/views
+                                       /device-overview.blade.php
+                                       /menu.blade.php
+                                       /page.blade.php
+                                       /port-tab.blade.php
+                                       /settings.blade.php
+```
+
+The above structure is checked before a plugin can be installed.
+
+All file/folder names are case sensitive and must match the structure.
+
+Only the blade files that are really needed need to be created. A plugin manager
+will then load a hook that has a basic functionality.
+
+If you want to customize the basic behavior of the hooks, you can create a
+class in 'app/Plugins/PluginName' and overload the hook methods.
+
+- device-overview.blade.php :: This is called in the Device
+  Overview page. You receive the $device as a object per default, you can do your
+  work here and display your results in a frame.
+
+```
+<div class="row">
+    <div class="col-md-12">
+        <div class="panel panel-default panel-condensed">
+            <div class="panel-heading">
+                <strong>{{ $title }}</strong>
+            </div>
+            <div class="panel-body">
+                <div class="row">
+                    <div class="col-sm-12">
+                         {{ $device->hostname }}
+		    	 <!-- Do you stuff here -->
+                    </div>
+		</div>
+	    </div>
+	</div>
+    </div>
+</div>
+```
+
+- port-tab.blade.php :: This is called in the Port page,
+  in the "Plugins" menu_option that will appear when your plugin gets
+  enabled. In this blade, you can do your work and display your
+  results in a frame.
+
+- menu.blade.php :: For a menu entry 
+
+- page.blade.pho :: Here is a good place to add a own LibreNMS page without dependence with a device. A good place to create your own lists with special requirements and behavior.
+
+- settings.blade.php :: If you need your own settings and variables, you can have a look in the ExamplePlugin.
+
+
+
+If you want to change the behavior, you can customize the hooks methods. Just as an example, you could imagine that the device-overview.blade.php should only be displayed when the device is in maintanence mode. Of course the method is more for a permission concept but it gives you the idea.
+
+```
+abstract class DeviceOverviewHook
+{
+    ...
+    public function authorize(User $user, Device $device, array $settings): bool
+    {
+        return $device->isUnderMaintenance();
+    }
+    ...
+```
+
+# Version 1 Plugin System structure (legacy verion)

 Plugins need to be installed into html/plugins