wip

Author: Severino

PLUGINS.md

@@ -7,13 +7,33 @@ Plugins are in beta (since Release _Isfahan_) and installation or the overall AP
 
 ## Plugin structure
 
-Before actually creating a plugin, here is how the folder structure of your plugin **has** to be:
 
-- `App`: Hosting your Laravel Models and an `info.xml` file with several metadata of your plugin
-- `Controllers`: Hosting your Laravel Controllers
-- `Migration`: Place your migration files here
-- `js`: This is the destination folder for your Vue/JavaScript code. **Important**: Bundle **all** your JavaScript code into a single `script.js` file!
-- `routes`: Place for your (API) routes to connect your JS code with the Laravel Backend (`api.php`)
+```
+app/Plugins/YourPlugin/
+├── App
+│   ├── Controllers/                            # Controller classes             
+│   ├── Models/                                 # Laravel database models
+│   ├── Scopes/                                 # Model scopes
+│   ├── Support/                                # Support classes
+│   ├── Services/                               # Service classes that can be autoloaded into other classed
+│   ├── Utils/                                  # Static utility functions
+│   └── ...             
+├── migrations/                                 # Plugin migrations
+│   ├── yyyy_mm_dd_hhmmss_migration_name.php    # Migrations in this specific format.
+│   └── ...
+├── routes/                                     # Plugin routes
+├── src/                                        # Frontend source files
+├── js/                 
+│   ├── script.js.map                           # Compiled map file for development
+│   └── script.js                               # Compiled plugin script - REQUIRED
+├── vendor/                                     # Composer vendor directory generated by the plugin via composer install 
+├── CHANGELOG.md                                # Version history
+├── composer.json                               # PHP dependencies
+├── package.json                                # JavaScript dependencies
+├── permissions.json                            # Plugin permissions
+├── plugin.xml                                  # Plugin metadata - REQUIRED
+└── role-presets.json                           # Role presets
+```
 
 ## Creating a Plugin
 
@@ -113,7 +133,7 @@ mkdir -p src/components
 mkdir src/i18n
 ```
 
-#### info.xml
+#### plugin.xml
 
 This File is mandatory and stores all the information about your plugin. Author, Licence, Version, Description, ...
 
@@ -128,6 +148,21 @@ This File is mandatory and stores all the information about your plugin. Author,
     <authors>
         <author>Vinzenz Rosenkranz</author>
     </authors>
+    <dependencies>
+        <depends-on plugin="file" min-version="2.0" />
+    </dependencies>
+    <routes>
+        <route src="routes/api.php" />
+    </routes>
+    <hooks>
+        <hook on="" />
+    </hooks>
+    <role-presets>
+        <role-preset src="role-resets.json" />
+    </role-presets>
+    <permissions>
+        <permission src="permission.json" />
+    </permissions>
 </info>
 
 ```

app/Http/Middleware/PluginHooks.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace App\Http\Middleware;
+
+use App\Services\HookService;
+use Closure;
+use Illuminate\Http\Request;
+
+class PluginHooks
+{
+    
+    public function __construct(protected HookService $hookService){ }
+
+    
+     public function handle(Request $request, Closure $next) {
+        $actionNamespace = $request->route()->getActionName();
+        info("ActionName :: " . $actionNamespace);
+        $namespaceParts = explode('\\', $actionNamespace);
+        $name = array_pop($namespaceParts);
+        
+        $response = $next($request);
+        // execute hooks with the response as first argument so hooks can modify it
+        $response = $this->hookService->executeHooks($name, $response, $request);
+    
+        return $response;
+     }
+}

app/Interfaces/IPluggable.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace App\Interfaces;
+
+use App\Plugin;
+
+interface IPluggable {
+    public function install(Plugin $plugin): void;
+    public function update(Plugin $plugin): void;
+    public function uninstall(Plugin $plugin): void;
+    public function remove(Plugin $plugin): void;
+}

app/Models/Plugin/Hook.php

@@ -0,0 +1,73 @@
+<?php
+
+namespace App\Models\Plugin;
+
+use App\Plugin;
+use Illuminate\Database\Eloquent\Model;
+
+class Hook extends Model
+{
+    public const AVAILABLE_HOOKS = [
+        'App\Http\Controllers\HomeController@getGlobalData',
+        'EditorController@setRelationInfo',
+        'EditorController@getEntityType'
+    ];        
+
+    protected $table = 'plugin_hooks';
+
+    protected $fillable = [
+        'plugin_id',
+        'src',
+        'order',
+        'on',
+    ];
+    
+    /**
+     * When a plugin xml is parsed, this method is used to create a Hook model from 
+     * the json representation of the hook in the plugin's info.xml.
+     * 
+     * @throws \Exception if the json is missing required fields or has invalid values.
+     * @return {Model(unsaved)} An unsaved Hook model instance.
+     */
+    public static function getHookFromJson($hookJson, Plugin $plugin = null): Hook {
+        $hook = $hookJson;
+        
+        $missingFields = [];
+        $requiredFields = ['on', 'src'];
+        
+        foreach($requiredFields as $reqiredField){
+            if(!isset($hook[$reqiredField])) {
+                $missingFields[] = $reqiredField;
+                }
+        }
+        
+        if(count($missingFields) > 0){
+            info("MISSING FIELDS IN HOOK JSON: " . implode(", ", $missingFields) . " in hook json: " . json_encode($hookJson));
+            throw new \Exception("Hook is missing field(s): " . implode(", ", $missingFields));
+        }
+        
+        if(!in_array($hook['on'], self::AVAILABLE_HOOKS)) {
+            throw new \Exception("Hook '".$hook['on']."' is not a valid hook.");
+        }
+
+        $src = $hook['src'];
+        $parts = explode('@', $src);
+        if(count($parts) != 2) {
+            throw new \Exception("Hook 'src' field must be in the format 'class@method'");
+        }
+
+        $order = isset($hook['order']) ? $hook['order'] : 0;
+        $order = intval($order);
+
+        $hookModel = new Hook();
+        $hookModel->on = $hook['on'];
+        $hookModel->src = $hook['src'];
+        $hookModel->order = $order;
+        
+        if($plugin) {
+            $hookModel->plugin_id = $plugin->id;
+        }
+        
+        return $hookModel;
+    }
+}

app/Patterns/Singleton.php

@@ -4,16 +4,26 @@
 
 abstract class Singleton {
 
-    public static ?Singleton $instance = null;
+    // NOTE: The problem in PHP is that static properties are shared between child classes, 
+    // so we need to store the instance in an array with the class name as key.
+    
+    /**
+    *  The instances of the singleton classes, stored with the class name as key.
+    * This is necessary because static properties are shared between child classes in PHP.
+    *
+    * @var array<string, static> - An array that holds the instances of the singleton classes, indexed by their class names.
+    */
+    protected static array $instances = [];
+    
+    protected function __construct() {}
 
-    protected function __construct() {
-        static::$instance = $this;
-    }
-
-    static function get(): static {
-        if (static::$instance != null) {
-            return static::$instance;
+    /**
+     * Returns the singleton instance of the class. If the instance does not exist, it creates a new one.
+     */
+    final public static function get(): static {
+        if(!isset(static::$instances[static::class])) {
+            static::$instances[static::class] = new static();
         }
-        return new static();
+        return static::$instances[static::class];
     }
 }