XDebug & phpStorm

filliph

I know on the website XDebug is shown as “coming soon”, but when it does, I’m hoping it will support dynamic loading.

My current setup with Docker is such that when nginx / php-fpm sees the phpStorm debug flag (set when you press the little telephone like icon in phpStorm), it routes the request through an instance of php-fpm that has XDebug compiled. If that flag is not present, no such routing occurs.

This is immensely useful because even XDebug 3 has severe performance degradation, so I’d prefer to only run it when I need more than the standard dump/die paradigm.

fmitchell

wow. filliph would you be open to sharing how you set that up?

Indigo

You're absolute right about the xdebug performance hit. In Indigo's PHP's Xdebug is always-on at present as you probably noticed; I have a feature planned whereby Indigo would monitor for apps listening on the Xdebug port and automatically enable/disable Xdebug based on that. I'd probably throw up a macOS notification when it changes Xdebug state.

However I'm wondering if there's an established way for a php-fpm to know when someone is listening for xdebug. Do you know how your docker containers do that?

Indigo

Thanks @filliph that's immensely useful. Can you confirm my understanding — with that config, you can enable/disable xdebug by setting the XDEBUG_SESSION_START environment variable? (I think I now recall a similar mechanism enabling xdebug by setting a request header or even appending a query string.)

If so, I'm assuming phpStorm is taking care of this for you at the push of a button — I would imagine VS Code would have a way to do this also, but I'm guessing many other editors won't.

Indigo I have a feature planned whereby Indigo would monitor for apps listening on the Xdebug port and automatically enable/disable Xdebug based on that.

I am wondering whether my port-watching idea would mean I can provide a fully-automatic solution to enabling Xcode, without the user having to configure an environment variable or whatnot. Your thoughts?

filliph

@fmitchell @Indigo here's the relevant part of nginx.conf:

http {
    [...]

    # Define available upstreams
    upstream php-fpm {
        server unix:/shared/var/run/php-fpm.sock;
    }

    # Define available upstreams
    upstream php-fpm-xdebug {
        server unix:/shared/var/run/php-fpm-xdebug.sock;
    }

    # XDebug mappings.
    map $arg_XDEBUG_SESSION_START $session_arg_pass {
        default php-fpm;
        1 php-fpm-xdebug;
    }

    map $cookie_XDEBUG_SESSION $cookie_arg_pass {
        default $session_arg_pass;
        xdebug php-fpm-xdebug;
        1 php-fpm-xdebug;
        PHPSTORM php-fpm-xdebug;
        XDEBUG_ECLIPSE php-fpm-xdebug;
    }

    map $arg_XDEBUG_PROFILE $xdebug_test_pass {
        default $cookie_arg_pass;
        1 php-fpm-xdebug;
    }

    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*.conf;
}

filliph

Indigo phpStorm doesn't toggle any environment variables, I believe the $arg_ portion is for the docker-compose.yml file to add it there should you so choose.

phpStorm (and presumably other IDEs) are just listeners. They don't interfere with any environment variable whatsoever. phpStorm requires you to use a browser extension to toggle debugging: https://www.jetbrains.com/help/phpstorm/2022.1/browser-debugging-extensions.html - these extensions will then offer configuration options that lets you set the session key, which is what the PHPSTORM and XDEBUG_ECLIPSE refers to.

Adding a session key will add a cookie when you enable XDebug, which is then picked up by the above nginx.conf block.

Port watching will not work because it's possible to change ports, and it doesn't make sense for you to try to either guess the port or offer an option when the cookie function exists already.

EDIT: Oh, and $xdebug_test_pass needs to be passed to fastcgi for Nginx:

    location ~ \.php$ {
        set $px $1;

        # send to fastcgi
        include fastcgi.conf;

        fastcgi_pass $xdebug_test_pass;
    }

    location ~* "\.php(/|$)" {
        # send to fastcgi
        include fastcgi.conf;
        fastcgi_pass $xdebug_test_pass;
    }

Indigo

Using nginx's upstream to switch Xdebug on or off is interesting — I've never configured Xdebug that way before. Of course I'd need something similar to en/disable Xdebug in Apache (I assume it's possible), and indeed for the command line for those occasions you might want to Xdebug a command line PHP script.

I'm really hoping my port-monitoring solution might provide a way to switch Xdebug in all scenarios, in a transparent manner. I've put a proof-of-concept into the current release of Indigo, whereby I show a little green "On" light beside Xdebug in the PHP service, when Indigo detects a GDBP debugger is active. Two things to note about this implementation right now:

1) it doesn't actually enable or disable Xdebug; right now Xdebug is permanently on.
2) it's currently buggy! The light sometimes does not turn on, or sometimes not turn off, when it should.

Please let me know if I'm misunderstanding something and this idea fundamentally would not work for you this way. But otherwise, give it a crack and see if the light enables/disables when you would expect it to.

filliph

Indigo There is no light, on or off, for XDebug. I'm on Beta 9 (94).

That being said, I don't think this would be a big problem for me personally since I can always override the nginx.conf file, as I don't need XDebug support for Apache.

Indigo

Strange it simply doesn't work for you. Regardless, sadly I'm going to have to back out from my idea — the current implementation relies on polling the Xdebug port, which I intended to replace with a non-polling solution. Unfortunately it turns out that's not really possible with TCP connections, and I'm not willing to use polling long-term. I guess there's a reason automatic Xdebug-enabling has never been done before 🙂

I will be implementing a variation of your suggestion above, where Xdebug is enabled using either a cookie or an environment variable (for command-line debugging). This is also officially the recommended way... not that I doubted you 🙂 Thanks for your input!

fmitchell

For those who come here and want basic instructions for setting up PHPStorm (version 2021.3.3) and XDebug:

Go to Preferences > PHP
Pick your PHP version that matches your stack for PHP language level (optional)
Click the ellipsis near the CLI Interpreter
Click the + sign > 'Other local...' for the interepreter
Copy and paste the path to your stack's php executable, i.e. /Users/fredric/.indigo/stacks/STACK_ID/php_XXXX/bin/php > Save
Set a breakpoint and turn on your listener
Reload your page and it should work

Indigo

@fmitchell thanks for those instructions! Would you mind me putting that in the Indigo docs?

fmitchell

Yes, of course.

Indigo

Indigo 1.0.0-beta.10 has just been released which configures Xdebug to enable only when a cookie or environment variable is set. See https://xdebug.org/docs/step_debug#browser-extensions for details.