Resolve: Description of a property in spec must correspond to DB TABLE COLUMN COMMENT #60

src/generator/default/dbmodel.php

@@ -49,8 +49,8 @@
  */
 abstract class <?= $model->getClassName() ?> extends \yii\db\ActiveRecord
 {
-<?php if($scenarios = $model->getScenarios()):
-foreach($scenarios as $scenario): ?>
+<?php if ($scenarios = $model->getScenarios()):
+foreach ($scenarios as $scenario): ?>
     /**
      *<?= $scenario['description'] ?>
 
@@ -76,7 +76,7 @@ public static function tableName()
     {
         return <?= var_export($model->getTableAlias()) ?>;
     }
-<?php if($scenarios): ?>
+<?php if ($scenarios): ?>
 
     /**
      * Automatically generated scenarios from the model 'x-scenarios'.
@@ -92,7 +92,7 @@ public function scenarios()
         $default = parent::scenarios()[self::SCENARIO_DEFAULT];
 
         return [
-<?php foreach($scenarios as $scenario): ?>
+<?php foreach ($scenarios as $scenario): ?>
             self::<?= $scenario['const'] ?> => $default,
 <?php endforeach; ?>
             /**

src/lib/ColumnToCode.php

@@ -84,9 +84,9 @@ class ColumnToCode
      */
     private $isPk = false;
 
-    private $rawParts = ['type' => null, 'nullable' => null, 'default' => null, 'position' => null];
+    private $rawParts = ['type' => null, 'nullable' => null, 'default' => null, 'position' => null, 'comment' => null];
 
-    private $fluentParts = ['type' => null, 'nullable' => null, 'default' => null, 'position' => null];
+    private $fluentParts = ['type' => null, 'nullable' => null, 'default' => null, 'position' => null, 'comment' => null];
 
     /**
      * @var bool
@@ -150,6 +150,60 @@ public function __construct(
         $this->resolve();
     }
 
+    private function resolve():void
+    {
+        $dbType = $this->typeWithoutSize(strtolower($this->column->dbType));
+        $type = $this->column->type;
+        $this->resolvePosition();
+        //Primary Keys
+        if (array_key_exists($type, self::PK_TYPE_MAP)) {
+            $this->rawParts['type'] = $type;
+            $this->fluentParts['type'] = self::PK_TYPE_MAP[$type];
+            $this->isPk = true;
+            return;
+        }
+        if (array_key_exists($dbType, self::PK_TYPE_MAP)) {
+            $this->rawParts['type'] = $dbType;
+            $this->fluentParts['type'] = self::PK_TYPE_MAP[$dbType];
+            $this->isPk = true;
+            return;
+        }
+
+        if ($dbType === 'varchar') {
+            $type = $dbType = 'string';
+        }
+        $fluentSize = $this->column->size ? '(' . $this->column->size . ')' : '()';
+        $rawSize = $this->column->size ? '(' . $this->column->size . ')' : '';
+        $this->rawParts['nullable'] = $this->column->allowNull ? 'NULL' : 'NOT NULL';
+        $this->fluentParts['nullable'] = $this->column->allowNull === true ? 'null()' : 'notNull()';
+
+        $this->fluentParts['comment'] = $this->column->comment ? 'comment('.var_export($this->column->comment, true).')' : $this->fluentParts['comment'];
+        $this->rawParts['comment'] = $this->column->comment ? 'COMMENT '.var_export($this->column->comment, true) : $this->rawParts['comment'];
+
+        if (array_key_exists($dbType, self::INT_TYPE_MAP)) {
+            $this->fluentParts['type'] = self::INT_TYPE_MAP[$dbType] . $fluentSize;
+            $this->rawParts['type'] =
+                $this->column->dbType . (strpos($this->column->dbType, '(') !== false ? '' : $rawSize);
+        } elseif (array_key_exists($type, self::INT_TYPE_MAP)) {
+            $this->fluentParts['type'] = self::INT_TYPE_MAP[$type] . $fluentSize;
+            $this->rawParts['type'] =
+                $this->column->dbType . (strpos($this->column->dbType, '(') !== false ? '' : $rawSize);
+        } elseif ($this->isEnum()) {
+            $this->resolveEnumType();
+        } elseif ($this->isDecimal()) {
+            $this->fluentParts['type'] = $this->column->dbType;
+            $this->rawParts['type'] = $this->column->dbType;
+        } else {
+            $this->fluentParts['type'] = $type . $fluentSize;
+            $this->rawParts['type'] =
+                $this->column->dbType . (strpos($this->column->dbType, '(') !== false ? '' : $rawSize);
+        }
+
+        $this->isBuiltinType = $this->raw ? false : $this->getIsBuiltinType($type, $dbType);
+
+        $this->resolveDefaultValue();
+    }
+
     public function getCode(bool $quoted = false):string
     {
         if ($this->isPk) {
@@ -160,7 +214,8 @@ public function getCode(bool $quoted = false):string
                 $this->fluentParts['type'],
                 $this->fluentParts['nullable'],
                 $this->fluentParts['default'],
-                $this->fluentParts['position']
+                $this->fluentParts['position'],
+                $this->fluentParts['comment'],
             ]);
             array_unshift($parts, '$this');
             return implode('->', array_filter(array_map('trim', $parts)));
@@ -175,9 +230,12 @@ public function getCode(bool $quoted = false):string
         }
 
         $code = $this->rawParts['type'] . ' ' . $this->rawParts['nullable'] . $default;
-        if ((ApiGenerator::isMysql() || ApiGenerator::isMariaDb()) && $this->rawParts['position']) {
-            $code .= ' ' . $this->rawParts['position'];
+
+        if ((ApiGenerator::isMysql() || ApiGenerator::isMariaDb())) {
+            $code .= $this->rawParts['position'] ? ' ' . $this->rawParts['position'] : '';
+            $code .= $this->rawParts['comment'] ? ' '.$this->rawParts['comment'] : '';
         }
+
         if (ApiGenerator::isPostgres() && $this->alterByXDbType) {
             return $quoted ? VarDumper::export($this->rawParts['type']) : $this->rawParts['type'];
         }
@@ -320,56 +378,6 @@ private function defaultValueArray(array $value):string
         return "'{" . trim(Json::encode($value, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_HEX_QUOT), '[]') . "}'";
     }
 
-    private function resolve():void
-    {
-        $dbType = $this->typeWithoutSize(strtolower($this->column->dbType));
-        $type = $this->column->type;
-        $this->resolvePosition();
-        //Primary Keys
-        if (array_key_exists($type, self::PK_TYPE_MAP)) {
-            $this->rawParts['type'] = $type;
-            $this->fluentParts['type'] = self::PK_TYPE_MAP[$type];
-            $this->isPk = true;
-            return;
-        }
-        if (array_key_exists($dbType, self::PK_TYPE_MAP)) {
-            $this->rawParts['type'] = $dbType;
-            $this->fluentParts['type'] = self::PK_TYPE_MAP[$dbType];
-            $this->isPk = true;
-            return;
-        }
-
-        if ($dbType === 'varchar') {
-            $type = $dbType = 'string';
-        }
-        $fluentSize = $this->column->size ? '(' . $this->column->size . ')' : '()';
-        $rawSize = $this->column->size ? '(' . $this->column->size . ')' : '';
-        $this->rawParts['nullable'] = $this->column->allowNull ? 'NULL' : 'NOT NULL';
-        $this->fluentParts['nullable'] = $this->column->allowNull === true ? 'null()' : 'notNull()';
-        if (array_key_exists($dbType, self::INT_TYPE_MAP)) {
-            $this->fluentParts['type'] = self::INT_TYPE_MAP[$dbType] . $fluentSize;
-            $this->rawParts['type'] =
-                $this->column->dbType . (strpos($this->column->dbType, '(') !== false ? '' : $rawSize);
-        } elseif (array_key_exists($type, self::INT_TYPE_MAP)) {
-            $this->fluentParts['type'] = self::INT_TYPE_MAP[$type] . $fluentSize;
-            $this->rawParts['type'] =
-                $this->column->dbType . (strpos($this->column->dbType, '(') !== false ? '' : $rawSize);
-        } elseif ($this->isEnum()) {
-            $this->resolveEnumType();
-        } elseif ($this->isDecimal()) {
-            $this->fluentParts['type'] = $this->column->dbType;
-            $this->rawParts['type'] = $this->column->dbType;
-        } else {
-            $this->fluentParts['type'] = $type . $fluentSize;
-            $this->rawParts['type'] =
-                $this->column->dbType . (strpos($this->column->dbType, '(') !== false ? '' : $rawSize);
-        }
-
-        $this->isBuiltinType = $this->raw ? false : $this->getIsBuiltinType($type, $dbType);
-
-        $this->resolveDefaultValue();
-    }
-
     /**
      * @param $type
      * @param $dbType

src/lib/items/Attribute.php

@@ -318,6 +318,7 @@ public function toColumnSchema():ColumnSchema
             'allowNull' => $this->allowNull(),
             'size' => $this->size > 0 ? $this->size : null,
             'xDbType' => $this->xDbType,
+            'comment' => $this->description,
         ]);
         $column->isPrimaryKey = $this->primary;
         $column->autoIncrement = $this->primary && $this->phpType === 'int';

src/lib/migrations/BaseMigrationBuilder.php

@@ -161,6 +161,8 @@ public function buildFresh():MigrationModel
             }
         }
 
+        $this->handleCommentsMigration();
+
         return $this->migration;
     }
 
@@ -275,6 +277,8 @@ abstract public static function getColumnSchemaBuilderClass(): string;
      */
     abstract protected function findTableIndexes():array;
 
+    abstract public function handleCommentsMigration();
+
     protected function buildIndexChanges():void
     {
         $haveIndexes = $this->findTableIndexes();
@@ -445,14 +449,17 @@ public function tmpSaveNewCol(string $tableAlias, \cebe\yii2openapi\db\ColumnSch
         if (ApiGenerator::isPostgres() && static::isEnum($columnSchema)) {
             $allEnumValues = $columnSchema->enumValues;
             $allEnumValues = array_map(function ($aValue) {
-                return "'$aValue'";
+                return $this->db->quoteValue($aValue);
             }, $allEnumValues);
             Yii::$app->db->createCommand(
                 'CREATE TYPE '.$tmpEnumName($columnSchema->name).' AS ENUM('.implode(', ', $allEnumValues).')'
             )->execute();
         }
 
         Yii::$app->db->createCommand()->createTable($tmpTableName, $column)->execute();
+        if (ApiGenerator::isPostgres() && $columnSchema->comment) {
+            Yii::$app->db->createCommand("COMMENT ON COLUMN $tmpTableName.$columnSchema->name IS {$this->db->quoteValue($columnSchema->comment)}")->execute();
+        }
 
         $table = Yii::$app->db->getTableSchema($tmpTableName);
 

src/lib/migrations/MigrationRecordBuilder.php

@@ -46,6 +46,10 @@ final class MigrationRecordBuilder
 
     public const ALTER_COLUMN_RAW_PGSQL = MigrationRecordBuilder::INDENT . "\$this->db->createCommand('ALTER TABLE %s ALTER COLUMN \"%s\" SET DATA TYPE %s')->execute();";
 
+    public const ADD_COMMENT_ON_COLUMN = MigrationRecordBuilder::INDENT . "\$this->addCommentOnColumn('%s', '%s', %s);";
+
+    public const DROP_COMMENT_FROM_COLUMN = MigrationRecordBuilder::INDENT . "\$this->dropCommentFromColumn('%s', '%s');";
+
     /**
      * @var \yii\db\Schema
      */
@@ -345,4 +349,14 @@ public static function makeString(array $codeColumns): string
         $codeColumns = '['.PHP_EOL.self::INDENT.'    '.$codeColumns.PHP_EOL . self::INDENT.']';
         return $codeColumns;
     }
+
+    public function addCommentOnColumn($table, string $column, string $comment): string
+    {
+        return sprintf(self::ADD_COMMENT_ON_COLUMN, $table, $column, var_export($comment, true));
+    }
+
+    public function dropCommentFromColumn($table, string $column): string
+    {
+        return sprintf(self::DROP_COMMENT_FROM_COLUMN, $table, $column);
+    }
 }

src/lib/migrations/MysqlMigrationBuilder.php

@@ -14,9 +14,7 @@
 use yii\db\ColumnSchema;
 use yii\db\IndexConstraint;
 use yii\db\Schema;
-use \Yii;
 use yii\helpers\ArrayHelper;
-use yii\helpers\VarDumper;
 
 final class MysqlMigrationBuilder extends BaseMigrationBuilder
 {
@@ -56,7 +54,7 @@ protected function compareColumns(ColumnSchema $current, ColumnSchema $desired):
 
         foreach (['type', 'size', 'allowNull', 'defaultValue', 'enumValues'
                     , 'dbType', 'phpType'
-                    , 'precision', 'scale', 'unsigned'
+                     , 'precision', 'scale', 'unsigned', 'comment'
         ] as $attr) {
             if ($attr === 'defaultValue') {
                 if ($this->isDefaultValueChanged($current, $desiredFromDb)) {
@@ -159,4 +157,10 @@ public function modifyDesiredInContextOfCurrent(ColumnSchema $current, ColumnSch
             $desired->size = $current->size;
         }
     }
+
+    public function handleCommentsMigration()
+    {
+        // nothing to do here as comments can be defined in same statement as of alter/add column in MySQL
+        // this method is only for PgSQL
+    }
 }

src/lib/migrations/PostgresMigrationBuilder.php

@@ -9,7 +9,6 @@
 
 use cebe\yii2openapi\lib\items\DbIndex;
 use yii\db\ColumnSchema;
-use yii\helpers\VarDumper;
 use yii\helpers\ArrayHelper;
 
 final class PostgresMigrationBuilder extends BaseMigrationBuilder
@@ -65,7 +64,7 @@ protected function buildColumnChanges(ColumnSchema $current, ColumnSchema $desir
 
         if (!empty(array_intersect(['type', 'size'
                     , 'dbType', 'phpType'
-                    , 'precision', 'scale', 'unsigned'
+            , 'precision', 'scale', 'unsigned'
         ], $changed))) {
             $addUsing = $this->isNeedUsingExpression($current->dbType, $desired->dbType);
             $this->migration->addUpCode($this->recordBuilder->alterColumnType($tableName, $desired, $addUsing));
@@ -91,6 +90,17 @@ protected function buildColumnChanges(ColumnSchema $current, ColumnSchema $desir
                 $this->migration->addUpCode($upCode)->addDownCode($downCode, true);
             }
         }
+
+        if (in_array('comment', $changed, true)) {
+            if ($desired->comment) {
+                $this->migration->addUpCode($this->recordBuilder->addCommentOnColumn($tableName, $desired->name, $desired->comment));
+                $this->migration->addDownCode($this->recordBuilder->dropCommentFromColumn($tableName, $desired->name));
+            } else {
+                $this->migration->addUpCode($this->recordBuilder->dropCommentFromColumn($tableName, $desired->name));
+                $this->migration->addDownCode($this->recordBuilder->addCommentOnColumn($tableName, $desired->name, $current->comment));
+            }
+        }
+
         if ($isChangeToEnum) {
             $this->migration->addUpCode($this->recordBuilder->createEnum($tableName, $desired->name, $desired->enumValues), true);
         }
@@ -127,7 +137,7 @@ protected function compareColumns(ColumnSchema $current, ColumnSchema $desired):
 
         foreach (['type', 'size', 'allowNull', 'defaultValue', 'enumValues'
                     , 'dbType', 'phpType'
-                    , 'precision', 'scale', 'unsigned'
+                     , 'precision', 'scale', 'unsigned', 'comment'
         ] as $attr) {
             if ($attr === 'defaultValue') {
                 if ($this->isDefaultValueChanged($current, $desiredFromDb)) {
@@ -248,4 +258,15 @@ public function modifyDesiredInContextOfCurrent(ColumnSchema $current, ColumnSch
             $desired->size = $current->size;
         }
     }
+
+    public function handleCommentsMigration()
+    {
+        $tableAlias = $this->model->getTableAlias();
+        foreach ($this->newColumns as $column) {
+            if ($column->comment) {
+                $this->migration
+                    ->addUpCode($this->recordBuilder->addCommentOnColumn($tableAlias, $column->name, $column->comment));
+            }
+        }
+    }
 }

tests/specs/blog/migrations/m200000_000002_create_table_blog_posts.php

@@ -11,10 +11,10 @@ public function up()
             0 => 'uid varchar(128) NOT NULL',
             'title' => $this->string(255)->notNull(),
             'slug' => $this->string(200)->null()->defaultValue(null),
-            'category_id' => $this->integer()->notNull(),
+            'category_id' => $this->integer()->notNull()->comment('Category of posts'),
             'active' => $this->boolean()->notNull()->defaultValue(false),
             'created_at' => $this->date()->null()->defaultValue(null),
-            'created_by_id' => $this->integer()->null()->defaultValue(null),
+            'created_by_id' => $this->integer()->null()->defaultValue(null)->comment('The User'),
         ]);
         $this->addPrimaryKey('pk_blog_posts_uid', '{{%blog_posts}}', 'uid');
         $this->createIndex('blog_posts_title_key', '{{%blog_posts}}', 'title', true);

tests/specs/blog/migrations/m200000_000004_create_table_post_comments.php

@@ -9,8 +9,8 @@ public function up()
     {
         $this->createTable('{{%post_comments}}', [
             'id' => $this->bigPrimaryKey(),
-            'post_id' => $this->string(128)->notNull(),
-            'author_id' => $this->integer()->notNull(),
+            'post_id' => $this->string(128)->notNull()->comment('A blog post (uid used as pk for test purposes)'),
+            'author_id' => $this->integer()->notNull()->comment('The User'),
             0 => 'message json NOT NULL',
             1 => 'meta_data json NOT NULL',
             'created_at' => $this->integer()->notNull(),

tests/specs/blog/migrations_maria_db/m200000_000002_create_table_blog_posts.php

@@ -11,10 +11,10 @@ public function up()
             0 => 'uid varchar(128) NOT NULL',
             'title' => $this->string(255)->notNull(),
             'slug' => $this->string(200)->null()->defaultValue(null),
-            'category_id' => $this->integer()->notNull(),
+            'category_id' => $this->integer()->notNull()->comment('Category of posts'),
             'active' => $this->boolean()->notNull()->defaultValue(false),
             'created_at' => $this->date()->null()->defaultValue(null),
-            'created_by_id' => $this->integer()->null()->defaultValue(null),
+            'created_by_id' => $this->integer()->null()->defaultValue(null)->comment('The User'),
         ]);
         $this->addPrimaryKey('pk_blog_posts_uid', '{{%blog_posts}}', 'uid');
         $this->createIndex('blog_posts_title_key', '{{%blog_posts}}', 'title', true);

tests/specs/blog/migrations_maria_db/m200000_000004_create_table_post_comments.php

@@ -9,8 +9,8 @@ public function up()
     {
         $this->createTable('{{%post_comments}}', [
             'id' => $this->bigPrimaryKey(),
-            'post_id' => $this->string(128)->notNull(),
-            'author_id' => $this->integer()->notNull(),
+            'post_id' => $this->string(128)->notNull()->comment('A blog post (uid used as pk for test purposes)'),
+            'author_id' => $this->integer()->notNull()->comment('The User'),
             0 => 'message json NOT NULL DEFAULT \'[]\'',
             1 => 'meta_data json NOT NULL DEFAULT \'[]\'',
             'created_at' => $this->integer()->notNull(),