How to configure XDebug for Magento 2 development

Before we dive into Magento 2 itself, I want to make our lives a little bit easier by setting up xDebug. It’s always a great idea to have debugger while you’re learning a new platform. Now, although it may be a very tricky task, I promise it’s going to be incredibly easy in this case. We will cover two most popular editors at the moment: Sublime Text and PhpStorm.


Since this is a follow up on the previous post, make sure that you have Magento 2 box up and running.

Sublime Text (2/3) lovers

1. Install Package Control

If you haven’t already, you need to install Package Control, a package manager for Sublime, that includes a list of over 2,500 packages available for install. You can find very clear and easy to follow instructions on their site.

2. Install XDebug plugin

  1. Start Sublime Text editor
  2. Open up Command Pallete (Ctrl+Shift+P Windows/Linux;  Cmd+Shift+P Mac OS users)
  3. Start typing install. Press Enter when Package Control: Install Package appears
  4. Type XDebug and choose XDebug Client

Once it’s done, you’ll have a new menu item Xdebug under Tools.


3. Saving the project

With this in place, it’s still not done – we need to add some configuration:

  1. Open Magento 2 folder in Sublime Text (as it is shown on the screenshot above)
  2. Go to Project->Save Project As and save it within the root of your application as mage2.sublime-project.


4. Configuring XDebug plugin

The final step is to copy and paste the following code into mage2.sublime-project file:

			"follow_symlinks": true,
			"path": "."
    "settings": {
        "xdebug": {
             "url": "",
                "path_mapping": {"/var/www/html/mage2/" : "/Users/mstojanov/Downloads/mage2-macos-linux/mage2/"}        

Of course, replace path_mapping part:


to match the path to Magento 2 folder on your local system.

5. Set breakpoints

We can add a breakpoint by clicking with our right mouse on a line, going to Xdebug and then clicking on Add/remove Breakpoint.


6. Debug

When you have at least one breakpoint set, you can go to Tools->XDebug->Start Debugging (Launch Browser) and have fun:


PHP Storm lovers

With PhpStorm, it is even easier to set up everything since it has native Xdebug integration.

1. Open Magento 2 project

  1. Open up a project
  2. Go to Preferences
  3. Search for servers in the popup’s upper left search field
  4. Click on Servers under PHP, as shown on the screenshot above


2. Set it up

When you are done with the previous step, you will get a window on the right, which will look like this (with values already set):


So, this is step by step what you need to do:

  1. Click the + button at the top of the PHP->Servers pane
  2. Give it a random name (Mage 2 in my case)
  3. Host is
  4. Tick Use path mappings
  5. File/Directory column represents web root of your project on your machine
  6. Absolute path on the server should be the same: /var/www/html/mage2
  7. Press OK to save the settings (not visible on the screenshot, I apologize)

3. Start listening for remote PHP connections

Make sure that you have this little thing in the top right corner of PhpStorm the same as on the following screen:


4. Set breakpoints

This is as simple as clicking in our gutter on the left:


5. Finally, run the application

With a breakpoint (or a couple of them) set, the very last thing that you need to do is to run the application in the browser. Code execution will pause at your first breakpoint and allow you to step through the code as you please.


Milan Stojanov is a certified Magento developer and Tuts+ author on Magento Fundamentals premium course. He likes to read and write about web development.

  • clod

    I prefer to use Codelobster to debug Magento projects:

  • G.

    I have setup everything like described above (PHPStorm10). When I try to load Magento in my browser, it just takes ages for the request to complete and I don’t see any response within PHPStorm. Do you have an idea what the problem could be?

  • I can’t make it work. Could you please help?

  • dissaa

    Ii can’t make work in sublime. Did all but i don’t have the Tools->XDebug->Start Debugging (Launch Browser) option, only Tools->XDebug->Start Debugging…