Add support for XDebug path mapping by fabpot · Pull Request #4733 · twigphp/Twig

fabpot · 2026-01-12T16:25:50Z

Closes #4697

CHANGELOG

src/Cache/ChainCache.php

doc/recipes.rst

fabpot · 2026-01-13T08:55:34Z

src/Cache/XdebugSourceMapCache.php

+            }
+
+            foreach (glob($mapPath.'/*.map') as $mapFile) {
+                xdebug_set_source_map($mapFile);


This function is not available yet but this is the cleaneast way to do it IMHO.

is there any public discussion on the Xdebug side about this function ?

Btw, the verb set in the name is confusing if it registers a new source map without removing the previous one, as that's not the usual meaning of set in function names.

As this is a feature that I haven't added yet, I am more than happy to discuss how it should work. I agree that using xdebug_add_source_map is probably a better choice. Right now, the internals will reject a new source map if it touches the same files though, and that seems not so easy to change.

Alternatively, I could add a new function xdebug_add_source_map_directory, which you would only have to call once before the compiled template files are loaded into PHP's memory through include.

Then Xdebug can (additionally) scan this directory to pick up any source maps that exist.

xdebug_add_source_map_directory might be better for the Twig use case indeed (and might maybe have less overhead for requests not using breakpoints by skipping the filesystem scanning, depending on when xdebug actually traverses those directories)

It currently scans the files (if path mapping is enabled) at the start of every request. Although for now, it only works with the step debugger, in the future I want to extend the support to maps to other features too: https://xdebug.org/funding/001-native-path-mapping#future-scope

fabpot · 2026-01-13T08:58:50Z

@derickr I would love to get your feedback on how I've integrated the source map feature with Twig.

src/Cache/XdebugSourceMapCache.php

stof · 2026-01-13T10:07:45Z

src/Cache/ChainCache.php

+        $directories = [];
+        foreach ($this->caches as $cache) {
+            if ($cache instanceof DirectoryCacheInterface) {
+                $directories []= $cache->getDirectories();


Suggested change

$directories []= $cache->getDirectories();

$directories[] = $cache->getDirectories();

derickr

Thanks for looking into this!

I left some comments and questions to ask how things can be improved.

I'm also still waiting on https://youtrack.jetbrains.com/issue/WI-81344/Cant-Set-Breakpoints-in-Template-Files-Even-Though-I-Added-The-File-Name-Pattern-to-PHP to make it into a release of PhpStorm (it's already fine with VS Code's Plugin)

derickr · 2026-01-14T10:41:26Z

src/Cache/XdebugSourceMapCache.php

+            }
+
+            foreach (glob($mapPath.'/*.map') as $mapFile) {
+                xdebug_set_source_map($mapFile);


As this is a feature that I haven't added yet, I am more than happy to discuss how it should work. I agree that using xdebug_add_source_map is probably a better choice. Right now, the internals will reject a new source map if it touches the same files though, and that seems not so easy to change.

Alternatively, I could add a new function xdebug_add_source_map_directory, which you would only have to call once before the compiled template files are loaded into PHP's memory through include.

Then Xdebug can (additionally) scan this directory to pick up any source maps that exist.

derickr · 2026-01-14T10:44:43Z

src/Cache/XdebugSourceMapCache.php

+                $endLine,
+                basename($templatePath),
+                $debugInfo[$startLine],
+            );


I imagine, this gets large, as there is a separate entry in the source file for each line.

I am planning on optimising this, using how JavaScript source maps approach the line-to-line mappings, if possible.

I would also recommend that if $startLine and $endline are the same, you should not include the $endLine in the mapping. It saves some processing on the Xdebug side (runs many times), where doing the test here needs to be done once per map-write.

derickr · 2026-01-14T10:50:16Z

src/Cache/XdebugSourceMapCache.php

+            $startLine = $compiledLines[$i];
+            // End line is exclusive, so use next start line minus 1
+            // Use a reasonable max for last range (Xdebug can't handle PHP_INT_MAX)
+            $endLine = isset($compiledLines[$i + 1]) ? $compiledLines[$i + 1] - 1 : 999999;


I don't like it that you need to use a random largish constant (999999) here. Perhaps it would make sense if I add an EOF marker to the parser, so that you can do:

compiled_file.php:5-EOF = orig_file.twig:4

Would that be helpful?

it would definitely be helpful here.

derickr · 2026-01-15T13:02:23Z

I've created the following tickets for myself:

fabpot force-pushed the xdebug-support branch from d8b025e to 8856b90 Compare January 12, 2026 16:29

jdreesen reviewed Jan 12, 2026

View reviewed changes

CHANGELOG Outdated Show resolved Hide resolved

Kocal reviewed Jan 12, 2026

View reviewed changes

src/Cache/ChainCache.php Outdated Show resolved Hide resolved

stof reviewed Jan 12, 2026

View reviewed changes

doc/recipes.rst Outdated Show resolved Hide resolved

doc/recipes.rst Outdated Show resolved Hide resolved

doc/recipes.rst Outdated Show resolved Hide resolved

doc/recipes.rst Outdated Show resolved Hide resolved

fabpot force-pushed the xdebug-support branch 4 times, most recently from f531331 to 5a46aa6 Compare January 13, 2026 08:52

fabpot commented Jan 13, 2026

View reviewed changes

jdreesen reviewed Jan 13, 2026

View reviewed changes

src/Cache/XdebugSourceMapCache.php Outdated Show resolved Hide resolved

fabpot force-pushed the xdebug-support branch from 5a46aa6 to e717cb6 Compare January 13, 2026 09:04

stof reviewed Jan 13, 2026

View reviewed changes

Add support for XDebug path mapping

64a7bf9

fabpot force-pushed the xdebug-support branch from e717cb6 to 64a7bf9 Compare January 14, 2026 07:47

derickr reviewed Jan 14, 2026

View reviewed changes

	$directories []= $cache->getDirectories();
	$directories[] = $cache->getDirectories();

Uh oh!

Comments

Conversation

fabpot commented Jan 12, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fabpot commented Jan 13, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

derickr left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

derickr commented Jan 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

5 participants