PHP debugging - listening for webserver not working with example in docs

I have a development environment set up in Gitpod and I have copied the settings for PHP debugging from the documentation.

The launch.json example file there has only one configuration, which is for launching the debugger for the current script (in CLI mode?). That works fine, but when I try to add another configuration to listen for connections to the webserver (Apache) on port 9000, it doesn’t receive any.

When I run php -v in the Gitpod workspace environment I see that Xdebug is installed and enabled:

PHP 7.4.3 (cli) (built: Mar 26 2020 20:24:23) ( NTS )
Zend Engine v3.4.0, Copyright (c) Zend Technologies
    with Xdebug v2.9.1, Copyright (c) 2002-2020, by Derick Rethans
    with Zend OPcache v7.4.3, Copyright (c), by Zend Technologies

However, when I call the phpinfo() function on the webserver, Xdebug is missing and there are no xdebug settings entries:

PHP Version 7.4.3
Zend Engine v3.4.0, Copyright (c) Zend Technologies
    with Zend OPcache v7.4.3, Copyright (c), by Zend Technologies

Are there separate instances of PHP being used for the workspace and webserver? If so, where should I set up Xdebug for the webserver? And can we add an example of webserver listening to the PHP docs?

Other notes: Here’s the launch.json file I’m using, which is based on the one generated from the PHP Debug extension:

  "version": "0.2.0",
  "configurations": [
      "type": "php",
      "name": "Listen for XDebug",
      "request": "launch",
      "stopOnEntry": true
      "type": "php",
      "name": "Launch currently open script",
      "request": "launch",
      "stopOnEntry": true,
      "program": "${file}",
      "cwd": "${workspaceRoot}",
      "externalConsole": false

BTW, Gitpod is awesome! I just discovered it this week and I’d love to move my team to cloud-based dev environments.

Hi @bjornhansen, welcome to the Gitpod community! :tada:

And many thanks for your kind words, we’re glad that you find Gitpod useful!

Unfortunately I’m not too familiar with PHP development / debugging, but maybe I can still help you somehow. Here is what I know:

  • The PHP debugging example repo was developed by @JesterOrNot – Sean, would you happen to know how one can debug a PHP webserver (Apache) running on port 9000, as opposed to just the current PHP script/file?

  • Both the docs & the example repo seem to install Xdebug using some very specific paths. So I guess in order for PHP to pick up Xdebug, these paths need to be correct, and the amended config file /etc/php/7.4/cli/php.ini should be used (I have no idea whether Apache comes with its own PHP runtime, or if it starts PHP with a different configuration, but that could very well be the case)

  • @meysholdt has also worked on various PHP & Apache example repos before – Moritz, would you have any insights in how to run Apache’s PHP webserver in debug mode in Gitpod, so that the PHP Debug extension could potentially pick it up?

Thanks for the info, jan! I was able to figure it out without too much hassle.

There are at least two PHP runtimes in the gitpod/workspace-full image. The example repo uses /etc/php/7.4/cli/php.ini, which is the CLI runtime. The Apache server runtime is in /etc/php/7.4/apache2/php.ini and also needs to be configured for Xdebug. There may also be others for running PHP on Nginx, etc… I haven’t looked into that yet.

The solution was to duplicate the last command in the RUN block in the example repo Dockerfile and changing the path to the Apache runtime. This allows both “debug the current file via the CLI runtime” and “debug the running app”, which is super useful sometimes. My final Dockerfile ended up being:

RUN wget \
    && tar -xvzf xdebug-2.9.1.tgz \
    && cd xdebug-2.9.1 \
    && phpize \
    && ./configure \
    && make \
    && sudo mkdir -p /usr/lib/php/20190902 \
    && sudo cp modules/ /usr/lib/php/20190902 \
    && sudo bash -c "echo -e '\nzend_extension = /usr/lib/php/20190902/\n[XDebug]\nxdebug.remote_enable = 1\nxdebug.remote_autostart = 1\n' >> /etc/php/7.4/cli/php.ini" \
    && sudo bash -c "echo -e '\nzend_extension = /usr/lib/php/20190902/\n[XDebug]\nxdebug.remote_enable = 1\nxdebug.remote_autostart = 1\n' >> /etc/php/7.4/apache2/php.ini"

I’d be happy to make a pull request to the docs and/or example repo in case others are interested in this issue. Coming from PHPStorm, the second type of debugging (“debug the running app”) is the default and the current setup may be confusing for migrating users.