[XDebug] Path mapping in PHP Storm

[adamziel]

When I use XDebug in Playground CLI with PHPStorm, my project directory may be anything from an empty dir to a full WordPress installation. If I mount pwd at /wordpress, PHPStorm can see most PHP files (maybe except for /internal) and I can set inspect code, set breakpoints, and step through those files in the code editor. However, if I don't mount anything, XDebug connects to Playground but then asks me to set up a path mapping. Currently, there's no way to do it – I don't have any files in my project directory. I notice I'm thinking "oh, I don't know how to use that".

Let's find a sensible way forward that would empower the user to debug their plugin, theme, entire WordPress site, whatever they have.

[adamziel]

An ideal user experience would be "the right PHP files just show up in my editor". One way that can happen is if we're working with a full WordPress site. But is there a way to do it if I'm only mounting a plugin but still want to step through WordPress code?

If not, what's the next best thing?

One idea is to tell the user "hey, all your WordPress files are available in this temporary local directory, map it to /wordpress and you're good". This would get annoying after a few restarts of CLI as the directory name would continue changing. Perhaps we could make the local path stable somehow? WDYT @brandonpayton?

Alternatively, we could start a local FTP/SFTP/whatever server from CLI for PHPStorm to connect and see all the VFS files – that's similar to the typical debugging over SSH experience.

[adamziel]

I've asked GPT this:

I use XDebug to debug a remote project in PHPStorm. The project is huge and I only have sftp access to a subdirectory. However, the execution often jumps out of that subdirectory. How do I set it up to step through the files that are outside of my sftp share?

And got this answer:

You can only step into files PhpStorm can open locally, so you need local copies of those “outside” files and correct path mappings.

Then I asked

Are you sure there isn't any way xdebug can send the right code to my PHPStorm? when I work with chrome devtools in similar situations, CDP supports transmitting file content so I can just see everything

And got this:

Short version: the DBGp protocol that Xdebug uses can send file contents (source), and Xdebug implements it. But PhpStorm does not use that for normal files. PhpStorm expects a local copy and path mappings; when it hits a file it can’t map, it literally tells you “Cannot find a local copy of the file … Click to set up mappings.” There isn’t a hidden toggle to make PhpStorm stream remote source like Chrome DevTools.

If you really want streamed source: some clients will render whatever Xdebug returns via source (handy for eval/virtual files and, in some tools, remote-only files). For example, Derick Rethans demonstrates debugging “source only available on the remote” in VS Code. That’s a different client behavior than PhpStorm’s.

There's also a link to https://xdebug.org/docs/dbgp that is timing out at the moment.

[brandonpayton]

One idea is to tell the user "hey, all your WordPress files are available in this temporary local directory, map it to /wordpress and you're good".

This is what I was coming here to propose as a first step.

This would get annoying after a few restarts of CLI as the directory name would continue changing. Perhaps we could make the local path stable somehow? WDYT @brandonpayton?

😅 yes, it could get annoying.

What if we select a ~/.playground/debug-wordpress dir or something like it when using the --xdebug option? We could confirm the dir isn't already in use.

[adamziel]

What if we select a ~/.playground/debug-wordpress dir or something like it when using the --xdebug option? We could confirm the dir isn't already in use.

Ooh sounds like a great idea! Maybe we could even choose a default directory name if not provided. The only missing bit are mounts. We can ask the user to set up 1 path mapping per mount, but maybe we can automate that for them by creating actual symlinks on the disk in place of mounts? And if that's not viable, perhaps we could generate some PHPStorm configuration they could copy and paste somewhere?

[adamziel]

I thought about leveraging the Import mappings from deployment configuration checkbox, but it seems like a no-go:

The dialog is available only when the PHP and FTP/SFTP/WebDAV Connectivity plugins are enabled. The plugins are not bundled with PhpStorm.

[adamziel]

Oh, more trouble. PHPStorm doesn't want to see those files anywhere on the disk. It wants them available within the current project directory:

[brandonpayton]

I don't have PHPStorm installed yet, but it sounds like PHPStorm projects can have multiple content root dirs? I wonder if someone debugging could just add such an xdebug target dir to their project. But if they are doing that, maybe they should manually manage providing a known mount in their project for /wordpress files.

[adamziel]

@brandonpayton that's a neat idea! It would also help us solve for this – PHPStorm really wants me to tell it where it can find the internal directory:

[brandonpayton]

@brandonpayton that's a neat idea! It would also help us solve for this – PHPStorm really wants me to tell it where it can find the internal directory:

If we can locate the main temp directory and map that, all relevant, top-level VFS folders should be contained in it: /internal, /wordpress, etc.

[brandonpayton]

Ooh sounds like a great idea! Maybe we could even choose a default directory name if not provided. The only missing bit are mounts. We can ask the user to set up 1 path mapping per mount, but maybe we can automate that for them by creating actual symlinks on the disk in place of mounts?

I thought symlinks could work well, but I even if it works I don't think it is a universal solution. We can create symlinks in the real temp dirs we create, but it seems too permissive to add symlinks to the real dirs mounted by users. If a user adds two mounts A and B with B a submount of A, I don't think a user would expect us to symlink B within A.

And if that's not viable, perhaps we could generate some PHPStorm configuration they could copy and paste somewhere?

I like the spirit of this question but am not very familiar with PHPStorm. I've been poking at it more today though.

Even without generating this kind of config for users, perhaps we could just give them a stable root temp directory name that they could configure for their project. Maybe we could have a param like --xdebug-session or --xdebug-name so users could give us a project name which we could turn into a stable directory location for their files.

I don't love the idea of adding such an option, but giving users the ability to be explicit and clear seems like a win to me.