cleanUp + getScenarios description

Author: siggi-k

src/generator/ApiGenerator.php

@@ -136,10 +136,11 @@ class ApiGenerator extends Generator
 
     /**
      * @var array Map for custom dbModels
+     *
+     * @see DbModel::$scenarioDefaultDescription with acceptedInputs: {scenarioName}, {scenarioConst}, {modelName}.
      * @example
      *  'dbModel' => [
-     *      AcceptedInputs: {scenarioName}, {scenarioConst}, {modelName}.
-     *      'scenarioDefaultDescription' => " Scenario {scenarioName}",     @see DbModel::$scenarioDefaultDescription
+     *      'scenarioDefaultDescription' => "Scenario {scenarioName}",
      *  ]
      */
     public $dbModel = [];

src/lib/Config.php

@@ -111,10 +111,11 @@ class Config extends BaseObject
 
     /**
      * @var array Map for custom dbModels
+     *
+     * @see DbModel::$scenarioDefaultDescription with acceptedInputs: {scenarioName}, {scenarioConst}, {modelName}.
      * @example
      *  'dbModel' => [
-     *      AcceptedInputs: {scenarioName}, {scenarioConst}, {modelName}.
-     *      'scenarioDefaultDescription' => " Scenario {scenarioName}",     @see DbModel::$scenarioDefaultDescription
+     *      'scenarioDefaultDescription' => "Scenario {scenarioName}",
      *  ]
      */
     public $dbModel = [];

src/lib/items/DbModel.php

@@ -85,7 +85,7 @@ class DbModel extends BaseObject
     /**
      * @var array Automatically generated scenarios from the model 'x-scenarios'.
      */
-    private array $scenarios;
+    private $_scenarios;
 
     /**
      * @var string
@@ -193,18 +193,72 @@ public function dbAttributes():array
     }
 
     /**
+     * Returns a scenarios array based on the 'x-scenarios'.
+     * Each scenario has the following properties: 'name', 'const', and 'description'.
+     *
+     * When the `getScenarios` function is called for the first time on this model,
+     * the value is stored in `_scenarios` and then returned.
+     * If the `getScenariosByOpenapiSchema` function is called again on this model,
+     * the stored value from `_scenarios` is returned.
+     *
      * @return array
      */
     public function getScenarios(): array
     {
-        if (isset($this->scenarios)) {
-            return $this->scenarios;
+        if (isset($this->_scenarios)) {
+            return $this->_scenarios;
         }
-        $this->scenarios = $this->getScenariosByOpenapiSchema();
-        return $this->scenarios;
+        $this->_scenarios = $this->getScenariosByOpenapiSchema();
+        return $this->_scenarios;
     }
 
     /**
+     * Returns a scenarios array based on the 'x-scenarios'.
+     * Each scenario has the following properties: 'name', 'const', and 'description'.
+     *
+     * Example for 'schema.yaml':
+     * x-scenarios:
+     *   - name: create
+     *     description: My custom description for scenario create
+     *   - name: update
+     *
+     * 1) With default @see $scenarioDefaultDescription = "Scenario {scenarioName}"
+     *
+     * The resulting array:
+     *  [
+     *      [
+     *          'name' => 'create',
+     *          'const' => 'SCENARIO_CREATE',
+     *          'description' => "My custom description for scenario create",
+     *      ],
+     *      [
+     *          'name' => 'update',
+     *          'const' => 'SCENARIO_UPDATE',
+     *          'description' => "Scenario update",
+     *      ],
+     *  ]
+     *
+     * 2) With custom @see $scenarioDefaultDescription = implode("\n", [
+     *      "This Backend-Scenario \"{scenarioName}\" exist in both the frontend model and the backend model.",
+     *      "@see \common\client\models\{modelName}::{scenarioConst}",
+     *  ]);
+     *
+     * For the 'update' scenario, it is an example of a two-line description.
+     * E.g. your modelName is 'Project'.
+     * The resulting array:
+     *  [
+     *      [
+     *          'name' => 'create',
+     *          'const' => 'SCENARIO_CREATE',
+     *          'description' => "My custom description for scenario create",
+     *      ],
+     *      [
+     *          'name' => 'update',
+     *          'const' => 'SCENARIO_UPDATE',
+     *          'description' => "This Backend-Scenario \"update\" exist in both the frontend model and the backend model.\n@see \common\client\models\Project::SCENARIO_UPDATE",
+     *      ],
+     *  ]
+     *
      * @return array
      */
     private function getScenariosByOpenapiSchema(): array