Fix #21042: Separate the @property annotations in case of different types in getters and setters

Author: mspirkov

build/controllers/PhpDocController.php

@@ -411,7 +411,7 @@ protected function fixDocBlockIndentation(&$lines)
                     }
                     $docLine = preg_replace('/\s+/', ' ', $docLine);
                     $docLine = $this->fixParamTypes($docLine);
-                } elseif (preg_match('/^(~~~|```)/', $docLine)) {
+                } elseif (strpos($docLine, '```') !== false) {
                     $codeBlock = !$codeBlock;
                     $listIndent = '';
                 } elseif (preg_match('/^(\s*)([0-9]+\.|-|\*|\+) /', $docLine, $matches)) {
@@ -676,7 +676,7 @@ protected function cleanDocComment($doc)
         $n = \count($lines);
         for ($i = 0; $i < $n; $i++) {
             $lines[$i] = rtrim($lines[$i]);
-            if (trim($lines[$i]) == '*' && trim($lines[$i + 1]) == '*') {
+            if (trim($lines[$i]) == '*' && isset($lines[$i + 1]) && trim($lines[$i + 1]) == '*') {
                 unset($lines[$i]);
             }
         }
@@ -702,10 +702,15 @@ protected function updateDocComment($doc, $properties, $className)
         foreach ($lines as $i => $line) {
             $line = trim($line);
             if (strncmp($line, '* @property', 11) === 0) {
+                if ($propertyPosition === false) {
+                    $propertyPosition = $i - 1;
+                }
                 $propertyPart = true;
             } elseif ($propertyPart && $line === '*') {
                 $propertyPosition = $i;
                 $propertyPart = false;
+            } elseif ($propertyPart && $line === '*/') {
+                $propertyPart = false;
             }
             if (strncmp($line, '* @author ', 10) === 0 && $propertyPosition === false) {
                 $propertyPosition = $i - 1;
@@ -833,7 +838,7 @@ protected function generateClassPropertyDocs($fileName)
                     continue;
                 }
 
-                $acr['comment'] = trim(preg_replace('#(^|\n)\s+\*\s?#', '$1 * ', $acr['comment']));
+                $acr['comment'] = trim(preg_replace('#(^|\n)\h+\*\h?#', '$1 * ', $acr['comment']));
                 $props[$acr['name']][$acr['kind']] = [
                     'type' => $acr['type'],
                     'comment' => $this->fixSentence($acr['comment']),
@@ -847,33 +852,41 @@ protected function generateClassPropertyDocs($fileName)
             ksort($props);
 
             foreach ($props as $propName => &$prop) {
-                $docLine = ' * @property';
-                $note = '';
+                $annotationSuffix = '';
                 if (isset($prop['get'], $prop['set'])) {
                     if ($prop['get']['type'] !== $prop['set']['type']) {
-                        $note = ' Note that the type of this property differs in getter and setter.'
-                            . ' See [[get' . ucfirst($propName) . '()]]'
-                            . ' and [[set' . ucfirst($propName) . '()]] for details.';
+                        $phpdoc .= $this->generatePropertyDocLine(
+                            '-read',
+                            $propName,
+                            $prop['get']['type'],
+                            $prop['get']['comment']
+                        );
+                        $phpdoc .= $this->generatePropertyDocLine(
+                            '-write',
+                            $propName,
+                            $prop['set']['type'],
+                            $prop['set']['comment']
+                        );
+                        continue;
                     }
                 } elseif (isset($prop['get'])) {
                     if (!$this->hasSetterInParents($className, $propName)) {
-                        $docLine .= '-read';
+                        $annotationSuffix = '-read';
                     }
                 } elseif (isset($prop['set'])) {
                     if (!$this->hasGetterInParents($className, $propName)) {
-                        $docLine .= '-write';
+                        $annotationSuffix = '-write';
                     }
                 } else {
                     continue;
                 }
-                $docLine .= ' ' . $this->getPropParam($prop, 'type') . " $$propName ";
-                $comment = explode("\n", $this->getPropParam($prop, 'comment') . $note);
-                foreach ($comment as &$cline) {
-                    $cline = ltrim(rtrim($cline), '* ');
-                }
-                $docLine = wordwrap($docLine . implode(' ', $comment), 110, "\n * ") . "\n";
 
-                $phpdoc .= $docLine;
+                $phpdoc .= $this->generatePropertyDocLine(
+                    $annotationSuffix,
+                    $propName,
+                    $this->getPropParam($prop, 'type'),
+                    $this->getPropParam($prop, 'comment')
+                );
             }
         }
 
@@ -918,14 +931,70 @@ protected function fixSentence($str)
             return '';
         }
 
-        return strtoupper(substr($str, 0, 1)) . substr($str, 1) . ($str[\strlen($str) - 1] !== '.' ? '.' : '');
+        $endsWithCodeFence = substr($str, -3) === '```';
+        $suffix = !$endsWithCodeFence && $str[\strlen($str) - 1] !== '.' ? '.' : '';
+
+        return strtoupper(substr($str, 0, 1)) . substr($str, 1) . $suffix;
     }
 
     protected function getPropParam($prop, $param)
     {
         return isset($prop['property']) ? $prop['property'][$param] : (isset($prop['get']) ? $prop['get'][$param] : $prop['set'][$param]);
     }
 
+    private function generatePropertyDocLine(
+        string $annotationSuffix,
+        string $propName,
+        string $type,
+        string $comment
+    ): string {
+        $docLine = " * @property{$annotationSuffix} {$type} \${$propName} ";
+
+        $isExample = false;
+        $commentLines = [];
+        $exampleLines = [];
+        $rawCommentLines = explode("\n", $comment);
+
+        foreach ($rawCommentLines as $lineIndex => $line) {
+            $isCodeFence = strpos($line, '* ```') !== false;
+            $formattedLine = ltrim(rtrim($line), '* ');
+
+            if ($isCodeFence) {
+                if (!$isExample) {
+                    $isExample = true;
+                    $exampleLines[] = "\n * {$formattedLine}";
+                    continue;
+                }
+
+                $exampleLines[] = " * {$formattedLine}";
+                $example = implode("\n", $exampleLines);
+
+                foreach (array_slice($rawCommentLines, $lineIndex + 1) as $remainingLine) {
+                    if (ltrim(rtrim($remainingLine), '* ') !== '') {
+                        $example .= "\n *";
+                        break;
+                    }
+                }
+
+                $commentLines[] = $example;
+                $exampleLines = [];
+                $isExample = false;
+                continue;
+            }
+
+            if ($isExample) {
+                $exampleLines[] = rtrim($line);
+            } elseif ($formattedLine !== '') {
+                $commentLines[] = $formattedLine;
+            }
+        }
+
+        $propertyDoc = wordwrap($docLine . implode(' ', $commentLines), 110, "\n * ");
+        $propertyDoc = preg_replace('/\h+\n/', "\n", $propertyDoc) ?? $propertyDoc;
+
+        return $propertyDoc . "\n";
+    }
+
     /**
      * Generate a hash value (message digest)
      * @param string $string message to be hashed.

framework/CHANGELOG.md

@@ -28,6 +28,7 @@ Yii Framework 2 Change Log
 - Enh #20988, #21040: Add generics to `yii\db\Connection` and `yii\db\Schema` so `getSchema()` and `getQueryBuilder()` infer driver-specific types (terabytesoftw, mspirkov)
 - Bug #20994: Fix `@var` annotations for `BlameableBehavior` properties (mspirkov)
 - Enh #20990: Show created migration file path on migrate create CLI command (flaviovs)
+- Bug #21042: Separate the `@property` annotations in case of different types in getters and setters (mspirkov)
 
 
 2.0.55 May 09, 2026

framework/base/Model.php

@@ -55,8 +55,7 @@
  *
  * Empty array if no errors.
  * @property-read Validator[] $activeValidators The validators applicable to the current [[scenario]].
- * @property array<string, mixed> $attributes Attribute values (name => value). Note that the type of this
- * property differs in getter and setter. See [[getAttributes()]] and [[setAttributes()]] for details.
+ * @property array<string, mixed> $attributes Attribute values (name => value).
  * @property-read array<string, string> $firstErrors The first errors. The array keys are the attribute names,
  * and the array values are the corresponding error messages. An empty array will be returned if there is no
  * error.
@@ -744,7 +743,7 @@ public function getAttributes($names = null, $except = [])
 
     /**
      * Sets the attribute values in a massive way.
-     * @param array $values attribute values (name => value) to be assigned to the model.
+     * @param array<string, mixed> $values attribute values (name => value) to be assigned to the model.
      * @param bool $safeOnly whether the assignments should only be done to the safe attributes.
      * A safe attribute is one that is associated with a validation rule in the current [[scenario]].
      * @see safeAttributes()

framework/base/Module.php

@@ -32,8 +32,14 @@
  * @property string $layoutPath The root directory of layout files. Defaults to "[[viewPath]]/layouts".
  * @property array $modules The modules (indexed by their IDs).
  * @property-read string $uniqueId The unique ID of the module.
- * @property string $version The version of this module. Note that the type of this property differs in getter
- * and setter. See [[getVersion()]] and [[setVersion()]] for details.
+ * @property-read string $version The version of this module.
+ * @property-write string|callable|null $version The version of this module. Version can be specified as a PHP
+ * callback, which can accept module instance as an argument and should return the actual version. For example:
+ * ```
+ * function (Module $module) {
+ *     //return string
+ * }
+ * ```
  * @property string $viewPath The root directory of view files. Defaults to "[[basePath]]/views".
  *
  * @author Qiang Xue <qiang.xue@gmail.com>

framework/base/Widget.php

@@ -16,10 +16,9 @@
  *
  * For more details and usage information on Widget, see the [guide article on widgets](guide:structure-widgets).
  *
- * @property string|null $id ID of the widget. Note that the type of this property differs in getter and
- * setter. See [[getId()]] and [[setId()]] for details.
- * @property \yii\web\View $view The view object that can be used to render views or view files. Note that the
- * type of this property differs in getter and setter. See [[getView()]] and [[setView()]] for details.
+ * @property-read string|null $id ID of the widget.
+ * @property-write string $id Id of the widget.
+ * @property \yii\web\View $view The view object that can be used to render views or view files.
  * @property-read string $viewPath The directory containing the view files for this widget.
  *
  * @author Qiang Xue <qiang.xue@gmail.com>
@@ -191,6 +190,7 @@ public function setId($value)
         $this->_id = $value;
     }
 
+    /** @var \yii\web\View|null */
     private $_view;
 
     /**
@@ -203,15 +203,17 @@ public function setId($value)
     public function getView()
     {
         if ($this->_view === null) {
-            $this->_view = Yii::$app->getView();
+            /** @var \yii\web\View $view */
+            $view = Yii::$app->getView();
+            $this->_view = $view;
         }
 
         return $this->_view;
     }
 
     /**
      * Sets the view object to be used by this widget.
-     * @param View $view the view object that can be used to render views or view files.
+     * @param \yii\web\View $view the view object that can be used to render views or view files.
      */
     public function setView($view)
     {

framework/caching/MemCache.php

@@ -58,8 +58,9 @@
  *
  * @property-read \Memcache|\Memcached $memcache The memcache (or memcached) object used by this cache
  * component.
- * @property MemCacheServer[] $servers List of memcache server configurations. Note that the type of this
- * property differs in getter and setter. See [[getServers()]] and [[setServers()]] for details.
+ * @property-read MemCacheServer[] $servers List of memcache server configurations.
+ * @property-write array $servers List of memcache or memcached server configurations. Each element must be an
+ * array with the following keys: host, port, persistent, weight, timeout, retryInterval, status.
  *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0

framework/console/controllers/AssetController.php

@@ -40,8 +40,9 @@
  * Note: by default this command relies on an external tools to perform actual files compression,
  * check [[jsCompressor]] and [[cssCompressor]] for more details.
  *
- * @property \yii\web\AssetManager $assetManager Asset manager instance. Note that the type of this property
- * differs in getter and setter. See [[getAssetManager()]] and [[setAssetManager()]] for details.
+ * @property-read \yii\web\AssetManager $assetManager Asset manager instance.
+ * @property-write \yii\web\AssetManager|array $assetManager Asset manager instance or its array
+ * configuration.
  *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @author Paul Klimov <klimov.paul@gmail.com>

framework/data/BaseDataProvider.php

@@ -21,11 +21,17 @@
  * @property array $keys The list of key values corresponding to [[models]]. Each data model in [[models]] is
  * uniquely identified by the corresponding key value in this array.
  * @property array $models The list of data models in the current page.
- * @property Pagination|false $pagination The pagination object. If this is false, it means the pagination is
- * disabled. Note that the type of this property differs in getter and setter. See [[getPagination()]] and
- * [[setPagination()]] for details.
- * @property Sort|bool $sort The sorting object. If this is false, it means the sorting is disabled. Note that
- * the type of this property differs in getter and setter. See [[getSort()]] and [[setSort()]] for details.
+ * @property-read Pagination|false $pagination The pagination object. If this is false, it means the
+ * pagination is disabled.
+ * @property-write array|Pagination|false $pagination The pagination to be used by this data provider. This
+ * can be one of the following: - a configuration array for creating the pagination object. The "class" element
+ * defaults to 'yii\data\Pagination' - an instance of [[Pagination]] or its subclass - false, if pagination needs
+ * to be disabled.
+ * @property-read Sort|bool $sort The sorting object. If this is false, it means the sorting is disabled.
+ * @property-write array|Sort|bool $sort The sort definition to be used by this data provider. This can be one
+ * of the following: - a configuration array for creating the sort definition object. The "class" element
+ * defaults to 'yii\data\Sort' - an instance of [[Sort]] or its subclass - false, if sorting needs to be
+ * disabled.
  * @property int $totalCount Total number of possible data models.
  *
  * @author Qiang Xue <qiang.xue@gmail.com>
@@ -199,7 +205,7 @@ public function getPagination()
 
     /**
      * Sets the pagination for this data provider.
-     * @param array|Pagination|bool $value the pagination to be used by this data provider.
+     * @param array|Pagination|false $value the pagination to be used by this data provider.
      * This can be one of the following:
      *
      * - a configuration array for creating the pagination object. The "class" element defaults

framework/data/DataFilter.php

@@ -113,13 +113,14 @@
  *
  * @see ActiveDataFilter
  *
- * @property array $errorMessages Error messages in format `[errorKey => message]`. Note that the type of this
- * property differs in getter and setter. See [[getErrorMessages()]] and [[setErrorMessages()]] for details.
+ * @property-read array $errorMessages Error messages in format `[errorKey => message]`.
+ * @property-write array|\Closure $errorMessages Error messages in `[errorKey => message]` format, or a PHP
+ * callback returning them.
  * @property mixed $filter Raw filter value.
- * @property array $searchAttributeTypes Search attribute type map. Note that the type of this property
- * differs in getter and setter. See [[getSearchAttributeTypes()]] and [[setSearchAttributeTypes()]] for details.
- * @property Model $searchModel Model instance. Note that the type of this property differs in getter and
- * setter. See [[getSearchModel()]] and [[setSearchModel()]] for details.
+ * @property-read array $searchAttributeTypes Search attribute type map.
+ * @property-write array|null $searchAttributeTypes Search attribute type map.
+ * @property-read Model $searchModel Model instance.
+ * @property-write Model|array|string|callable $searchModel Model instance or its DI compatible configuration.
  *
  * @author Paul Klimov <klimov.paul@gmail.com>
  * @since 2.0.13

framework/data/Sort.php

@@ -69,9 +69,10 @@
  *
  * For more details and usage information on Sort, see the [guide article on sorting](guide:output-sorting).
  *
- * @property array $attributeOrders Sort directions indexed by attribute names. Sort direction can be either
- * `SORT_ASC` for ascending order or `SORT_DESC` for descending order. Note that the type of this property
- * differs in getter and setter. See [[getAttributeOrders()]] and [[setAttributeOrders()]] for details.
+ * @property-read array $attributeOrders Sort directions indexed by attribute names. Sort direction can be
+ * either `SORT_ASC` for ascending order or `SORT_DESC` for descending order.
+ * @property-write array|null $attributeOrders Sort directions indexed by attribute names. Sort direction can
+ * be either `SORT_ASC` for ascending order or `SORT_DESC` for descending order.
  * @property-read array $orders The columns (keys) and their corresponding sort directions (values). This can
  * be passed to [[\yii\db\Query::orderBy()]] to construct a DB query.
  *