Skip to main content
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 Upsun, 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.

​
Before you begin

The following table shows the PHP versions where Xdebug is available (○). You also need:
  • The Upsun CLI
  • A Xdebug-compatible IDE installed on your machine. For setup instructions, consult your IDE’s Xdebug documentation, such as that for PHPStorm.

​
1. Set up Xdebug

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: can be any arbitrary alphanumeric string. When that key is defined, Upsun 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: Xdebug has several configuration options available. They can be set the same way as any other PHP setting. For a full list of available options, consult the Xdebug documentation.

​
2. Use Xdebug

​
Open a tunnel

To open an SSH tunnel to the server from a local checkout of your app, run the following CLI command : 
upsun environment:xdebug
That SSH tunnel allows your IDE and the server to communicate debug information securely. By default, Xdebug operates on port 9003. Generally, it’s best to configure your IDE to use that port. To use an alternate port, use the --port flag. To close the tunnel and terminate the debug connection, press Ctrl + C.

​
Install an Xdebug helper

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.

​
3. Configure your IDE

Follow the instructions for your IDE, such as those for PHPStorm. The common steps for setup usually include:
  1. Configuring the Xdebug debug port and making sure it’s set to the expected value (9003 as default or the value you chose with --port when opening the tunnel).
  2. Making sure that external connections are allowed.
  3. Adding a new server for your Upsun environment. The Host should be the hostname of the environment on Upsun you are debugging. The Port should always be 443 and the Debugger set to Xdebug.
  4. 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 myapp.
  5. Listening for connections.
  6. Starting debugging. While in listen mode, start the upsun xdebug tunnel. 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.
Last modified on March 11, 2026