dockervisual-studio-codexdebugxdebug-3gitpod

Xdebug 3 on GitPod with Apache


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.


Solution

  • 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