Draft for 3.0

yiisoft · Aug 30, 2021 · 7aa586d · 7aa586d
1 parent 8f75edd
commit 7aa586d
Show file tree

Hide file tree

Showing 16 changed files with 155 additions and 104 deletions.
diff --git a/.gitignore b/.gitignore
@@ -32,4 +32,6 @@ phpunit.phar
 /tests/runtime
 
 # local tests configuration
-/tests/data/config.local.php
+/tests/data/config.local.php
+
+.phpunit.result.cache
diff --git a/commands/ApiController.php b/commands/ApiController.php
@@ -97,14 +97,15 @@ public function actionIndex(array $sourceDirs, $targetDir)
         $done = 0;
         foreach ($files as $file) {
             try {
-                $context->addFile($file);
+                $context->addProjectFile($file);
             } catch (\Exception $e) {
                 $context->errors[] = "Unable to process \"$file\": " . $e->getMessage();
             }
             Console::updateProgress(++$done, $fileCount);
         }
         Console::endProgress(true);
         $this->stdout('done.' . PHP_EOL, Console::FG_GREEN);
+        $context->processFiles();
 
         // save processed data to cache
         $this->storeContext($context, $targetDir);

diff --git a/composer.json b/composer.json
@@ -19,20 +19,19 @@
     ],
     "minimum-stability": "dev",
     "require": {
-        "php": ">=5.4",
-        "yiisoft/yii2": "~2.0.13",
+        "php": "^7.2",
+        "yiisoft/yii2": "~2.0.16",
         "yiisoft/yii2-bootstrap": "~2.0.0",
-        "phpdocumentor/reflection": "^3.0.1",
-        "phpdocumentor/reflection-docblock": "^2.0.4",
-        "nikic/php-parser": "^1.0",
-        "cebe/js-search": "~0.9.3",
-        "cebe/markdown": "~1.0.0 | ~1.1.0 | ~1.2.0",
-        "cebe/markdown-latex": "~1.0",
-        "scrivo/highlight.php": "~9.13"
+        "phpdocumentor/reflection": "^4.0 | ^5.0",
+        "phpdocumentor/reflection-docblock": "^4.0 | ^5.0",
+        "nikic/php-parser": "^4.0",
+        "cebe/js-search": "~0.9.0",
+        "cebe/markdown": "^1.0",
+        "cebe/markdown-latex": "^1.0",
+        "scrivo/highlight.php": "^9.0"
     },
     "require-dev": {
-        "cweagans/composer-patches": "^1.7",
-        "phpunit/phpunit": "4.8.34"
+        "phpunit/phpunit": "*"
     },
     "repositories": [
         {
@@ -47,16 +46,6 @@
     "extra": {
         "branch-alias": {
             "dev-master": "2.1.x-dev"
-        },
-        "composer-exit-on-patch-failure": true,
-        "patches": {
-            "phpunit/phpunit-mock-objects": {
-                "Fix PHP 7 and 8 compatibility": "https://yiisoft.github.io/phpunit-patches/phpunit_mock_objects.patch"
-            },
-            "phpunit/phpunit": {
-                "Fix PHP 7 compatibility": "https://yiisoft.github.io/phpunit-patches/phpunit_php7.patch",
-                "Fix PHP 8 compatibility": "https://yiisoft.github.io/phpunit-patches/phpunit_php8.patch"
-            }
         }
     }
 }
diff --git a/models/BaseDoc.php b/models/BaseDoc.php
@@ -10,6 +10,10 @@
 use phpDocumentor\Reflection\DocBlock\Tag;
 use phpDocumentor\Reflection\DocBlock\Tag\DeprecatedTag;
 use phpDocumentor\Reflection\DocBlock\Tag\SinceTag;
+use phpDocumentor\Reflection\DocBlock\Tags\Deprecated;
+use phpDocumentor\Reflection\DocBlock\Tags\Generic;
+use phpDocumentor\Reflection\DocBlock\Tags\Since;
+use phpDocumentor\Reflection\Php\Class_;
 use yii\base\BaseObject;
 use yii\helpers\StringHelper;
 
@@ -26,6 +30,7 @@ class BaseDoc extends BaseObject
      */
     public $phpDocContext;
     public $name;
+    public $shortName;
     public $sourceFile;
     public $startLine;
     public $endLine;
@@ -101,7 +106,7 @@ public function getPackageName()
     }
 
     /**
-     * @param \phpDocumentor\Reflection\BaseReflector $reflector
+     * @param Class_ $reflector
      * @param Context $context
      * @param array $config
      */
@@ -114,30 +119,34 @@ public function __construct($reflector = null, $context = null, $config = [])
         }
 
         // base properties
-        $this->name = ltrim($reflector->getName(), '\\');
-        $this->startLine = $reflector->getNode()->getAttribute('startLine');
-        $this->endLine = $reflector->getNode()->getAttribute('endLine');
+        $this->name = ltrim((string) $reflector->getFqsen(), '\\');
+        $separator = strrpos($this->name, '::');
+        if ($separator !== false) {
+            $this->shortName = substr($this->name, $separator + 2);
+        }
+        $this->startLine = $reflector->getLocation()->getLineNumber();
+        //$this->endLine = $reflector->getNode()->getAttribute('endLine');
 
         $docblock = $reflector->getDocBlock();
         if ($docblock !== null) {
-            $this->shortDescription = static::mbUcFirst($docblock->getShortDescription());
+            $this->shortDescription = StringHelper::mb_ucfirst($docblock->getSummary());
             if (empty($this->shortDescription) && !($this instanceof PropertyDoc) && $context !== null && $docblock->getTagsByName('inheritdoc') === null) {
                 $context->warnings[] = [
                     'line' => $this->startLine,
                     'file' => $this->sourceFile,
                     'message' => "No short description for " . substr(StringHelper::basename(get_class($this)), 0, -3) . " '{$this->name}'",
                 ];
             }
-            $this->description = $docblock->getLongDescription()->getContents();
+            $this->description = $docblock->getDescription()->render();
 
             $this->phpDocContext = $docblock->getContext();
 
             $this->tags = $docblock->getTags();
             foreach ($this->tags as $i => $tag) {
-                if ($tag instanceof SinceTag) {
+                if ($tag instanceof Since) {
                     $this->since = $tag->getVersion();
                     unset($this->tags[$i]);
-                } elseif ($tag instanceof DeprecatedTag) {
+                } elseif ($tag instanceof Deprecated) {
                     $this->deprecatedSince = $tag->getVersion();
                     $this->deprecatedReason = $tag->getDescription();
                     unset($this->tags[$i]);
@@ -147,7 +156,7 @@ public function __construct($reflector = null, $context = null, $config = [])
             if ($this->shortDescription === '{@inheritdoc}') {
                 // Mock up parsing of '{@inheritdoc}' (in brackets) tag, which is not yet supported at "phpdocumentor/reflection-docblock" 2.x
                 // todo consider removal in case of "phpdocumentor/reflection-docblock" upgrade
-                $this->tags[] = new Tag('inheritdoc', '');
+                $this->tags[] = new Generic('inheritdoc');
                 $this->shortDescription = '';
             }
 

diff --git a/models/ClassDoc.php b/models/ClassDoc.php
@@ -101,7 +101,7 @@ public function __construct($reflector = null, $context = null, $config = [])
             return;
         }
 
-        $this->parentClass = ltrim($reflector->getParentClass(), '\\');
+        $this->parentClass = ltrim($reflector->getParent(), '\\');
         if (empty($this->parentClass)) {
             $this->parentClass = null;
         }
@@ -111,7 +111,7 @@ public function __construct($reflector = null, $context = null, $config = [])
         foreach ($reflector->getInterfaces() as $interface) {
             $this->interfaces[] = ltrim($interface, '\\');
         }
-        foreach ($reflector->getTraits() as $trait) {
+        foreach ($reflector->getUsedTraits() as $trait) {
             $this->traits[] = ltrim($trait, '\\');
         }
         foreach ($reflector->getConstants() as $constantReflector) {

diff --git a/models/Context.php b/models/Context.php
@@ -5,15 +5,18 @@
  * @license http://www.yiiframework.com/license/
  */
 
+declare(strict_types=1);
+
 namespace yii\apidoc\models;
 
-use phpDocumentor\Reflection\FileReflector;
+use phpDocumentor\Reflection\File\LocalFile;
+use phpDocumentor\Reflection\Php\Project;
+use phpDocumentor\Reflection\Php\ProjectFactory;
 use yii\base\Component;
 
 /**
- *
  * @author Carsten Brandt <mail@cebe.cc>
- * @since 2.0
+ * @author Paweł Brzozowski <pawel@positive.codes>
  */
 class Context extends Component
 {
@@ -39,7 +42,6 @@ class Context extends Component
     public $errors = [];
     /**
      * @var array
-     * @since 2.0.6
      */
     public $warnings = [];
 
@@ -49,29 +51,58 @@ class Context extends Component
      * @param string $type
      * @return null|ClassDoc|InterfaceDoc|TraitDoc
      */
-    public function getType($type)
+    public function getType(string $type)
     {
         $type = ltrim($type, '\\');
+
         if (isset($this->classes[$type])) {
             return $this->classes[$type];
-        } elseif (isset($this->interfaces[$type])) {
+        }
+        if (isset($this->interfaces[$type])) {
             return $this->interfaces[$type];
-        } elseif (isset($this->traits[$type])) {
+        }
+        if (isset($this->traits[$type])) {
             return $this->traits[$type];
         }
 
         return null;
     }
 
+    public function addProjectFile($fileName): void
+    {
+        $this->files[$fileName] = sha1_file($fileName);
+    }
+
+    public function processFiles(): void
+    {
+        $projectFiles = $this->getReflectionProject()->getFiles();
+        foreach ($this->files as $fileName => $hash) {
+            $reflection = $projectFiles[$fileName];
+
+            foreach ($reflection->getClasses() as $class) {
+                $class = new ClassDoc($class, $this, ['sourceFile' => $fileName]);
+                $this->classes[$class->name] = $class;
+            }
+            foreach ($reflection->getInterfaces() as $interface) {
+                $interface = new InterfaceDoc($interface, $this, ['sourceFile' => $fileName]);
+                $this->interfaces[$interface->name] = $interface;
+            }
+            foreach ($reflection->getTraits() as $trait) {
+                $trait = new TraitDoc($trait, $this, ['sourceFile' => $fileName]);
+                $this->traits[$trait->name] = $trait;
+            }
+        }
+    }
+
     /**
      * Adds file to context
      * @param string $fileName
      */
-    public function addFile($fileName)
+    public function addFile(string $fileName): void
     {
         $this->files[$fileName] = sha1_file($fileName);
 
-        $reflection = new FileReflector($fileName, true);
+        $reflection = new \phpDocumentor\Reflection\File\LocalFile($fileName, true);
         $reflection->process();
 
         foreach ($reflection->getClasses() as $class) {
@@ -91,7 +122,7 @@ public function addFile($fileName)
     /**
      * Updates references
      */
-    public function updateReferences()
+    public function updateReferences(): void
     {
         // update all subclass references
         foreach ($this->classes as $class) {
@@ -101,10 +132,12 @@ public function updateReferences()
                 $class->subclasses[] = $className;
             }
         }
+
         // update interfaces of subclasses
         foreach ($this->classes as $class) {
             $this->updateSubclassInterfacesTraits($class);
         }
+
         // update implementedBy and usedBy for interfaces and traits
         foreach ($this->classes as $class) {
             foreach ($class->traits as $trait) {
@@ -306,7 +339,7 @@ private function inheritMethodRecursive($method, $class)
         foreach($inheritanceCandidates as $candidate) {
             if (isset($candidate->methods[$method->name])) {
                 $cmethod = $candidate->methods[$method->name];
-                if ($cmethod->hasTag('inheritdoc')) {
+                if (!$candidate instanceof InterfaceDoc && $cmethod->hasTag('inheritdoc')) {
                     $this->inheritDocs($candidate);
                 }
                 $methods[] = $cmethod;
@@ -458,7 +491,7 @@ private function hasNonOptionalParams($method, $number = 0)
                 $count++;
             }
         }
-        return $count == $number;
+        return $count === $number;
     }
 
     /**
@@ -485,15 +518,31 @@ protected function isSubclassOf($classA, $classB)
         if (is_object($classB)) {
             $classB = $classB->name;
         }
-        if ($classA->name == $classB) {
+        if ($classA->name === $classB) {
             return true;
         }
         while ($classA->parentClass !== null && isset($this->classes[$classA->parentClass])) {
             $classA = $this->classes[$classA->parentClass];
-            if ($classA->name == $classB) {
+            if ($classA->name === $classB) {
                 return true;
             }
         }
         return false;
     }
+
+    private $reflectionProject;
+
+    public function getReflectionProject(): Project
+    {
+        if ($this->reflectionProject === null) {
+            $files = [];
+            foreach ($this->files as $fileName => $hash) {
+                $files[] = new LocalFile($fileName);
+            }
+
+            $this->reflectionProject = ProjectFactory::createInstance()->create('ApiDoc', $files);
+        }
+
+        return $this->reflectionProject;
+    }
 }
diff --git a/models/FunctionDoc.php b/models/FunctionDoc.php
@@ -11,6 +11,11 @@
 use phpDocumentor\Reflection\DocBlock\Tag\PropertyTag;
 use phpDocumentor\Reflection\DocBlock\Tag\ReturnTag;
 use phpDocumentor\Reflection\DocBlock\Tag\ThrowsTag;
+use phpDocumentor\Reflection\DocBlock\Tags\Param;
+use phpDocumentor\Reflection\DocBlock\Tags\Throws;
+use phpDocumentor\Reflection\Php\Function_;
+use phpDocumentor\Reflection\Php\Method;
+use phpDocumentor\Reflection\Php\Property;
 
 /**
  * Represents API documentation information for a `function`.
@@ -32,7 +37,7 @@ class FunctionDoc extends BaseDoc
 
 
     /**
-     * @param \phpDocumentor\Reflection\FunctionReflector $reflector
+     * @param Method $reflector
      * @param Context $context
      * @param array $config
      */
@@ -44,20 +49,20 @@ public function __construct($reflector = null, $context = null, $config = [])
             return;
         }
 
-        $this->isReturnByReference = $reflector->isByRef();
+        $this->isReturnByReference = false;//$reflector->isByRef();
 
         foreach ($reflector->getArguments() as $arg) {
             $arg = new ParamDoc($arg, $context, ['sourceFile' => $this->sourceFile]);
             $this->params[$arg->name] = $arg;
         }
 
         foreach ($this->tags as $i => $tag) {
-            if ($tag instanceof ThrowsTag) {
+            if ($tag instanceof Throws) {
                 $this->exceptions[$tag->getType()] = $tag->getDescription();
                 unset($this->tags[$i]);
-            } elseif ($tag instanceof PropertyTag) {
+            } elseif ($tag instanceof Property) {
                 // ignore property tag
-            } elseif ($tag instanceof ParamTag) {
+            } elseif ($tag instanceof Param) {
                 $paramName = $tag->getVariableName();
                 if (!isset($this->params[$paramName]) && $context !== null) {
                     $context->errors[] = [