x-scenarios README

README.md

@@ -186,6 +186,224 @@ Such values are not allowed:
 
 If `enum` and `x-db-type` both are provided then for database column schema (migrations), only `x-db-type` will be considered ignoring `enum`.
 
+### `x-scenarios`
+
+Automatically generated scenarios from the model 'x-scenarios'.
+Each scenario is assigned attributes as in the 'default' scenario.
+The advantage is that the scenario can be used immediately.
+This can be overridden in the child model if needed.
+
+The 'default' scenario and all scenarios mentioned in the rules() using 'on' and 'except'
+are automatically included in the scenarios() function for the model.
+
+There are three ways to define the scenarios `description`:
+- use scenario description default settings `public $scenarioDefaultDescription = "Scenario {scenarioName}"`.
+- use custom `scenarioDefaultDescription` at `dbModel`.
+- use custom `description` for individual scenario.
+
+1. Example with default setting.
+    ```yaml
+        Invoice:
+          type: object
+          x-scenarios:
+            - name: create
+            - name: update
+    ```
+
+   The following code is generated in the abstract model:
+    ```php
+    abstract class Invoice extends \yii\db\ActiveRecord
+    {
+        /**
+         * Scenario create
+         */
+        public const SCENARIO_CREATE = 'create';
+
+        /**
+         * Scenario update
+         */
+        public const SCENARIO_UPDATE = 'update';
+
+        /**
+         * Automatically generated scenarios from the model 'x-scenarios'.
+         * @return array a list of scenarios and the corresponding active attributes.
+         */
+        public function scenarios()
+        {
+            $parentScenarios = parent::scenarios();
+
+            /**
+             * Each scenario is assigned attributes as in the 'default' scenario.
+             * The advantage is that the scenario can be used immediately.
+             * This can be overridden in the child model if needed.
+             */
+            $default = $parentScenarios[self::SCENARIO_DEFAULT];
+
+            return [
+               self::SCENARIO_CREATE => $default,
+               self::SCENARIO_UPDATE => $default,
+               /**
+                * The 'default' scenario and all scenarios mentioned in the rules() using 'on' and 'except'
+                * are automatically included in the scenarios() function for the model.
+                */
+               ...$parentScenarios,
+            ];
+        }
+      }
+      ```
+
+2. Example with custom `description` for individual scenario.
+    ```yaml
+        Invoice:
+          type: object
+          x-scenarios:
+            - name: create
+              description: My custom description for scenario create
+            - name: update
+    ```
+
+   The following code is generated in the abstract model:
+    ```php
+    abstract class Invoice extends \yii\db\ActiveRecord
+    {
+        /**
+         * My custom description for scenario create
+         */
+        public const SCENARIO_CREATE = 'create';
+
+        /**
+         * Scenario update
+         */
+        public const SCENARIO_UPDATE = 'update';
+
+        /**
+         * Automatically generated scenarios from the model 'x-scenarios'.
+         * @return array a list of scenarios and the corresponding active attributes.
+         */
+        public function scenarios()
+        {...}
+      }
+      ```
+
+3. Example with custom `scenarioDefaultDescription`.
+
+   Set custom `scenarioDefaultDescription` at `dbModel`.
+   `scenarioDefaultDescription` Accepted-Placeholder: {scenarioName}, {scenarioConst}, {modelName}.
+
+   For example, for the `create` scenario in the `Invoice` model, the placeholders would result in the following:
+   `{scenarioName}` = `create`
+   `{scenarioConst}` = `SCENARIO_CREATE`
+   `{modelName}` = `Invoice`
+
+    php-config-settings
+    ```php
+    $config['modules']['gii']['generators']['api'] = [
+        'class' => \cebe\yii2openapi\generator\ApiGenerator::class,
+        'dbModel' => [
+            /** Accepted-Placeholder: {scenarioName}, {scenarioConst}, {modelName}. @see DbModel::$scenarioDefaultDescription */
+            'scenarioDefaultDescription' => "This scenario \"{scenarioName}\" at Model \"{modelName}\" has Constant {scenarioConst}.",
+        ],
+        ...
+    ];
+    ```
+
+    ```yaml
+        Invoice:
+          type: object
+          x-scenarios:
+            - name: create
+              description: My custom description for scenario create
+            - name: update
+    ```
+
+   The following code is generated in the abstract model:
+    ```php
+    abstract class Invoice extends \yii\db\ActiveRecord
+    {
+        /**
+         * My custom description for scenario create
+         */
+        public const SCENARIO_CREATE = 'create';
+
+        /**
+         * This scenario "update" at Model "Invoice" has Constant SCENARIO_UPDATE.
+         */
+        public const SCENARIO_UPDATE = 'update';
+
+        /**
+         * Automatically generated scenarios from the model 'x-scenarios'.
+         * @return array a list of scenarios and the corresponding active attributes.
+         */
+        public function scenarios()
+        {...}
+      }
+      ```
+
+4. Example with custom `scenarioDefaultDescription`
+   and use-case: both '\cebe\yii2openapi\generator\ApiGenerator::class' and '\common\client_generator\{your_ApiClientGenerator}::class' are used.
+
+   Set custom `scenarioDefaultDescription` at `dbModel`.
+   `scenarioDefaultDescription` Accepted-Placeholder: {scenarioName}, {scenarioConst}, {modelName}.
+
+    php-config-settings
+    ```php
+    $config['modules']['gii']['generators']['api'] = [
+        'class' => \cebe\yii2openapi\generator\ApiGenerator::class,
+        'dbModel' => [
+            /** Accepted-Placeholder: {scenarioName}, {scenarioConst}, {modelName}. @see DbModel::$scenarioDefaultDescription */
+            'scenarioDefaultDescription' => implode("\n", [
+                "This Backend-Scenario \"{scenarioName}\" exist in both the frontend model and the backend model.",
+                "@see \common\client\models\{modelName}::{scenarioConst}",
+            ]),
+        ],
+        ...
+    ];
+
+   $config['modules']['gii']['generators']['api-client'] = [
+       'class' => \common\client_generator\{your_ApiClientGenerator}::class,
+       'dbModel' => [
+           /** AcceptedInputs: {scenarioName}, {scenarioConst}, {modelName}. @see DbModel::$scenarioDefaultDescription */
+           'scenarioDefaultDescription' => implode("\n", [
+               "This Frontend-Scenario \"{scenarioName}\" exist in both the frontend model and the backend model.",
+               "@see \common\models\base\{modelName}::{scenarioConst}",
+           ]),
+       ],
+       ...
+    ```
+
+    ```yaml
+        Invoice:
+          type: object
+          x-scenarios:
+            - name: create
+            - name: update
+    ```
+
+   The following code is generated in the abstract model:
+    ```php
+    abstract class Invoice extends \yii\db\ActiveRecord
+    {
+        /**
+         * This Backend-Scenario "create" exist in both the frontend model and the backend model.
+         * @see \common\client\models\Invoice::SCENARIO_CREATE
+         */
+        public const SCENARIO_CREATE = 'create';
+
+        /**
+         * This Backend-Scenario "update" exist in both the frontend model and the backend model.
+         * @see \common\client\models\Invoice::SCENARIO_UPDATE
+         */
+        public const SCENARIO_UPDATE = 'update';
+
+        /**
+         * Automatically generated scenarios from the model 'x-scenarios'.
+         * @return array a list of scenarios and the corresponding active attributes.
+         */
+        public function scenarios()
+        {...}
+    }
+    ```
+
 ### `x-indexes`
 
 Specify table indexes

src/generator/ApiGenerator.php

@@ -143,7 +143,7 @@ class ApiGenerator extends Generator
     /**
      * @var array Map for custom dbModels
      *
-     * @see DbModel::$scenarioDefaultDescription with acceptedInputs: {scenarioName}, {scenarioConst}, {modelName}.
+     * @see DbModel::$scenarioDefaultDescription with Accepted-Placeholder: {scenarioName}, {scenarioConst}, {modelName}.
      * @example
      *  'dbModel' => [
      *      'scenarioDefaultDescription' => "Scenario {scenarioName}",

src/generator/default/dbmodel.php

@@ -84,12 +84,14 @@ public static function tableName()
      */
     public function scenarios()
     {
+        $parentScenarios = parent::scenarios();
+
         /**
          * Each scenario is assigned attributes as in the 'default' scenario.
          * The advantage is that the scenario can be used immediately.
          * This can be overridden in the child model if needed.
          */
-        $default = parent::scenarios()[self::SCENARIO_DEFAULT];
+        $default = $parentScenarios[self::SCENARIO_DEFAULT];
 
         return [
 <?php foreach ($scenarios as $scenario): ?>
@@ -99,7 +101,7 @@ public function scenarios()
              * The 'default' scenario and all scenarios mentioned in the rules() using 'on' and 'except'
              * are automatically included in the scenarios() function for the model.
              */
-            ...parent::scenarios(),
+            ...$parentScenarios,
         ];
     }
 <?php endif;?>

src/lib/Config.php

@@ -112,7 +112,7 @@ class Config extends BaseObject
     /**
      * @var array Map for custom dbModels
      *
-     * @see DbModel::$scenarioDefaultDescription with acceptedInputs: {scenarioName}, {scenarioConst}, {modelName}.
+     * @see DbModel::$scenarioDefaultDescription with Accepted-Placeholder: {scenarioName}, {scenarioConst}, {modelName}.
      * @example
      *  'dbModel' => [
      *      'scenarioDefaultDescription' => "Scenario {scenarioName}",

src/lib/items/DbModel.php

@@ -84,7 +84,7 @@ class DbModel extends BaseObject
     /**
      * @var string
      * Here, you can set your own default description for the scenario.
-     * AcceptedInputs: {scenarioName}, {scenarioConst}, {modelName}.
+     * Accepted-Placeholder: {scenarioName}, {scenarioConst}, {modelName}.
      */
     public $scenarioDefaultDescription = "Scenario {scenarioName}";