Log invalid tags

CHANGELOG.md

@@ -4,7 +4,7 @@ Yii Framework 2 apidoc extension Change Log
 3.0.9 under development
 -----------------------
 
-- no changes in this release.
+- Enh #337: Log invalid tags (mspirkov)
 
 
 3.0.8 November 24, 2025

models/BaseDoc.php

@@ -1,4 +1,5 @@
 <?php
+
 /**
  * @link https://www.yiiframework.com/
  * @copyright Copyright (c) 2008 Yii Software LLC
@@ -10,6 +11,7 @@
 use phpDocumentor\Reflection\DocBlock\Tag;
 use phpDocumentor\Reflection\DocBlock\Tags\Deprecated;
 use phpDocumentor\Reflection\DocBlock\Tags\Generic;
+use phpDocumentor\Reflection\DocBlock\Tags\InvalidTag;
 use phpDocumentor\Reflection\DocBlock\Tags\Since;
 use phpDocumentor\Reflection\Php\Class_;
 use phpDocumentor\Reflection\Php\Constant;
@@ -193,6 +195,19 @@ public function __construct($reflector = null, $context = null, $config = [])
             } elseif ($tag instanceof Generic && $tag->getName() === self::TODO_TAG_NAME) {
                 $this->todos[] = $tag;
                 unset($this->tags[$i]);
+            } elseif ($tag instanceof InvalidTag && $context !== null) {
+                $exception = $tag->getException();
+                $message = 'Invalid tag: ' . $tag->render() . '.';
+
+                if ($exception !== null) {
+                    $message .= ' Exception message: ' . $exception->getMessage();
+                }
+
+                $context->errors[] = [
+                    'line' => $this->startLine,
+                    'file' => $this->sourceFile,
+                    'message' => $message,
+                ];
             }
         }
 
@@ -242,7 +257,8 @@ public static function extractFirstSentence($text, $prevText = '')
             if ($length >= $pos + 2) {
                 $abbrev = mb_substr($text, $pos - 3, 4, 'utf-8');
                 // do not break sentence after abbreviation
-                if ($abbrev === 'e.g.' ||
+                if (
+                    $abbrev === 'e.g.' ||
                     $abbrev === 'i.e.' ||
                     mb_substr_count($prevText, '`', 'utf-8') % 2 === 1
                 ) {

tests/commands/ApiControllerTest.php

@@ -99,5 +99,15 @@ public function testGenerateBootstrap()
         $sourceFilesCount = count(FileHelper::findFiles($sourceFilesDir, ['recursive' => true]));
 
         $this->assertSame($sourceFilesCount, $filesCount);
+
+        $warningsContent = file_get_contents("{$outputPath}/warnings.txt");
+        // Remove the dynamic parts of the file paths
+        $warningsContent = preg_replace('/(\s*\[file\] => ).*(\/tests\/.*\.php)/', '$1$2', $warningsContent);
+        $this->assertMatchesTextSnapshot($warningsContent);
+
+        $errorsContent = file_get_contents("{$outputPath}/errors.txt");
+        // Remove the dynamic parts of the file paths
+        $errorsContent = preg_replace('/(\s*\[file\] => ).*(\/tests\/.*\.php)/', '$1$2', $errorsContent);
+        $this->assertMatchesTextSnapshot($errorsContent);
     }
 }

tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__3.html

@@ -166,6 +166,11 @@ <h2>Public Methods</h2>
                     <td><a href="yiiunit-apidoc-data-api-animal-dog.html#isOlder()-detail">isOlder()</a></td>
                     <td>Checks whether the animal is older than the specified time.</td>
                     <td><a href="yiiunit-apidoc-data-api-animal-animal.html">yiiunit\apidoc\data\api\animal\Animal</a></td>
+                </tr>
+                                                <tr class="">
+                    <td><a href="yiiunit-apidoc-data-api-animal-dog.html#methodWithInvalidReturnTag()-detail">methodWithInvalidReturnTag()</a></td>
+                    <td></td>
+                    <td><a href="yiiunit-apidoc-data-api-animal-dog.html">yiiunit\apidoc\data\api\animal\Dog</a></td>
                 </tr>
                                                 <tr class="">
                     <td><a href="yiiunit-apidoc-data-api-animal-dog.html#render()-detail">render()</a></td>
@@ -406,6 +411,50 @@ <h2>Method Details</h2>
 </span>{
     <span class="hljs-keyword">return</span><span class="hljs-keyword">$this</span>-&gt;getAge() &gt; $date;
 }
+</code>
+            </pre>
+        </div>
+    </div>
+
+        </div>
+            <div class="">
+            <div class="detail-header h3">
+                <a class="tool-link" title="go to top"><span class="glyphicon glyphicon-arrow-up"></span></a>
+                <a class="tool-link hash" href="yiiunit-apidoc-data-api-animal-dog.html#methodWithInvalidReturnTag()-detail" title="direct link to this method"><span class="glyphicon icon-hash"></span></a>
+
+                methodWithInvalidReturnTag()
+
+                <span class="detail-header-tag small">
+                    public                                                            method
+                                    </span>
+            </div>
+
+
+            <div class="doc-description">
+
+                <p><strong></strong></p>
+                                            </div>
+
+            <table class="detail-table table table-striped table-bordered table-hover">
+                <tr><td colspan="3" class="signature">
+<span class="signature-defs">public</span><span class="signature-type"><a href="https://www.php.net/language.types.mixed">mixed</a></span><strong><a href="yiiunit-apidoc-data-api-animal-dog.html#methodWithInvalidReturnTag()-detail">methodWithInvalidReturnTag</a></strong> ( )</td></tr>
+
+                            </table>
+
+
+
+
+    <p>
+        <a class="btn btn-link" data-toggle="collapse" role="button" aria-expanded="false" aria-controls="collapseMethodWithInvalidReturnTag">
+            Source code
+        </a>
+    </p>
+    <div class="collapse">
+        <div class="card card-body">
+            <pre>
+                <code class="hljs php language-php"><span class="hljs-keyword">public</span><span class="hljs-function"><span class="hljs-keyword">function</span><span class="hljs-title">methodWithInvalidReturnTag</span><span class="hljs-params">()</span>
+</span>{
+}
 </code>
             </pre>
         </div>

tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__5.txt

@@ -0,0 +1,66 @@
+Array
+(
+    [0] => Array
+        (
+            [line] => 41
+            [file] => /tests/data/api/animal/Animal.php
+            [message] => No docblock for element '$propertyWithoutDoc'
+        )
+
+    [1] => Array
+        (
+            [line] => 41
+            [file] => /tests/data/api/animal/Animal.php
+            [message] => No short description for element '$propertyWithoutDoc'
+        )
+
+    [2] => Array
+        (
+            [line] => 43
+            [file] => /tests/data/api/animal/Animal.php
+            [message] => No docblock for element '$propertyWithoutDocAndTypeHint'
+        )
+
+    [3] => Array
+        (
+            [line] => 43
+            [file] => /tests/data/api/animal/Animal.php
+            [message] => No short description for element '$propertyWithoutDocAndTypeHint'
+        )
+
+    [4] => Array
+        (
+            [line] => 70
+            [file] => /tests/data/api/animal/Animal.php
+            [message] => No docblock for element 'setBirthDate'
+        )
+
+    [5] => Array
+        (
+            [line] => 32
+            [file] => /tests/data/api/animal/Cat.php
+            [message] => No docblock for element 'methodWithoutDocAndTypeHints'
+        )
+
+    [6] => Array
+        (
+            [line] => 40
+            [file] => /tests/data/api/animal/Cat.php
+            [message] => No short description for Method 'methodWithTodoTag'
+        )
+
+    [7] => Array
+        (
+            [line] => 30
+            [file] => /tests/data/api/animal/Dog.php
+            [message] => No short description for Method 'methodWithInvalidReturnTag'
+        )
+
+    [8] => Array
+        (
+            [line] => 11
+            [file] => /tests/data/api/base/Component.php
+            [message] => No docblock for element 'yiiunit\apidoc\data\api\base\Component'
+        )
+
+)

tests/commands/__snapshots__/ApiControllerTest__testGenerateBootstrap__6.txt

@@ -0,0 +1,10 @@
+Array
+(
+    [0] => Array
+        (
+            [line] => 30
+            [file] => /tests/data/api/animal/Dog.php
+            [message] => Invalid tag: @return invalid-type. Exception message: "\yiiunit\apidoc\data\api\animal\invalid-type" is not a valid Fqsen.
+        )
+
+)

tests/data/api/animal/Dog.php

@@ -23,4 +23,11 @@ public function render()
         // this method has `inheritdoc` tag without brackets
         return 'This is a dog';
     }
+
+    /**
+     * @return invalid-type
+     */
+    public function methodWithInvalidReturnTag()
+    {
+    }
 }