On this page
Xdebug is a real-time debugger extension for PHP. While usually used for local development, it can also be helpful for debugging aberrant behavior on the server.
As configured on Platform.sh, it avoids any runtime overhead for non-debug requests, even in production, and only allows connections via SSH tunnels to avoid any security issues.
Note that Xdebug runs only on your app containers. So you can’t use it for worker containers.
Also, note that if you use a custom start command, Xdebug is automatically disabled.
The following table shows the PHP versions where Xdebug is available on Grid environments:
You also need:
- The Platform.sh CLI
- A Xdebug-compatible IDE installed on your machine. For setup instructions, consult your IDE’s Xdebug documentation, such as that for PHPStorm.
Xdebug runs as a second PHP-FPM process used only for debugging requests, leaving the normal process unaffected.
To enable Xdebug, add the following to your app configuration:
YOUR_KEY can be any arbitrary alphanumeric string.
When that key is defined, Platform.sh starts a second PHP-FPM process on the container that’s identically configured but also has Xdebug enabled. Only incoming requests that have an Xdebug cookie or query parameter set are forwarded to the debug PHP-FPM process. All other requests are directed to the normal PHP-FPM process and thus have no performance impact.
If you have enabled the router cache,
you need to explicitly add the Xdebug cookie (
XDEBUG_SESSION) to the cookie allowlist.
Depending on the cookies already listed, the result should look similar to the following:
cookies: ['/^SS?ESS/', 'XDEBUG_SESSION']
To open an SSH tunnel to the server from a local checkout of your app, run the following CLI command :
That SSH tunnel allows your IDE and the server to communicate debug information securely.
By default, Xdebug operates on port
Generally, it’s best to configure your IDE to use that port.
To use an alternate port, use the
To close the tunnel and terminate the debug connection, press Ctrl + C.
On Dedicated Gen 3
Note that because you have several virtual machines running but your tunnel is connected to only one of them, your requests don’t always reach the same host.
While Xdebug can be triggered from the browser by adding a special query parameter, the preferred way is to use a browser plugin helper. Helpers are available for Firefox and Chrome. Their respective plugin pages document how to trigger them when needed.
Follow the instructions for your IDE, such as those for PHPStorm.
The common steps for setup usually include:
- Configuring the Xdebug debug port and making sure it’s set to the expected value (
9003as default or the value you chose with
--portwhen opening the tunnel).
- Making sure that external connections are allowed.
- Adding a new server for your Platform.sh environment.
The Host should be the hostname of the environment on Platform.sh you are debugging.
The Port should always be
443and the Debugger set to
- Ensuring path mappings is enabled.
This lets you define what remote paths on the server correspond to what path on your local machine.
In the majority of cases you can just define your app root
to map to
- Listening for connections.
- Starting debugging. While in listen mode, start the
platform xdebugtunnel. Use the Xdebug helper plugin for your browser to enable debugging. Set a break point in your app, then load a page in your browser. The request should pause at the break point and allow you to examine the running app.
Learn more about how to set up Xdebug on Dedicated server clusters.