Skip to content

XDebug (Personal)

Jump to bottom
Matt Poole edited this page Jul 16, 2024 · 6 revisions

IDE Configuration

Before you can use Xdebug, you must configure your IDE.

PhpStorm

The environment ships with a shared PHP Remote Debug server. It can be found at .run/appserver.run.xml. But, before you can use it, you must configure a 'server' for it to connect to. Luckily, Drupal Env ships with a command to add this server:

./robo.sh xdebug:phpstorm-debug-config

I recommend running this while the IDE is closed. If you don't, restart the IDE afterwards. Then confirm that your IDE has the following setup:

image

image

Click the 3 little dots next to appserver to see the server configuration.

image

Your project root MUST be mapped to /app inside of the remote server (Lando).

VSCode

The configuration for VSCode should be in the .vscode/launch.json. There should be no other configuration.

Running the debugger

How to debug inside your IDE is outside the scope of this.

Enable the Xdebug PHP Module

Now you that your IDE is configured to run Xdebug, we have to get the environment ready. The Lando environment comes with Xdebug disabled completely.

To turn on (enable the xdebug PHP module, not start debugging) the extension there are two options:

  • lando xdebug-on: Turns on Xdebug temporarily until lando rebuild or lando destroy. In the same vein, you can turn off Xdebug again with lando xdebug-off.
  • lando:xdebug-toggle-on-by-default: Turns on Xdebug on until the command is run again.

Start Debugging

As long as any of the options below are set, your IDE must be listening to for Xdebug requests for the debugger to start. Please see your IDEs documentation on how to do this.

Start via URL / Cookie

Appending ?XDEBUG_SESSION, ?XDEBUG_TRIGGER, or ?XDEBUG_SESSION_START to the URL will cause Xdebug to connect to your IDE for just that request. Appending ?XDEBUG_SESSIONS_START=somevalue to the URL will cause Xdebug to connect to your IDE until the session cookie (XDEBUG_SESSION) is deleted or ?XDEBUG_SESSION_STOP is appended to the URL instead.

Start for every request

This is useful for debugging CLI (Drush) requests or if you want to have zero steps besides start listening for your requests in your IDE to start Xdebug.

./robo.sh lando:xdebug-toggle-always-connect This command sets XDEBUG_SESSION=1 as an environment variable inside of Lando. Reminder: If you turned on Xdebug via lando xdebug-on, you'll need to run that again since the above command rebuilds Lando.

Warning: You will see "Step Debug" warnings about Xdebug not being able to connect when running CLI commands if you IDE is not listening. If you want to have Xdebug always connecting AND this warnings get too annoying, you can comment out log_level in lando-config/php.ini. This is a shared configuration for the local, not a personal configuration. You must lando rebuild for this to take effect.

Troubleshoot

There 2 minimum things that are required to make Xdebug work:

  • The Xdebug PHP module must be enabled, confirm with lando ssh -c 'php -m | grep xdebug'. It should print 'xdebug'
    • If not see 'Enabling Xdebug' section above.
  • Your IDE must be listening for Xdebug connections. See the 'Configure Xdebug for X' sections. lando drush eval 'print_r(getenv());' | grep XDEBUG_SESSION

Once those are in place, you now have to make sure Xdebug is trying to connect to your IDE.

Clone this wiki locally