Add docblocks and improve API key management

Added detailed PHP docblocks to controllers, models, and services for better code documentation and maintainability. Improved API key management in CpController, including corrected German notice text. Enhanced Twig templates with comments and clarified API key UI logic. No functional changes, only documentation and minor UI improvements.

Author: stefanladner

src/controllers/CpController.php

@@ -14,22 +14,30 @@
 use yii\base\NotSupportedException;
 use yii\web\BadRequestHttpException;
 use yii\web\MethodNotAllowedHttpException;
+use yii\web\Response;
 use yii\web\ServerErrorHttpException;
 
+/**
+ * Class CpController
+ *
+ * This controller handles the Control Panel (CP) actions for the plugin.
+ * It provides methods for managing plugin settings, such as generating or deleting API keys.
+ *
+ * @package digitaldiff\diffbase\controllers
+ */
 class CpController extends Controller
 {
-
     /**
-     * @throws NotSupportedException
-     * @throws InvalidConfigException
-     * @throws MissingComponentException
-     * @throws ServerErrorHttpException
-     * @throws StaleResourceException
-     * @throws BusyResourceException
-     * @throws ErrorException
-     * @throws Exception
+     * Renders the main settings page for the plugin.
+     *
+     * - Initializes the plugin and its settings.
+     * - Automatically generates an API key if none exists.
+     *
+     * @throws MissingComponentException If a required component is missing.
+     * @throws Exception If the plugin is not initialized.
+     * @return Response The rendered settings page.
      */
-    public function actionIndex(): \yii\web\Response
+    public function actionIndex(): Response
     {
         $plugin = Plugin::getInstance();
         if (!$plugin) {
@@ -54,6 +62,11 @@ public function actionIndex(): \yii\web\Response
         ]);
     }
 
+    /**
+     * Retrieves the plugin settings.
+     *
+     * @return Settings The plugin settings model.
+     */
     private function getSettings(): Settings
     {
         /** @var Settings $settings */
@@ -62,18 +75,24 @@ private function getSettings(): Settings
     }
 
     /**
-     * @throws NotSupportedException
-     * @throws InvalidConfigException
-     * @throws MissingComponentException
-     * @throws MethodNotAllowedHttpException
-     * @throws ServerErrorHttpException
-     * @throws BadRequestHttpException
-     * @throws StaleResourceException
-     * @throws BusyResourceException
-     * @throws ErrorException
-     * @throws Exception
+     * Generates a new API key and saves it to the plugin settings.
+     *
+     * - Requires a POST request.
+     * - Displays a success notice upon completion.
+     *
+     * @throws NotSupportedException If the operation is not supported.
+     * @throws InvalidConfigException If the configuration is invalid.
+     * @throws MissingComponentException If a required component is missing.
+     * @throws MethodNotAllowedHttpException If the request method is not allowed.
+     * @throws ServerErrorHttpException If a server error occurs.
+     * @throws BadRequestHttpException If the request is invalid.
+     * @throws StaleResourceException If the resource is stale.
+     * @throws BusyResourceException If the resource is busy.
+     * @throws ErrorException If an error occurs during execution.
+     * @throws Exception If an unexpected error occurs.
+     * @return Response A redirect response to the posted URL.
      */
-    public function actionGenerateApiKey(): \yii\web\Response
+    public function actionGenerateApiKey(): Response
     {
         $this->requirePostRequest();
 
@@ -88,25 +107,36 @@ public function actionGenerateApiKey(): \yii\web\Response
     }
 
     /**
-     * @throws MissingComponentException
-     * @throws MethodNotAllowedHttpException
-     * @throws BadRequestHttpException
+     * Deletes the existing API key from the plugin settings.
+     *
+     * - Requires a POST request.
+     * - Displays a success notice upon completion.
+     *
+     * @throws MissingComponentException If a required component is missing.
+     * @throws MethodNotAllowedHttpException If the request method is not allowed.
+     * @throws BadRequestHttpException If the request is invalid.
+     * @return Response A redirect response to the posted URL.
      */
-    public function actionDeleteApiKey(): \yii\web\Response
+    public function actionDeleteApiKey(): Response
     {
         $this->requirePostRequest();
 
         // Settings ber Plugin speichern
         Craft::$app->plugins->savePluginSettings(Plugin::getInstance(), ['apiKey' => null]);
-        Craft::$app->getSession()->setNotice('API-Key wurde gelscht.');
+        Craft::$app->getSession()->setNotice('API-Key wurde gelöscht.');
 
         return $this->redirectToPostedUrl();
     }
 
     /**
-     * @throws \Exception
+     * Renders the settings page for the plugin.
+     *
+     * - Initializes the plugin and its settings.
+     *
+     * @throws \Exception If the plugin is not initialized.
+     * @return Response The rendered settings page.
      */
-    public function actionSettings(): \yii\web\Response
+    public function actionSettings(): Response
     {
         $plugin = Plugin::getInstance();
         if (!$plugin) {

src/models/Settings.php

@@ -2,19 +2,45 @@
 namespace digitaldiff\diffbase\models;
 
 use craft\base\Model;
+use Random\RandomException;
 
+/**
+ * Class Settings
+ *
+ * This model represents the settings for the "diff. base plugin".
+ * It is used to store and validate the plugin's configuration, such as the API key.
+ *
+ * @package digitaldiff\diffbase\models
+ */
 class Settings extends Model
 {
+    /**
+     * @var string|null $apiKey The API key used for authentication. Defaults to null.
+     */
     public ?string $apiKey = null;
 
+    /**
+     * Returns the validation rules for the model's attributes.
+     *
+     * @return array The validation rules for the `apiKey` attribute.
+     */
     public function rules(): array
     {
         return [
-            ['apiKey', 'string'],
-            ['apiKey', 'default', 'value' => null],
+            ['apiKey', 'string'], // Ensures the API key is a string.
+            ['apiKey', 'default', 'value' => null], // Sets the default value of the API key to null.
         ];
     }
 
+    /**
+     * Generates a new random API key.
+     *
+     * This method uses `random_bytes` to generate a secure 32-byte random string,
+     * which is then converted to a hexadecimal representation.
+     *
+     * @throws RandomException If an appropriate source of randomness cannot be found.
+     * @return string The generated API key as a 64-character hexadecimal string.
+     */
     public function generateApiKey(): string
     {
         return bin2hex(random_bytes(32));

src/services/ApiService.php

@@ -4,14 +4,35 @@
 use craft\base\Component;
 use digitaldiff\diffbase\Plugin;
 
+/**
+ * Class ApiService
+ *
+ * This service handles API-related business logic for the plugin.
+ * It provides methods for validating API keys and retrieving system data.
+ *
+ * @package digitaldiff\diffbase\services
+ */
 class ApiService extends Component
 {
+    /**
+     * Validates the provided API key against the stored plugin settings.
+     *
+     * @param string $key The API key to validate.
+     * @return bool True if the API key matches the stored key, false otherwise.
+     */
     public function validateApiKey(string $key): bool
     {
         $settings = Plugin::getInstance()->getSettings();
         return $settings->apiKey === $key;
     }
 
+    /**
+     * Retrieves system data for the API, including plugin and API status.
+     *
+     * @return array An associative array containing:
+     * - `api_enabled` (bool): Whether the API is enabled (based on the presence of an API key).
+     * - `version` (string): The current version of the plugin.
+     */
     public function getSystemData(): array
     {
         $settings = Plugin::getInstance()->getSettings();

src/templates/index.twig

@@ -1,3 +1,21 @@
+{#
+This Twig template extends the Craft CMS Control Panel layout and provides the interface for the "diff. base plugin" settings page.
+
+Template Details:
+- Displays the current API key if available.
+- Allows users to copy the API key, generate a new one, or access the API endpoint.
+- Includes a JavaScript function for copying the API key to the clipboard.
+
+Variables:
+- `settings.apiKey`: The current API key stored in the plugin settings.
+
+Blocks:
+- `content`: Contains the main content of the settings page, including the API key management interface.
+
+Notes:
+- Ensure the `settings.apiKey` variable is properly passed to the template.
+- The `copyApiKey` JavaScript function uses Craft's `Craft.cp.displayNotice` for user feedback.
+#}
 {% extends "_layouts/cp" %}
 {% set title = "diff. base plugin" %}
 {% set crumbs = [
@@ -32,34 +50,35 @@
                   {% if settings.apiKey %}
                     Neuen API-Key generieren
                   {% else %}
-                    API-Key generieren
                   {% endif %}
+                  API-Key generieren
                 </button>
               </form>
 
               <a href="{{ siteUrl }}api/info?key={{ settings.apiKey }}" class="view-btn btn" target="_blank">
                 {{ svg('@appicons/external-link.svg') }}
                 API-Endpunkt aufrufen
               </a>
-
-
             </div>
           </div>
         </div>
-
       {% endif %}
 
       <hr>
     </div>
   </div>
 
   <script>
+      /**
+       * Copies the API key to the clipboard and displays a success notice.
+       */
       function copyApiKey() {
           const field = document.getElementById('apiKeyField');
           field.select();
           document.execCommand('copy');
 
+          // Display a success message using Craft's control panel notice system
           Craft.cp.displayNotice('API-Key in Zwischenablage kopiert');
       }
   </script>
-{% endblock %}
+{% endblock %}

src/templates/settings.twig

@@ -1 +1,12 @@
-{% redirect "diffbase" %}
+{#
+This Twig template redirects the user to the main "diffbase" section of the Craft CMS Control Panel.
+
+Usage:
+- This template is typically used as a placeholder or entry point for the plugin's settings page.
+- When accessed, it automatically redirects the user to the "diffbase" route.
+
+Notes:
+- Ensure that the "diffbase" route is properly defined in your plugin's `src/controllers/CpController.php`.
+- This template does not render any content; it only performs a redirect.
+#}
+{% redirect "diffbase" %}