Refactor plugin to use 'diffbase' handle and templates

Updated plugin handle from '_diffbase' to 'diffbase' in composer.json and throughout the codebase. Refactored template paths and URL rules to use 'diffbase'. Improved Plugin and CpController initialization, settings management, and API key generation logic. Simplified settings.twig to redirect to the main plugin page.

Author: stefanladner

README.md

@@ -1,30 +1,14 @@
 # diff. base module
 
 ## Installation
-- Copy module to ```/modules```
-- Open ```config/app.php``` and initialize module by adding
 
-```php
-    'modules' => [
-        'diffbase' => modules\diffbase\Module::class,
-    ],
-    'bootstrap' => ['diffbase'],
+```
+composer require "digitaldiff/diffbase" -w && php craft plugin/install diffbase
 ```
 
-- Go to Settings/diff. base module and generate a API key
+- Go to plugin settings and generate a API key
 - Test the API Key by going to ```yourdomain.com/api/info?key=```
 - Copy the API key to flow.diff.ch/admin and make a new entry with the API key and the site url 
 
 ## Compatibility
-Only works/tested with Craft CMS 5.x
-
-## Troubleshooting
-If you get a error at the Login screen, make sure that in the root composer.json the modules are initialized by adding:
-
-```json
-  "autoload": {
-    "psr-4": {
-      "modules\\": "modules/"
-    }
-  },
-```
+Only works/tested with Craft CMS 5.x

composer.json

@@ -24,7 +24,7 @@
     },
     "extra": {
         "name": "diff. base module",
-        "handle": "_diffbase",
+        "handle": "diffbase",
         "developer": "diff. Kommunikation AG",
         "documentationUrl": "https://github.com/digitaldiff/diffbase/blob/main/README.md",
         "changelogUrl": "https://raw.githubusercontent.com/digitaldiff/diffbase/main/CHANGELOG.md",

src/Plugin.php

@@ -1,4 +1,5 @@
 <?php
+
 namespace digitaldiff\diffbase;
 
 use Craft;
@@ -9,101 +10,132 @@
 use craft\events\RegisterCpNavItemsEvent;
 use craft\events\RegisterTemplateRootsEvent;
 use craft\web\View;
+use Twig\Error\LoaderError;
+use Twig\Error\RuntimeError;
+use Twig\Error\SyntaxError;
 use yii\base\Event;
 use digitaldiff\diffbase\models\Settings;
 use digitaldiff\diffbase\services\ApiService;
+use yii\base\Exception;
 
+/**
+ * Main plugin class for the "diff. base plugin".
+ *
+ * This class handles the initialization of the plugin, including:
+ * - Registering template paths
+ * - Defining custom URL rules for the site and control panel
+ * - Adding a custom navigation item to the control panel
+ * - Providing a settings model and rendering the settings page
+ */
 class Plugin extends BasePlugin
 {
+    /**
+     * @var string The schema version of the plugin.
+     */
     public string $schemaVersion = '1.0.0';
-//    public bool $hasCpSettings = true;
-//    public bool $hasCpSection = true;
 
+    /**
+     * @var bool Indicates whether the plugin has a control panel settings page.
+     */
+    public bool $hasCpSettings = true;
+
+    /**
+     * Configures the plugin's components.
+     *
+     * @return array The configuration array for the plugin's components.
+     */
     public static function config(): array
     {
         return [
             'components' => [
-                'apiService' => ApiService::class,
+                'apiService' => ApiService::class, // Registers the ApiService for business logic
             ],
         ];
     }
 
-    public function init()
+    /**
+     * Initializes the plugin.
+     *
+     * This method is called automatically when the plugin is loaded. It sets up
+     * aliases, registers template paths, defines URL rules, and adds a control panel
+     * navigation item.
+     */
+    public function init(): void
     {
         parent::init();
 
+        // Set an alias for the plugin's base path
         Craft::setAlias('@digitaldiff/diffbase', $this->getBasePath());
 
-        // Template-Pfad registrieren
+        // Register the template path for the plugin
         Event::on(
             View::class,
-            View::EVENT_REGISTER_CP_TEMPLATE_ROOTS,
+            View::EVENT_REGISTER_SITE_TEMPLATE_ROOTS,
             function(RegisterTemplateRootsEvent $event) {
-                $event->roots['_diffbase'] = $this->getBasePath() . '/templates';
+                $event->roots['diffbase'] = __DIR__ . 'src/templates'; // Registers the template directory
             }
         );
 
-        // Site URL-Regeln für API
+        // Register site URL rules for the plugin's API
         Event::on(
             UrlManager::class,
             UrlManager::EVENT_REGISTER_SITE_URL_RULES,
             function (RegisterUrlRulesEvent $event) {
-                $event->rules['api/info'] = '_diffbase/api/info';
+                $event->rules['api/info'] = 'diffbase/api/info'; // Maps 'api/info' to the ApiController
             }
         );
 
-        // CP URL-Regeln
+        // Register control panel URL rules for the plugin
         Event::on(
             UrlManager::class,
             UrlManager::EVENT_REGISTER_CP_URL_RULES,
             function (RegisterUrlRulesEvent $event) {
-                $event->rules['_diffbase'] = '_diffbase/cp/index';
-                $event->rules['_diffbase/settings'] = '_diffbase/cp/settings';
+                $event->rules['diffbase'] = 'diffbase/cp/index'; // Maps 'diffbase' to CpController::actionIndex
+                $event->rules['diffbase/test'] = 'diffbase/cp/test'; // Maps 'diffbase/test' to CpController::actionTest
+                $event->rules['diffbase/<action:\w+>'] = 'diffbase/cp/<action>'; // Maps dynamic actions
             }
         );
 
+        // Add a custom navigation item to the control panel
         Event::on(
             Cp::class,
             Cp::EVENT_REGISTER_CP_NAV_ITEMS,
-            function (RegisterCpNavItemsEvent $event) {
+            function(RegisterCpNavItemsEvent $event) {
                 $event->navItems[] = [
-                    'url' => '_diffbase',
-                    'label' => 'diff. base plugin',
-                    'icon' => '@digitaldiff/diffbase/icon-mask.svg',
-                    'weight' => 2, // Position im Hauptmenü
+                    'label' => 'diff. base plugin', // Label for the navigation item
+                    'url' => 'diffbase', // URL for the navigation item
+                    'icon' => '@digitaldiff/diffbase/icon-mask.svg', // Icon for the navigation item
+                    'weight' => 3, // Position in the navigation menu
                 ];
             }
         );
-
-/*        // CP Navigation
-        Event::on(
-            Cp::class,
-            Cp::EVENT_REGISTER_CP_NAV_ITEMS,
-            function (RegisterCpNavItemsEvent $event) {
-                foreach ($event->navItems as &$item) {
-                    if ($item['url'] === 'settings') {
-                        $item['subnav']['_diffbase'] = [
-                            'label' => 'DiffBase',
-                            'url' => '_diffbase',
-                            'selected' => Craft::$app->getRequest()->getSegment(1) === '_diffbase'
-                        ];
-                        break;
-                    }
-                }
-            }
-        );*/
     }
 
+    /**
+     * Creates the settings model for the plugin.
+     *
+     * @return Settings The settings model instance.
+     */
     protected function createSettingsModel(): Settings
     {
         return new Settings();
     }
 
+    /**
+     * Renders the settings page for the plugin.
+     *
+     * @return string|null The rendered HTML for the settings page.
+     *
+     * @throws SyntaxError If there is a syntax error in the Twig template.
+     * @throws Exception If an error occurs during rendering.
+     * @throws RuntimeError If a runtime error occurs in the Twig template.
+     * @throws LoaderError If the Twig template cannot be loaded.
+     */
     protected function settingsHtml(): ?string
     {
-        return Craft::$app->getView()->renderTemplate('_diffbase/settings', [
-            'plugin' => $this,
-            'settings' => $this->getSettings(),
+        return Craft::$app->getView()->renderTemplate('diffbase/settings', [
+            'plugin' => $this, // Passes the plugin instance to the template
+            'settings' => $this->getSettings(), // Passes the settings model to the template
         ]);
     }
 }

src/controllers/CpController.php

@@ -18,6 +18,7 @@
 
 class CpController extends Controller
 {
+
     /**
      * @throws NotSupportedException
      * @throws InvalidConfigException
@@ -30,23 +31,34 @@ class CpController extends Controller
      */
     public function actionIndex(): \yii\web\Response
     {
-        $settings = $this->getSettings();
+        $plugin = Plugin::getInstance();
+        if (!$plugin) {
+            throw new \Exception('Plugin nicht initialisiert');
+        }
+
+        $settings = $plugin->getSettings();
+        if (!$settings) {
+            // Fallback: neue Settings erstellen
+            $settings = new Settings();
+        }
 
         // API-Key automatisch generieren wenn keiner vorhanden
         if (!$settings->apiKey) {
             $settings->apiKey = $settings->generateApiKey();
-            Craft::$app->getProjectConfig()->set('_diffbase.apiKey', $settings->apiKey);
+            Craft::$app->plugins->savePluginSettings($plugin, ['apiKey' => $settings->apiKey]);
             Craft::$app->getSession()->setNotice('API-Key wurde automatisch generiert.');
         }
 
-        return $this->renderTemplate('_diffbase/index', [
+        return $this->renderTemplate('diffbase/index', [
             'settings' => $settings
         ]);
     }
 
     private function getSettings(): Settings
     {
-        return Plugin::getInstance()->getSettings();
+        /** @var Settings $settings */
+        $settings = Plugin::getInstance()->getSettings();
+        return $settings;
     }
 
     /**
@@ -84,10 +96,32 @@ public function actionDeleteApiKey(): \yii\web\Response
     {
         $this->requirePostRequest();
 
-        // Settings über Plugin speichern
+        // Settings ber Plugin speichern
         Craft::$app->plugins->savePluginSettings(Plugin::getInstance(), ['apiKey' => null]);
-        Craft::$app->getSession()->setNotice('API-Key wurde gelöscht.');
+        Craft::$app->getSession()->setNotice('API-Key wurde gelscht.');
 
         return $this->redirectToPostedUrl();
     }
+
+    /**
+     * @throws \Exception
+     */
+    public function actionSettings(): \yii\web\Response
+    {
+        $plugin = Plugin::getInstance();
+        if (!$plugin) {
+            throw new \Exception('Plugin nicht initialisiert');
+        }
+
+        $settings = $plugin->getSettings();
+        if (!$settings) {
+            // Fallback: neue Settings erstellen
+            $settings = new Settings();
+        }
+
+        return $this->renderTemplate('diffbase/index', [
+            'plugin' => $plugin,
+            'settings' => $settings,
+        ]);
+    }
 }

src/models/Settings.php

@@ -10,13 +10,13 @@ class Settings extends Model
     public function rules(): array
     {
         return [
-            [['apiKey'], 'string', 'max' => 255],
+            ['apiKey', 'string'],
+            ['apiKey', 'default', 'value' => null],
         ];
     }
 
     public function generateApiKey(): string
     {
-        $this->apiKey = bin2hex(random_bytes(32));
-        return $this->apiKey;
+        return bin2hex(random_bytes(32));
     }
 }

src/templates/index.twig

@@ -55,20 +55,12 @@
   </div>
 
   <script>
-    function copyApiKey() {
-      const field = document.getElementById('apiKeyField');
-      field.select();
-      document.execCommand('copy');
+      function copyApiKey() {
+          const field = document.getElementById('apiKeyField');
+          field.select();
+          document.execCommand('copy');
 
-      Craft.cp.displayNotice('API-Key in Zwischenablage kopiert');
-    }
+          Craft.cp.displayNotice('API-Key in Zwischenablage kopiert');
+      }
   </script>
-{% endblock %}
-
-{#              <form method="post" action="{{ actionUrl('diffbase/cp/delete-api-key') }}" style="display: inline; margin: 0;">
-                {{ csrfInput() }}
-                {{ redirectInput('diffbase') }}
-                <button type="submit" class="btn secondary" onclick="return confirm('API-Key wirklich löschen?')">
-                  Löschen
-                </button>
-              </form>#}
+{% endblock %}