Render exception class PHPDoc description in HTML debug output

src/Renderer/HtmlRenderer.php

@@ -16,6 +16,7 @@
 use Yiisoft\ErrorHandler\ThrowableRendererInterface;
 use Yiisoft\FriendlyException\FriendlyExceptionInterface;
 use Yiisoft\Http\Header;
+use ReflectionClass;
 use ReflectionException;
 use ReflectionFunction;
 use ReflectionMethod;
@@ -45,15 +46,22 @@
 use function ob_implicit_flush;
 use function ob_start;
 use function realpath;
+use function preg_match;
+use function preg_replace;
+use function preg_replace_callback;
+use function preg_split;
 use function str_replace;
+use function str_starts_with;
 use function stripos;
 use function strlen;
 use function count;
 use function function_exists;
+use function trim;
 
 use const DIRECTORY_SEPARATOR;
 use const ENT_QUOTES;
 use const EXTR_OVERWRITE;
+use const PREG_SPLIT_DELIM_CAPTURE;
 
 /**
  * Formats throwable into HTML string.
@@ -204,10 +212,16 @@ public function render(Throwable $t, ?ServerRequestInterface $request = null): E
 
     public function renderVerbose(Throwable $t, ?ServerRequestInterface $request = null): ErrorData
     {
+        $displayThrowable = $t instanceof CompositeException ? $t->getFirstException() : $t;
+        $exceptionDescription = $displayThrowable instanceof FriendlyExceptionInterface
+            ? null
+            : $this->getThrowableDescription($displayThrowable);
+
         return new ErrorData(
             $this->renderTemplate($this->verboseTemplate, [
                 'request' => $request,
                 'throwable' => $t,
+                'exceptionDescription' => $exceptionDescription,
             ]),
             [Header::CONTENT_TYPE => self::CONTENT_TYPE],
         );
@@ -541,6 +555,108 @@ public function removeAnonymous(string $value): string
         return $anonymousPosition !== false ? substr($value, 0, $anonymousPosition) : $value;
     }
 
+    /**
+     * Extracts a user-facing description from throwable class PHPDoc.
+     *
+     * Takes only descriptive text before block tags and normalizes inline
+     * {@see ...}/{@link ...} annotations into markdown-friendly form.
+     */
+    private function getThrowableDescription(Throwable $throwable): ?string
+    {
+        $docComment = (new ReflectionClass($throwable))->getDocComment();
+        if ($docComment === false) {
+            return null;
+        }
+
+        $descriptionLines = [];
+        foreach (preg_split('/\R/', $docComment) ?: [] as $line) {
+            $line = trim($line);
+            $line = preg_replace('/^\/\*\*?/', '', $line) ?? $line;
+            $line = preg_replace('/\*\/$/', '', $line) ?? $line;
+            $line = preg_replace('/^\*/', '', $line) ?? $line;
+            $line = trim($line);
+
+            if ($line !== '' && str_starts_with($line, '@')) {
+                break;
+            }
+
+            $descriptionLines[] = $line;
+        }
+
+        $description = trim(implode("\n", $descriptionLines));
+        if ($description === '') {
+            return null;
+        }
+
+        $description = preg_replace_callback(
+            '/\{@(see|link)\s+([^\s}]+)(?:\s+([^}]+))?}/i',
+            static function (array $matches): string {
+                $target = $matches[2];
+                $label = trim($matches[3] ?? '');
+
+                if (preg_match('/^https?:\/\//i', $target) === 1) {
+                    $text = $label !== '' ? $label : $target;
+                    return '[' . $text . '](' . $target . ')';
+                }
+
+                if ($label !== '') {
+                    return $label . ' (`' . $target . '`)';
+                }
+
+                return '`' . $target . '`';
+            },
+            $description,
+        ) ?? $description;
+
+        $paragraphs = preg_split('/\R\s*\R/', $description) ?: [];
+        $result = [];
+
+        foreach ($paragraphs as $paragraph) {
+            $paragraph = trim($paragraph);
+            if ($paragraph === '') {
+                continue;
+            }
+
+            $parts = preg_split(
+                '/(\[[^]]+]\([^)]+\)|`[^`]+`)/',
+                $paragraph,
+                -1,
+                PREG_SPLIT_DELIM_CAPTURE,
+            ) ?: [];
+
+            $html = '';
+            foreach ($parts as $part) {
+                if ($part === '') {
+                    continue;
+                }
+
+                if (preg_match('/^\[([^]]+)]\(([^)]+)\)$/', $part, $matches) === 1) {
+                    if (preg_match('/^https?:\/\//i', $matches[2]) === 1) {
+                        $html .= '<a href="' . $this->htmlEncode($matches[2]) . '">'
+                            . $this->htmlEncode($matches[1])
+                            . '</a>';
+                    } else {
+                        $html .= $this->htmlEncode($matches[1])
+                            . ' (<code>' . $this->htmlEncode($matches[2]) . '</code>)';
+                    }
+
+                    continue;
+                }
+
+                if (preg_match('/^`([^`]+)`$/', $part, $matches) === 1) {
+                    $html .= '<code>' . $this->htmlEncode($matches[1]) . '</code>';
+                    continue;
+                }
+
+                $html .= $this->htmlEncode($part);
+            }
+
+            $result[] = '<p>' . $html . '</p>';
+        }
+
+        return $result === [] ? null : implode("\n", $result);
+    }
+
     /**
      * Renders a template.
      *

templates/development.php

@@ -9,6 +9,7 @@
 /**
  * @var ServerRequestInterface|null $request
  * @var Throwable $throwable
+ * @var string|null $exceptionDescription
  */
 
 $theme = $_COOKIE['yii-exception-theme'] ?? '';
@@ -93,6 +94,10 @@
             <?= nl2br($this->htmlEncode($exceptionMessage)) ?>
         </div>
 
+        <?php if ($exceptionDescription !== null): ?>
+            <div class="exception-description solution"><?= $exceptionDescription ?></div>
+        <?php endif ?>
+
         <?php if ($solution !== null): ?>
             <div class="solution"><?= $this->parseMarkdown($solution) ?></div>
         <?php endif ?>

tests/Renderer/HtmlRendererTest.php

@@ -15,7 +15,13 @@
 use RuntimeException;
 use Yiisoft\ErrorHandler\Exception\ErrorException;
 use Yiisoft\ErrorHandler\Renderer\HtmlRenderer;
+use Yiisoft\ErrorHandler\Tests\Support\TestDocBlockException;
+use Yiisoft\ErrorHandler\Tests\Support\TestEmptyDescriptionDocBlockException;
+use Yiisoft\ErrorHandler\Tests\Support\TestExceptionWithoutDocBlock;
+use Yiisoft\ErrorHandler\Tests\Support\TestFriendlyException;
 use Yiisoft\ErrorHandler\Tests\Support\TestHelper;
+use Yiisoft\ErrorHandler\Tests\Support\TestInlineCodeDocBlockException;
+use Yiisoft\ErrorHandler\Tests\Support\TestUnsafeDocBlockException;
 
 use function dirname;
 use function file_exists;
@@ -66,6 +72,82 @@ public function testVerboseOutput(): void
         $this->assertStringContainsString($exceptionMessage, (string) $errorData);
     }
 
+    public function testVerboseOutputRendersThrowableDescriptionFromDocComment(): void
+    {
+        $renderer = new HtmlRenderer();
+        $exception = new TestDocBlockException('exception-test-message');
+
+        $errorData = $renderer->renderVerbose($exception, $this->createServerRequestMock());
+        $result = (string) $errorData;
+
+        $this->assertStringContainsString('<div class="exception-description solution">', $result);
+        $this->assertStringContainsString('Test summary with <code>RuntimeException</code>.', $result);
+        $this->assertStringContainsString(
+            '<a href="https://www.yiiframework.com">Yii Framework</a>',
+            $result,
+        );
+    }
+
+    public function testVerboseOutputDoesNotRenderThrowableDescriptionWhenNoDocComment(): void
+    {
+        $renderer = new HtmlRenderer();
+        $exception = new TestExceptionWithoutDocBlock('exception-test-message');
+
+        $errorData = $renderer->renderVerbose($exception, $this->createServerRequestMock());
+
+        $this->assertStringNotContainsString('<div class="exception-description solution">', (string) $errorData);
+    }
+
+    public function testVerboseOutputDoesNotRenderThrowableDescriptionWhenDocCommentHasNoDescription(): void
+    {
+        $renderer = new HtmlRenderer();
+        $exception = new TestEmptyDescriptionDocBlockException('exception-test-message');
+
+        $errorData = $renderer->renderVerbose($exception, $this->createServerRequestMock());
+
+        $this->assertStringNotContainsString('<div class="exception-description solution">', (string) $errorData);
+    }
+
+    public function testVerboseOutputKeepsFriendlyExceptionBehaviorWithoutDescriptionDuplication(): void
+    {
+        $renderer = new HtmlRenderer();
+        $exception = new TestFriendlyException('exception-test-message');
+
+        $errorData = $renderer->renderVerbose($exception, $this->createServerRequestMock());
+        $result = (string) $errorData;
+
+        $this->assertStringContainsString('<div class="solution">', $result);
+        $this->assertStringNotContainsString('<div class="exception-description solution">', $result);
+    }
+
+    public function testVerboseOutputEscapesUnsafeThrowableDescriptionLinks(): void
+    {
+        $renderer = new HtmlRenderer();
+        $exception = new TestUnsafeDocBlockException('exception-test-message');
+
+        $errorData = $renderer->renderVerbose($exception, $this->createServerRequestMock());
+        $result = (string) $errorData;
+
+        $this->assertStringNotContainsString('href="javascript:alert(1)"', $result);
+        $this->assertStringContainsString('Click me (<code>javascript:alert(1)</code>)', $result);
+        $this->assertStringContainsString(
+            '<a href="https://www.yiiframework.com">Safe link</a>',
+            $result,
+        );
+    }
+
+    public function testVerboseOutputRendersInlineCodeAndSeeTagWithoutLabel(): void
+    {
+        $renderer = new HtmlRenderer();
+        $exception = new TestInlineCodeDocBlockException('exception-test-message');
+
+        $errorData = $renderer->renderVerbose($exception, $this->createServerRequestMock());
+        $result = (string) $errorData;
+
+        $this->assertStringContainsString('<code>inline-code</code>', $result);
+        $this->assertStringContainsString('<code>RuntimeException</code>', $result);
+    }
+
     public function testNonVerboseOutputWithCustomTemplate(): void
     {
         $templateFileContents = '<html><?php echo $throwable->getMessage();?></html>';

tests/Support/TestDocBlockException.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\ErrorHandler\Tests\Support;
+
+use RuntimeException;
+
+/**
+ * Test summary with {@see RuntimeException}.
+ *
+ * More details with {@link https://www.yiiframework.com Yii Framework}.
+ *
+ * @link https://example.com Ignored tag.
+ */
+final class TestDocBlockException extends RuntimeException {}

tests/Support/TestEmptyDescriptionDocBlockException.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\ErrorHandler\Tests\Support;
+
+use RuntimeException;
+
+/**
+ *
+ * @link https://example.com Ignored tag.
+ */
+final class TestEmptyDescriptionDocBlockException extends RuntimeException {}

tests/Support/TestExceptionWithoutDocBlock.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\ErrorHandler\Tests\Support;
+
+use RuntimeException;
+
+final class TestExceptionWithoutDocBlock extends RuntimeException {}

tests/Support/TestInlineCodeDocBlockException.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\ErrorHandler\Tests\Support;
+
+use RuntimeException;
+
+/**
+ * Description with raw `inline-code` and {@see RuntimeException}.
+ */
+final class TestInlineCodeDocBlockException extends RuntimeException {}

tests/Support/TestUnsafeDocBlockException.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\ErrorHandler\Tests\Support;
+
+use RuntimeException;
+
+/**
+ * Unsafe HTML <img src="x" onerror="alert(1)"> should not survive.
+ *
+ * {@link javascript:alert(1) Click me} and {@link https://www.yiiframework.com Safe link}.
+ */
+final class TestUnsafeDocBlockException extends RuntimeException {}