Support PHPStan/Psalm syntax and intersection types

CHANGELOG.md

@@ -1,11 +1,15 @@
 Yii Framework 2 apidoc extension Change Log
 ===========================================
 
-3.0.9 under development
+4.0.0 under development
 -----------------------
 
 - Bug #338: Fix deprecation error `Using null as an array offset is deprecated, use an empty string instead` (mspirkov)
 - Enh #337: Log invalid tags (mspirkov)
+- Enh #339: Add support for PHPStan/Psalm syntax (mspirkov)
+- Enh #339: Add support for intersection types (mspirkov)
+- Bug #339: Fix the mechanism for replacing `static` with FQCN (mspirkov)
+- Bug #339: Fix processing of multidimensional arrays (mspirkov)
 
 
 3.0.8 November 24, 2025

commands/GuideController.php

@@ -13,7 +13,6 @@
 use yii\apidoc\renderers\GuideRenderer;
 use yii\helpers\Console;
 use yii\helpers\FileHelper;
-use Yii;
 use yii\helpers\Json;
 
 /**

composer.json

@@ -24,7 +24,8 @@
         "php": "^7.4 || ^8.0",
         "yiisoft/yii2": "~2.0.16",
         "yiisoft/yii2-bootstrap": "~2.0.0",
-        "phpdocumentor/reflection": "^5.1.0 || ^6.0.0",
+        "phpdocumentor/reflection": "^5.3.0 || ^6.0.0",
+        "phpdocumentor/type-resolver": "^1.11",
         "nikic/php-parser": "^4.0 || ^5.0",
         "cebe/js-search": "~0.9.0",
         "cebe/markdown": "^1.0",

helpers/TypeHelper.php

@@ -7,6 +7,8 @@
 
 namespace yii\apidoc\helpers;
 
+use phpDocumentor\Reflection\PseudoTypes\Conditional;
+use phpDocumentor\Reflection\PseudoTypes\ConditionalForParameter;
 use phpDocumentor\Reflection\Type;
 use phpDocumentor\Reflection\Types\AggregatedType;
 
@@ -18,24 +20,41 @@
 final class TypeHelper
 {
     /**
-     * @return string[]
+     * @return Type[]
      */
-    public static function splitType(?Type $type): array
+    public static function getTypesByAggregatedType(AggregatedType $compound): array
     {
-        if ($type === null) {
-            return [];
+        $types = [];
+        foreach ($compound as $type) {
+            $types[] = $type;
         }
 
-        // TODO: Don't split the Intersection
-        if (!$type instanceof AggregatedType) {
-            return [(string) $type];
-        }
+        return $types;
+    }
 
+    /**
+     * @param Conditional|ConditionalForParameter $type
+     * @return Type[] Possible unique types.
+     */
+    public static function getPossibleTypesByConditionalType(Type $type): array
+    {
         $types = [];
-        foreach ($type as $childType) {
-            $types[] = (string) $childType;
+
+        foreach ([$type->getIf(), $type->getElse()] as $innerType) {
+            if ($innerType instanceof Conditional || $innerType instanceof ConditionalForParameter) {
+                $types = array_merge($types, self::getPossibleTypesByConditionalType($innerType));
+            } elseif ($innerType instanceof AggregatedType) {
+                $types = array_merge($types, self::getTypesByAggregatedType($innerType));
+            } else {
+                $types[] = $innerType;
+            }
         }
 
-        return $types;
+        $uniqueTypes = [];
+        foreach ($types as $innerType) {
+            $uniqueTypes[(string) $innerType] = $innerType;
+        }
+
+        return array_values($uniqueTypes);
     }
 }

models/BaseDoc.php

@@ -13,12 +13,15 @@
 use phpDocumentor\Reflection\DocBlock\Tags\Generic;
 use phpDocumentor\Reflection\DocBlock\Tags\InvalidTag;
 use phpDocumentor\Reflection\DocBlock\Tags\Since;
+use phpDocumentor\Reflection\DocBlock\Tags\Template;
+use phpDocumentor\Reflection\FqsenResolver;
 use phpDocumentor\Reflection\Php\Class_;
 use phpDocumentor\Reflection\Php\Constant;
 use phpDocumentor\Reflection\Php\Interface_;
 use phpDocumentor\Reflection\Php\Method;
 use phpDocumentor\Reflection\Php\Property;
 use phpDocumentor\Reflection\Php\Trait_;
+use phpDocumentor\Reflection\TypeResolver;
 use yii\base\BaseObject;
 use yii\helpers\StringHelper;
 
@@ -32,14 +35,26 @@
  */
 class BaseDoc extends BaseObject
 {
+    private const PHPSTAN_TYPE_ANNOTATION_NAME = 'phpstan-type';
+    private const PSALM_TYPE_ANNOTATION_NAME = 'psalm-type';
+
+    private const PHPSTAN_IMPORT_TYPE_ANNOTATION_NAME = 'phpstan-import-type';
+    private const PSALM_IMPORT_TYPE_ANNOTATION_NAME = 'psalm-import-type';
+
     private const INHERITDOC_TAG_NAME = 'inheritdoc';
     private const TODO_TAG_NAME = 'todo';
 
     /**
      * @var \phpDocumentor\Reflection\Types\Context|null
      */
     public $phpDocContext;
+    /**
+     * @var string|null
+     */
     public $name;
+    /**
+     * @var string|null
+     */
     public $fullName;
     public $sourceFile;
     public $startLine;
@@ -64,6 +79,30 @@ class BaseDoc extends BaseObject
      * @var Generic[]
      */
     public $todos = [];
+    /**
+     * @var array<string, Template>
+     */
+    public $templates = [];
+    /**
+     * @var self|null
+     */
+    public $parent = null;
+    /**
+     * @var array<string, PseudoTypeDoc>
+     */
+    public array $phpStanTypes = [];
+    /**
+     * @var array<string, PseudoTypeDoc>
+     */
+    public array $psalmTypes = [];
+    /**
+     * @var array<string, PseudoTypeImportDoc>
+     */
+    public array $phpStanTypeImports = [];
+    /**
+     * @var array<string, PseudoTypeImportDoc>
+     */
+    public array $psalmTypeImports = [];
 
     /**
      * Checks if doc has tag of a given name
@@ -126,18 +165,24 @@ public function getPackageName()
     }
 
     /**
+     * @param self|null $parent
      * @param Class_|Method|Trait_|Interface_|Property|Constant|null $reflector
      * @param Context|null $context
      * @param array $config
      */
-    public function __construct($reflector = null, $context = null, $config = [])
+    public function __construct($parent = null, $reflector = null, $context = null, $config = [])
     {
         parent::__construct($config);
 
+        $this->parent = $parent;
+
         if ($reflector === null) {
             return;
         }
 
+        $fqsenResolver = new FqsenResolver();
+        $typeResolver = new TypeResolver($fqsenResolver);
+
         // base properties
         $this->fullName = trim((string) $reflector->getFqsen(), '\\()');
 
@@ -160,7 +205,7 @@ public function __construct($reflector = null, $context = null, $config = [])
             return;
         }
 
-        $this->shortDescription = StringHelper::mb_ucfirst($docBlock->getSummary());;
+        $this->shortDescription = StringHelper::mb_ucfirst($docBlock->getSummary());
         if (empty($this->shortDescription) && !($this instanceof PropertyDoc) && $context !== null && !$docBlock->getTagsByName(self::INHERITDOC_TAG_NAME)) {
             $context->warnings[] = [
                 'line' => $this->startLine,
@@ -192,9 +237,57 @@ public function __construct($reflector = null, $context = null, $config = [])
                 $this->deprecatedSince = $tag->getVersion();
                 $this->deprecatedReason = (string) $tag->getDescription();
                 unset($this->tags[$i]);
-            } elseif ($tag instanceof Generic && $tag->getName() === self::TODO_TAG_NAME) {
-                $this->todos[] = $tag;
+            } elseif ($tag instanceof Template) {
+                $fqsen = $fqsenResolver->resolve($tag->getTemplateName(), $this->phpDocContext);
+                $this->templates[(string) $fqsen] = $tag;
                 unset($this->tags[$i]);
+            } elseif ($tag instanceof Generic) {
+                if ($tag->getName() === self::TODO_TAG_NAME) {
+                    $this->todos[] = $tag;
+                    unset($this->tags[$i]);
+                } elseif ($tag->getName() === self::PHPSTAN_TYPE_ANNOTATION_NAME) {
+                    $tagData = explode(' ', trim($tag->getDescription()), 2);
+                    $phpStanType = new PseudoTypeDoc(
+                        PseudoTypeDoc::TYPE_PHPSTAN,
+                        $this,
+                        trim($tagData[0]),
+                        $typeResolver->resolve(trim($tagData[1]), $this->phpDocContext)
+                    );
+                    $fqsen = $fqsenResolver->resolve($phpStanType->name, $this->phpDocContext);
+                    $this->phpStanTypes[(string) $fqsen] = $phpStanType;
+                    unset($this->tags[$i]);
+                } elseif ($tag->getName() === self::PSALM_TYPE_ANNOTATION_NAME) {
+                    $tagData = explode('=', trim($tag->getDescription()), 2);
+                    $psalmType = new PseudoTypeDoc(
+                        PseudoTypeDoc::TYPE_PSALM,
+                        $this,
+                        trim($tagData[0]),
+                        $typeResolver->resolve(trim($tagData[1]), $this->phpDocContext)
+                    );
+                    $fqsen = $fqsenResolver->resolve($psalmType->name, $this->phpDocContext);
+                    $this->psalmTypes[(string) $fqsen] = $psalmType;
+                    unset($this->tags[$i]);
+                } elseif ($tag->getName() === self::PHPSTAN_IMPORT_TYPE_ANNOTATION_NAME) {
+                    $tagData = explode(' from ', trim($tag->getDescription()), 2);
+                    $phpStanTypeImport = new PseudoTypeImportDoc(
+                        PseudoTypeImportDoc::TYPE_PHPSTAN,
+                        trim($tagData[0]),
+                        $fqsenResolver->resolve(trim($tagData[1]), $this->phpDocContext)
+                    );
+                    $fqsen = $fqsenResolver->resolve($phpStanTypeImport->typeName, $this->phpDocContext);
+                    $this->phpStanTypeImports[(string) $fqsen] = $phpStanTypeImport;
+                    unset($this->tags[$i]);
+                } elseif ($tag->getName() === self::PSALM_IMPORT_TYPE_ANNOTATION_NAME) {
+                    $tagData = explode(' from ', trim($tag->getDescription()), 2);
+                    $psalmTypeImport = new PseudoTypeImportDoc(
+                        PseudoTypeImportDoc::TYPE_PSALM,
+                        trim($tagData[0]),
+                        $fqsenResolver->resolve(trim($tagData[1]), $this->phpDocContext)
+                    );
+                    $fqsen = $fqsenResolver->resolve($psalmTypeImport->typeName, $this->phpDocContext);
+                    $this->psalmTypeImports[(string) $fqsen] = $psalmTypeImport;
+                    unset($this->tags[$i]);
+                }
             } elseif ($tag instanceof InvalidTag && $context !== null) {
                 $exception = $tag->getException();
                 $message = 'Invalid tag: ' . $tag->render() . '.';

models/ClassDoc.php

@@ -7,6 +7,8 @@
 
 namespace yii\apidoc\models;
 
+use phpDocumentor\Reflection\Php\Class_;
+
 /**
  * Represents API documentation information for a `class`.
  *
@@ -91,7 +93,9 @@ public function getNativeEvents()
     }
 
     /**
-     * @inheritdoc
+     * @param Class_|null $reflector
+     * @param Context|null $context
+     * @param array $config
      */
     public function __construct($reflector = null, $context = null, $config = [])
     {
@@ -118,11 +122,11 @@ public function __construct($reflector = null, $context = null, $config = [])
         foreach ($reflector->getConstants() as $constantReflector) {
             $docBlock = $constantReflector->getDocBlock();
             if ($docBlock !== null && count($docBlock->getTagsByName('event')) > 0) {
-                $event = new EventDoc($constantReflector, null, [], $docBlock);
+                $event = new EventDoc($this, $constantReflector, null, [], $docBlock);
                 $event->definedBy = $this->name;
                 $this->events[$event->name] = $event;
             } else {
-                $constant = new ConstDoc($constantReflector);
+                $constant = new ConstDoc($this, $constantReflector);
                 $constant->definedBy = $this->name;
                 $this->constants[$constant->name] = $constant;
             }

models/ConstDoc.php

@@ -18,6 +18,9 @@
  */
 class ConstDoc extends BaseDoc
 {
+    /**
+     * @var string|null
+     */
     public $definedBy;
     /**
      * @var string|null
@@ -26,14 +29,15 @@ class ConstDoc extends BaseDoc
 
 
     /**
+     * @param ClassDoc|TraitDoc $parent
      * @param Constant|null $reflector
      * @param Context|null $context
      * @param array $config
      * @param DocBlock|null $docBlock
      */
-    public function __construct($reflector = null, $context = null, $config = [], $docBlock = null)
+    public function __construct($parent, $reflector = null, $context = null, $config = [], $docBlock = null)
     {
-        parent::__construct($reflector, $context, $config);
+        parent::__construct($parent, $reflector, $context, $config);
 
         if ($reflector === null) {
             return;