Magento Tutorials

Debugging Magento with Xdebug using PhpStorm and Chrome

This tutorial shows you how to debug your code using PhpStorm and Google Chrome browser with Xdebug.

Configure PhpStorm to work with Xdebug

  1. Open PhpStorm Project > Settings panel
  • Windows: Select File > Settings.
  • Mac OS X: Select PhpStorm > Preferences.
  1. Expand Language & Frameworks > PHP 
  2. Set the CLI interpreters.
  3. Click Server then Add a new server configuration.

Configure as below: 

Name: localhost (Same as PHP_IDE_CONFIG in docker-compose.yml)

Host: localhost

Port: 80

  1. Tick the Use path mapping checkbox and add your mappings.
  2. Under the PHP node, click Debug.
  3. Set the Xdebug port to 9000(Xdebug 2). For Xdebug 3, set the port to 9003
  4. Click Apply

Create an SSH tunnel

Before you run Xdebug, you must create an SSH tunnel to the DevBox container. You can download Magento DevBox on Magento Tech Resource Download page.

On Windows

To use an SSH tunnel on Windows:

1. Start Putty.

2. In the Category pane, click Session.

3. In Hostname (or IP address) field: Enter the SSH URL for your Cloud server

In Port field: Enter 22


4. In the Category pane, click Connection > SSH > Tunnels.

5. Enter the following information:

Source port field: Enter 9000

Destination field: Enter

Click Remote

Click Add.

6. In the Category pane, click Session.

7. In the Saved Sessions field, enter a name for this SSH tunnel.

8. Click Save.

9. From the Saved Sessions list, click the name of your DevBox SSH session and click Load.

10. Click Open.

11. At the Login as prompt, enter magento2

On Mac OS

To create an SSH tunnel on Mac OS, open a Terminal window and enter the following command:

./<DevBox root folder>/

*If it shows an “unable to connect” or “could not listen to port on remote” error, there could be another active SSH session on the server that is occupying port 9000. If that connection isn’t being used, you can terminate it.

Use Xdebug in Chrome

  1. Install the Xdebug Helper extension.
  2. Enable the extension in Chrome.
    Enable the Xdebug extension in Chrome
  3. Open your DevBox PhpStorm project.
  4. In the top navigation bar, click
    Start listening for connections
    (Start listening). If the navigation bar isn’t displayed, click View > Navigation Bar.
  5. In the PhpStorm navigation pane, double-click the PHP file to test.
  6. In the right pane, in the gray area next to a line number, click to set a breakpoint.
  7. In Chrome, go to a URL that invokes the breakpoint.If Chrome is already displaying the URL, click Refresh in the Chrome toolbar.
    If the Incoming Connection from Xdebug dialog box displays, select the same file in which you set the breakpoint and click Accept.

A knowledge craver who always strive to be wiser everyday.