Making bugs ex-bugs with Xdebug

Xdebug is an indispensable tool for every PHP developer. PHP's favorite real-time debugger, it supports breakpoints, more detailed debug output, and deeper introspection of PHP code to determine just what it's doing (and what it's doing wrong). Sadly, it comes at a huge cost in performance, though, making it unsuitable for production.

Turning it on

Xdebug is an extension, but it's not enabled the same as other extensions. Instead, you specify an idekey for Xdebug's configuration in your .platform.app.yaml file:

runtime:
  xdebug:
    idekey: PHPSTORM

That's all. Xdebug will now be enabled.

Fast and secure

Normally Xdebug has a huge negative impact on performance. It has to inject itself into every function call in an application, which adds up quickly. For that reason, it's generally a bad idea to run Xdebug in production. On Platform.sh, though, it's safe to do with almost no performance impact. How?

When you enable Xdebug on an environment, we start a second, parallel PHP-FPM process that is identical to the one serving normal requests, but with Xdebug added as well. Then, any incoming request that has the Xdebug trigger cookie or query parameter enabled will get routed to that Xdebug-enabled FPM process. Those that do not go to the normal PHP-FPM process and so incur no overhead.

Xdebug remote connections also have the potential of opening up security issues. They do allow direct inspection of a running application on a remote server, after all. For that reason, Platform.sh only supports remote debugging over an SSH tunnel from your local system. Only users with SSH access to the environment will be able to start a debug session.

You can easily start an SSH tunnel with the new platform xdebug command in the Platform.sh CLI.

The net result is that Xdebug on Platform.sh is fast, secure, and ready to roll.

IDE configuration

Different IDEs and developer tools have their own ways of connecting to Xdebug. Our Xdebug documentation includes instructions for the popular PHPStorm IDE, but Xdebug works with many code editors.

If you have a favorite editor that works with Xdebug on Platform.sh, pull requests for our public documentation are most welcome.

May all your bugs be X-bugs.