2026-02-10

February: Native Path Mappping in the Wild

Fabian Potencier, from Symfony fame, has created an exploratory patch for Twig to make use of Xdebug's new Native Path Mapping functionality.

From the initial patch, it became clear that a few things need to be improved on the Xdebug side for this to be a complete feature. For that reason, I have created a few issues to work on:

Invent better way of configuring lots of line-to-line mappings

Right now, each line mapping needs to have a special line, resulting in mapping file that look like:

user-info-823edfe12e38a649355c5172b9d98e0a.php:2-31 = user-info.ezt:1
user-info-823edfe12e38a649355c5172b9d98e0a.php:32-33 = user-info.ezt:2
user-info-823edfe12e38a649355c5172b9d98e0a.php:34-36 = user-info.ezt:3
user-info-823edfe12e38a649355c5172b9d98e0a.php:37 = user-info.ezt:4
user-info-823edfe12e38a649355c5172b9d98e0a.php:38 = user-info.ezt:5
user-info-823edfe12e38a649355c5172b9d98e0a.php:39-40 = user-info.ezt:6
user-info-823edfe12e38a649355c5172b9d98e0a.php:41-46 = user-info.ezt:7
…
user-info-823edfe12e38a649355c5172b9d98e0a.php:301-302 = user-info.ezt:73
user-info-823edfe12e38a649355c5172b9d98e0a.php:303 = user-info.ezt:74-75
user-info-823edfe12e38a649355c5172b9d98e0a.php:304-306 = user-info.ezt:76

This is really ineffecient, so I will be looking at a way to collapse these all in one line.

Create xdebug_add_source_map_directory() function

Right now, Xdebug will check for path mapping files only in some parent .xdebug/ directories. As Twig, and likely other tools, would want to generate their own files into their own cache directory, it is needed that tools can specify these extra directories.

Add EOF marker/stanza to native path file mapper

The Twig mapping generator is using 999999 to denote the end of a line range, to mean "end of file". It would be better that Xdebug implements a specific keyword (think EOF) for this instead so that now arbitrary numbers have to be used.

I am hoping to work on these features in the next few months to land in Xdebug 3.6, which I am planning to release in the middle of this year.

Additionally, my PhpStorm issue to allow for the setting of breakpoints in template file has now been merged, and is scheduled for 2026.1 EAP 2. At the time of writing this isn't quite out yet, so I will keep you posted.