Add $traceLink parameter to HtmlRenderer (#151)

Co-authored-by: Alexander Makarov <[email protected]>

Author: vjik

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## 4.1.1 under development
 
 - Enh #150: Cleanup templates, remove legacy code (@vjik)
+- New #151: Add `$traceLink` parameter to `HtmlRenderer` to allow linking to trace files (@vjik)
 
 ## 4.1.0 April 18, 2025
 

src/Renderer/HtmlRenderer.php

@@ -6,6 +6,7 @@
 
 use Alexkart\CurlBuilder\Command;
 use cebe\markdown\GithubMarkdown;
+use Closure;
 use Psr\Http\Message\ServerRequestInterface;
 use RuntimeException;
 use Throwable;
@@ -48,6 +49,7 @@
 /**
  * Formats throwable into HTML string.
  *
+ * @psalm-type TraceLinkClosure = Closure(string $file, int|null $line): (string|null)
  * @psalm-import-type DebugBacktraceType from ErrorException
  */
 final class HtmlRenderer implements ThrowableRendererInterface
@@ -99,6 +101,11 @@ final class HtmlRenderer implements ThrowableRendererInterface
      */
     public readonly ?string $traceHeaderLine;
 
+    /**
+     * @psalm-var TraceLinkClosure
+     */
+    public readonly Closure $traceLinkGenerator;
+
     /**
      * @var string[]|null The list of vendor paths is determined automatically.
      *
@@ -120,7 +127,20 @@ final class HtmlRenderer implements ThrowableRendererInterface
      * information.
      * @param int|null $maxSourceLines The maximum number of source code lines to be displayed. Defaults to 19.
      * @param int|null $maxTraceLines The maximum number of trace source code lines to be displayed. Defaults to 13.
-     * @param string|null $traceHeaderLine The trace header line with placeholders to be substituted. Defaults to null.
+     * @param string|null $traceHeaderLine Deprecated, use {@see traceLink} instead. The trace header line with
+     * placeholders to be substituted. Defaults to null.
+     * @param Closure|string|null $traceLink The trace link. It can be a string with placeholders `file` and `line` to
+     * be substituted or a closure that accepts `file` and `line` parameters and returns a string or null. Examples:
+     *  - string "ide://open?file={file}&line={line}";
+     *  - closure:
+     *    ```php
+     *    static function (string $file, ?int $line): string {
+     *        return strtr(
+     *            'phpstorm://open?file={file}&line={line}',
+     *            ['{file}' => $file, '{line}' => (string) $line],
+     *        );
+     *    }
+     *    ```
      *
      * @psalm-param array{
      *   template?: string,
@@ -129,6 +149,7 @@ final class HtmlRenderer implements ThrowableRendererInterface
      *   maxTraceLines?: int,
      *   traceHeaderLine?: string,
      * } $settings
+     * @psalm-param string|TraceLinkClosure|null $traceLink
      */
     public function __construct(
         array $settings = [],
@@ -137,6 +158,7 @@ public function __construct(
         ?int $maxSourceLines = null,
         ?int $maxTraceLines = null,
         ?string $traceHeaderLine = null,
+        string|Closure|null $traceLink = null,
     ) {
         $this->markdownParser = new GithubMarkdown();
         $this->markdownParser->html5 = true;
@@ -157,6 +179,7 @@ public function __construct(
         $this->traceHeaderLine = $traceHeaderLine
             ?? $settings['traceHeaderLine']
             ?? null;
+        $this->traceLinkGenerator = $this->createTraceLinkGenerator($traceLink);
     }
 
     public function render(Throwable $t, ?ServerRequestInterface $request = null): ErrorData
@@ -703,4 +726,23 @@ public function removeAnonymous(string $value): string
 
         return $anonymousPosition !== false ? substr($value, 0, $anonymousPosition) : $value;
     }
+
+    /**
+     * @psalm-param string|TraceLinkClosure|null $traceLink
+     * @psalm-return TraceLinkClosure
+     */
+    private function createTraceLinkGenerator(string|Closure|null $traceLink): Closure
+    {
+        if ($traceLink === null) {
+            return static fn(): string|null => null;
+        }
+
+        if (is_string($traceLink)) {
+            return static function (string $file, ?int $line) use ($traceLink): string {
+                return str_replace(['{file}', '{line}'], [$file, (string) $line], $traceLink);
+            };
+        }
+
+        return $traceLink;
+    }
 }

templates/_call-stack-item.php

@@ -34,17 +34,34 @@
         <div class="flex-1 mw-100">
             <?php if ($file !== null): ?>
                 <span class="file-name">
-                    <?= "{$index}. in {$this->htmlEncode($file)}" ?>
-                    <?php if ($this->traceHeaderLine !== null): ?>
-                        <?= strtr($this->traceHeaderLine, ['{file}' => $file, '{line}' => (int) $line + 1, '{icon}' => $icon]) ?>
-                    <?php endif ?>
+                    <?php
+                    if ($this->traceHeaderLine === null) {
+                        echo "$index. ";
+                        $traceLink = ($this->traceLinkGenerator)($file, $line);
+                        echo $traceLink === null
+                            ? $this->htmlEncode($file)
+                            : sprintf(
+                                '<a href="%s" class="trace-link">%s %s</a>',
+                                $this->htmlEncode($traceLink),
+                                $this->htmlEncode($file),
+                                $icon,
+                            );
+                    } else {
+                        echo "$index. " . $this->htmlEncode($file);
+                        echo strtr($this->traceHeaderLine, [
+                            '{file}' => $file,
+                            '{line}' => (int) $line + 1,
+                            '{icon}' => $icon,
+                        ]);
+                    }
+                    ?>
                 </span>
             <?php endif ?>
 
             <?php if ($function !== null): ?>
                 <span class="function-info word-break">
                     <?php
-                    echo $file === null ? "{$index}." : '&mdash;&nbsp;';
+                    echo $file === null ? "$index. " : '&mdash;&nbsp;';
                     $function = $class === null ? $function : "{$this->removeAnonymous($class)}::$function";
 
                     echo '<span class="function">' . $this->htmlEncode($function) . '</span>';

templates/development.css

@@ -572,7 +572,17 @@ main {
     color: var(--element-wrap-text-color);
 }
 
-.call-stack ul li .element-wrap .file-name:hover,
+.call-stack ul li .element-wrap .file-name .trace-link {
+    color: var(--element-wrap-text-color);
+    text-decoration: none;
+}
+.call-stack ul li .element-wrap .file-name .trace-link:hover {
+    color: var(--element-wrap-hover-text-color);
+}
+.call-stack ul li .element-wrap .file-name .trace-link:hover path {
+    fill: var(--icon-color);
+}
+
 .call-stack ul li .element-code-wrap .code-wrap .lines-item:hover {
     color: var(--element-wrap-hover-text-color);
 }

tests/Renderer/HtmlRendererTest.php

@@ -303,6 +303,39 @@ public function testIsVendorFileWithPathsAlreadyAdded(): void
         $this->assertFalse($this->invokeMethod($renderer, 'isVendorFile', ['file' => __FILE__]));
     }
 
+    public static function dataTraceLinkGenerator(): iterable
+    {
+        yield [null, static fn() => null];
+        yield [
+            'phpstorm://open?file=test.php&line=42',
+            static fn(string $file, int|null $line) => "phpstorm://open?file=$file&line=$line",
+        ];
+        yield [
+            'phpstorm://open?file=test.php&line=42',
+            'phpstorm://open?file={file}&line={line}',
+        ];
+        yield [
+            'phpstorm://open?file=test.php&line=',
+            'phpstorm://open?file={file}&line={line}',
+            'test.php',
+            null,
+        ];
+    }
+
+    #[DataProvider('dataTraceLinkGenerator')]
+    public function testTraceLinkGenerator(
+        string|null $expected,
+        mixed $traceLink,
+        string $file = 'test.php',
+        int|null $line = 42,
+    ): void {
+        $renderer = new HtmlRenderer(traceLink: $traceLink);
+
+        $link = ($renderer->traceLinkGenerator)($file, $line);
+
+        $this->assertSame($expected, $link);
+    }
+
     private function createServerRequestMock(): ServerRequestInterface
     {
         $serverRequestMock = $this->createMock(ServerRequestInterface::class);