Debugging

The farmOS development Docker image comes pre-installed with XDebug 3, which allows debugger connections on port 9003.

XDebug can be configured to discover the client host automatically with the following extra_hosts and environment configuration in docker-compose.yml:

extra_hosts:
- host.docker.internal:host-gateway
environment:
  XDEBUG_MODE: debug
  XDEBUG_CONFIG: client_host=host.docker.internal

PHPStorm

If you are using the PHPStorm IDE, some additional environment variables are necessary:

XDEBUG_SESSION: PHPSTORM
PHP_IDE_CONFIG: serverName=localhost

For example:

extra_hosts:
- host.docker.internal:host-gateway
environment:
  XDEBUG_MODE: debug
  XDEBUG_CONFIG: client_host=host.docker.internal
  XDEBUG_SESSION: PHPSTORM
  PHP_IDE_CONFIG: serverName=localhost

With this configuration in place, enable the "Start listening for PHP Debug Connections" option. Add a breakpoint in your code, load the page in your browser, and you should see a prompt appear in PHPStorm that will begin the debugging session and pause execution at your breakpoint.

This also works with command-line scripts like drush. You may need to map the path to Drush (vendor/drush) in the PHPStorm debugger config.