Xdebug 3 on GitPod with Apache

Question

I am trying to get Xdebug 3 to run on GitPod with Apache. Installation works well, also "Launch on currently open script".

The challenge is to connect Xdebug to the debug client. That seems to fail if one is just using xdebug.client_host = localhost, because of the Docker environment. Normally one would use xdebug.client_host = host.docker.internal, but simply declaring that does not work on GitPod.

• LazyOne: "The challenge is to connect Xdebug to the webserver." What do you mean here? I believe you need to RTM on what Xdebug is and how it works. Just in case: 1) Xdebug is PHP extension. So it's already "connected to the website" since it is loaded together with other PHP extensions (if installed and configured ofc)
• LazyOne: 2) It's Xdebug that connects to debug client (VSCode in your case) and NOT other way around. That's why I think that this - port: 9003 line is not needed (as I understand it opens port from container so it can be reached from the host OS). That's why xdebug.client_host = localhost would also not good here (at least not for traditional Docker where you would normally use xdebug.client_host = host.docker.internal). Not sure what needs to be used for GitPod (do not really know how it actually works)... but Xdebug must be able to connect to your debug client/VSCode.
• LazyOne: 3) I'm sure that in your research you must have checked a lot of links. But just in case: does this one provide any help? gitpod.io/docs/introduction/languages/…
• Sina: @LazyOne Thanks, updated the question. Indeed, ````xdebug.client_host = host.docker.internal`` is a likely solution in the Ubuntu docker environment of GitPod. I think github.com/tmy2017/php-ddd-cargo-sample/commit/… shows some solution via docker run --add-host host.docker.internal:host-gateway but I don't know how to implement this in my use case?

Answer 1

With help on the Gitpod Discord, here is the solution. It is implemented in the repo on Github.

No changes or pathmappings in VScode needed. Default launch.json works.

Xdebug settings for "Listen to Xd" to be copied to Apache (e.g. /etc/php/8.2/apache2/conf.d/99-custom.ini)

xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.discover_client_host=1

Xdebug settings for CLI to be copied (e.g. /etc/php/8.2/cli/conf.d/)

xdebug.mode = off
xdebug.start_with_request = yes

Docker caches the copy commands and this can lead to a lot of confusion when debugging. So I moved them to the .gitpod.yml, which also initializes the ports and installs the php-debug extension for VScode.

image:
 file: .gitpod.dockerfile
 context: .env
 
ports:
- port: 8080
 onOpen: open-preview
- port: 9003
 onOpen: ignore
tasks:
- name: Apache
 init: >
 sudo cp .env/xdebug_cli.ini /etc/php/8.2/cli/conf.d/99-custom.ini &&
 sudo cp .env/xdebug_web.ini /etc/php/8.2/apache2/conf.d/99-custom.ini
 command: >
 apachectl start &&
 multitail /var/log/apache2/access.log -I /var/log/apache2/error.log
vscode:
 extensions:
 - felixfbecker.php-debug

• VonC: Good catch. Upvoted. That does directly address Xdebug settings and avoids potential permission issues by not altering Docker daemon configurations.