Skip to content

XDebug

XDebug is available on Stratus for debugging your store. While a powerful tool, it can drastically slow down your store if used in production. Even when its not actively tracing or profiling anything!

XDebug has a variety of settings. By default we set up XDebug to cover most situations for you. There are three ways to use Xdebug:

  • Profiling - outputs cachegrind files on the Stratus file system for you to evaluate request performance
  • Tracing - outputs trace files on the file system with full output of all function calls with function processing times
  • Debug - connect your local IDE via SSH tunnel on Stratus to step through code when called via browser request

Setup

We highly recommend using this Chrome extension to trigger the profiling and tracing in XDebug XDebug Helper

Before XDebug can be used, it must be enabled under the PHP section of your Stratus Management panel. There is a separate XDebug sub-section.

If Varnish is running, disable it.

You will see a configuration area like this:

config-75

Before enabling Xdebug, set a trace and profiler value, along with your IDE key. The IDE key is not strictly necessary on Stratus. The trace and profiler values will be used by the XDebug helper extension to trigger cachegrind or tracefile generation.

Once you have set the profile values, click Update. Your site will go down for a minute or two while PHP is reloaded with XDebug enabled. If you also had Blackfire enabled, you will get a warning. Blackfire and XDebug cannot and should not be enabled at the same time.

XDebug is now enabled and ready for use. If you installed XDebug Helper, edit the option fors the extension to match what you set in your Stratus panel.

helper-75

Tracing and Profiling

With XDebug helper, click the debug icon and choose either Profile or Trace from the available modes. Then load any page on your site you want to diagnose.

After a longer than normal page load, check the filesystem on your Stratus instance. There will be a directory called xdebug in /srv/

Depending on which option you chose in the XDebug helper, you will see either a cachegrind.out.(xxxx) file or a trace.(xxxx).(xxxx).xt file. Cachegrind files can be viewed with tools like KCacheGrind or WinCacheGrind. They are profiles of the page request. The .xt files are raw text showing the series of function calls made in the web request.

Remote Debugging with Breakpoints

Note the examples below use PHP Storm and VS Code, both common IDEs. If you are using something else, likely the settings here will be similar for you. There may also be other plugins and settings you can use in either IDE to your taste.

VS Code

Setup:

  • Have VS Code installed
  • Install the PHP Debug Plugin
  • Open VS Code to a copy of your Magento site code

Now configure the PHP Debug Plugin, this simple snippet should be in your launch.json file:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "port": 9000,
            "pathMappings": {
                "/srv/public_html/pub/": "${workspaceRoot}",
              }
        }
    ]
}

Change the path mapping to suit. Now add a breakpoint somewhere in your code. Presumably on code you know will be executed on your request.

Before you can use this, you need an SSH tunnel to pass the XDebug information from the Stratus instance to the local listener. Open a tunnel to your instance with these parameters:

ssh -p <stratus_port> <username>@<hostname> -R :9001:127.0.0.1:9000

Click the bug Icon in VS Code to Debug and Run, you should see an option to Listen for XDebug.

debug-75

Now request some page on your site for debugging, with a link like:

https://yoursite.com/test.php?XDEBUG_SESSION_START=1

The query string will trigger XDebug to begin debugging, you should see output appear in the variables column to the left side in XDebug. You can use the VS Code debug interface to continue stepping through your code.

PhpStorm

The JetBrains IDE costs money and is very powerful. But setup is a breeze. Similar to VS Code, an SSH tunnel is still required. Follow these steps.

  • Have PhpStorm installed and open
  • Open your code base in PhpStorm

Now press Ctrl+Alt+S to open the PhpStorm settings menu. Navigate to Languages and Frameworks -> PHP -> Debug.

settings-75

Set the XDebug section as shown above. Now open an SSH tunnel to your Stratus instance.

ssh -p <stratus_port> <username>@<hostname> -R :9001:127.0.0.1:9000

In your Magento code base/project, set breakpoints in PhpStorm. Then enable the XDebug listener via the Phone icon in the top right of the editor, or in the Settings menu under the Debug settings of PHP there is a link that says Start Listening.

Now request some page on your site for debugging, with a link like:

` https://yoursite.com/test.php?XDEBUG_SESSION_START=1

You should get a prompt to start debugging in a separate pop-up window within PhpStorm. Say yes and happy debugging!