Add $traceFileMap parameter to HtmlRenderer (#171)

[WarLikeLaux]

Q	A
Is bugfix?	❌
New feature?	✔️
Docs added?	❌
Tests added?	✔️
Breaks BC?	❌
Fixed issues	#155

What does this PR do?

Adds $traceFileMap parameter to HtmlRenderer for mapping file path prefixes in trace display and links, useful when the app runs inside Docker and IDE needs host paths.

Use cases

When running PHP inside a Docker container, stack trace file paths point to container paths (e.g. /app/src/index.php) which the IDE cannot open. This parameter maps container path prefixes to host machine paths:

$renderer = new HtmlRenderer(
    traceLink: 'phpstorm://open?file={file}&line={line}',
    traceFileMap: ['/app' => '/home/user/project'],
);
// /app/src/index.php -> /home/user/project/src/index.php

The mapping applies to both the displayed file path and the trace link URL. First matching prefix wins. Source code reading still uses the original (container) path so that code snippets render correctly.

Matching is path-boundary-aware: ['/app' => '/local'] maps /app/src/index.php but not /application/src/index.php. Both / and \ separators are supported. Empty keys are silently skipped, root prefix (/) is handled as a special case.

BC

No BC break: new constructor parameter with a default value of [], existing code unaffected.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.18%. Comparing base (7378764) to head (6709351).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff              @@
##             master     #171      +/-   ##
============================================
+ Coverage     86.92%   87.18%   +0.25%     
- Complexity      216      225       +9     
============================================
  Files            19       19              
  Lines           696      710      +14     
============================================
+ Hits            605      619      +14     
  Misses           91       91              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Adds support in HtmlRenderer to remap file path prefixes used in stack trace display/link generation (e.g., container paths → host paths), addressing docker/IDE path mismatches (Issue #155).

Changes:

• Add new HtmlRenderer::$traceFileMap constructor parameter and implement prefix-based path mapping via mapFilePath().
• Apply mapped file paths when rendering call stack items (affecting both displayed path and trace link URL).
• Add PHPUnit coverage for mapping behavior and an integration-style assertion that mapping appears in rendered call stack output.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
src/Renderer/HtmlRenderer.php	Introduces traceFileMap, implements mapFilePath(), and applies mapping during call stack item rendering.
tests/Renderer/HtmlRendererTest.php	Adds unit tests for mapping rules and verifies mapping appears in rendered call stack output.
CHANGELOG.md	Documents the new traceFileMap feature in the changelog.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.