Using PHP xdebug in a Docker with Netbeans
Tags: docker, xdebug, netbeans, php
Published: 2020-10-04 15:38:11

There are quite some guides around to connect xdebug-docker to PHPStorm, or xdebug to netbeans... but not a lot regarding xdebug-docker and netbeans. After struggling I managed to find a way. Here is how.

# Configuring docker

The Docker image must have xdebug installed. I use the following lines to do so:

```
FROM php:7.4-cli
[...]

RUN pecl channel-update pecl.php.net && pecl install xdebug-2.8.1 \
    && docker-php-ext-enable xdebug
```

# Running the image

After building you docker image (above is just an extract, you may need many other things for your project), here is how I run it. And here is where I struggled most...

```
docker run \
  --name=project_name \
  -v /home/me/dev/project/xdebug.ini:/usr/local/etc/php/conf.d/xdebug.ini \
  -v /home/me/dev/project:/home/me/dev/project \
  --rm \
  --env XDEBUG_CONFIG=\"idekey=my-ide-key\" \
  --network=host \
  -ti my-docker-img bash
```

The first `-v` option is copying a local xdebug.ini file inside the docker, at a location it will be read by PHP. From my image inherited from `FROM php:7.4-cli`, I know the folder `/usr/local/etc/php/conf.d/xdebug.ini` will do.

This is a flexible way to play with parameters in your docker PHP config. Expect this will not work from the first time...

In my case this `xdebug.ini` file contains:
```
xdebug.remote_enable=on
xdebug.remote_autostart=off
xdebug.remote_host=127.0.0.1
xdebug.remote_log="/tmp/xdebug.log"
xdebug.idekey="my-ide-key"
xdebug.remote_port=9123
```

These are the required minimal configuration. I highly suggest to use a `remote_log` parameter, because if it fails, it's where you'll have valuable data.

The `idekey` will be used in Netbeans as well as the remote port.

The line `-v /home/me/dev/project:/home/me/dev/project` is also very important. Your project file names and directories inside your container must **be the same as your host architecture**. If not, Netbeans will stop but will be unable to show you the actual line.

The line `--env XDEBUG_CONFIG=\"idekey=my-ide-key\"` is kind of duplicate of the `xdebug.ini` configuration `xdebug.idekey="my-ide-key"`... This parameter needs (also?) to be an environment variable, so don't forget it.

The line `--network=host` is also very important. It means that the `xdebug.remote_host=127.0.0.1` will also be the host IP. Otherwise, xdebug will be stuck inside your docker and unable to talk to the Host, where Netbeans sits.

In your docker, check your xdebug parameters are properly set by using the command `php -i | grep xdebug`. You will see such an output, reflecting your configuration (and the configuration used the next time you use the `php` command):

```
...
xdebug.remote_enable => On => On
xdebug.remote_handler => dbgp => dbgp
xdebug.remote_host => 127.0.0.1 => 127.0.0.1
xdebug.remote_log => /tmp/xdebug.log => /tmp/xdebug.log
xdebug.remote_log_level => 7 => 7
xdebug.remote_mode => req => req
...
```

If it looks OK, carry on, otherwise fix your config first.

# Configuring Netbeans

This is the easier part. Go to Tools | Options | PHP | Debugging.

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/a7grq881c5e01y6wg5ux.png)

Make these parameters match the `xdebug.ini` config in your docker, as visible on the picture (fields `Debugger Port` and `Session ID`)

# Launching your debugging session

In Netbeans, click on the following icon (or ctrl+F5):

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/slm0zmdz1z0jmvkm1zej.png)

Place a breakpoint somewhere in your application, as early as possible (or use the `Stop at first line` option provided by Netbeans, as visible in the screenshot above).

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/4fq5vaft38k9qbn97d60.png)

*breakpoint (red square) set at line 63 here*

In your docker launch a PHP command, like `php bin/phpunit`.

The command will stop, and Netbeans will be stop at the required line. BINGO!

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/67mulobmf12yejhr55nz.png)

*The debugger stopped here (green arrow)*

# Basic debugger use

The most useful commands to me are the following one (step into, go to next instruction etc.)

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/mog3mjbvcqysp8duvvi7.png)

And the Variables and Call Stack panels. You can display them from the Window | Debugging menu if they don't show up automatically.

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/jqtrs6wbz1i9fm6a1rht.png)

# Troubleshooting

## Make sure your configuration is active

`php -i | grep xdebug` is a good start. If you don't run your project with the `php` command, be sure (by displaying a `phpinfo()` for example) that the xdebug.ini is applied, e.g. in a place which is considered by your PHP executable.

## Read the logs

If you copied my documentation, there should be a logging file, inside your docker, at the location: `/tmp/xdebug.log`. Read that!

## Check the xdebug.ini parameters match the Netbeans ones.

I am sure you checked it 10 times but who knows...