Xdebug and Sublime Text

Published by Lennart Van Vaerenbergh on May 5, 2015

This blog post is about making Xdebug work together with Sublime Text (in this example version 2). By many considered a tough task. But it's doable. Your IDE will look something like this:

A couple of assumptions made before continuing:
  • ​Sublime Text 2 or higher is installed.
  • Xdebug is installed and working. (Check your info.php and look for Xdebug, you should find configuration. Also, when generating errors in your browser, you should get these nice orange error messages containing a function stack.)

Step 1: Install Sublime Text plugin

Install the xdebug client package for Sublime Text using the Sublime Text Package Control (which, if you don't have it already, should also be installed). We'll be using the one of Martomo called SublimeTextXdebug.
In Sublime, go to Preferences > Package Control and type in 'Install Package'. When the repositories are loaded, type in 'xdebug' and choose 'Xdebug Client':

The installation of the plugin in Sublime is done. You should now be able to set breakpoints in your files by right clicking > Xdebug > Add/Remove breakpoint. Starting an actual debugging session we'll do in step 4.

Step 2: Configure Xdebug

Xdebug may be installed, but perhaps isn't configured correctly yet. That's what we'll do now. View your PHP info and locate the xdebug ini file.

Open this file and make sure following configuration is added (leave the zend_extension as is, this depends on your installation):





Step 3: Install an Xdebug helper addon in your browser

Sublime knows when to listen to your browser when a certain cookie is set. For sublime this cookie is "XDEBUG_SESSION = sublime.xdebug".
To avoid setting this cookie by hand, we can add a helper addon in our browser so we can enable and disable Xdebug whenever we want. I'm using Chrome, so here is the addon we can use for doing this: Xdebug Helper.
When installed, go to your Chrome Preferences > Extensions > Xdebug Helper Options and configure the addon:

Now you're able to enable or disable Xdebug from within your browser, as explained in the addon.

Step 4: Start a debugging session

The configuration is done and we should be able to start debugging now. In one of your files, place a breakpoint at certain line by clicking right > Xdebug > Add/Remove Breakpoint. At this point, the website will freeze and all available variables will be exposed in the debugging windows on the bottom of Sublime. You can set multiple breakpoints and step through them one by one.

To start the session, go to Tools > Xdebug > Start Debugging. Now the debugging layout appears in Sublime.

Go to Chrome, click on the Xdebug Helper icon and click on Debug. Reload the page you want to debug and it should freeze (keeps loading). In Sublime, you should see the active breakpoint (the first it encounters) and variable information in the tab Xdebug Context. To move to the next breakpoint, right click in your document > Xdebug > Run. Now the next breakpoint should be active (this could also be the same breakpoint, when your program calls it multiple times).

Debugging time!

Help, my debugging layout is messed up in Sublime

I encountered this annoying thing that my Xdebug views (the tabs in Sublime) were not positioned correctly in the lower areas of Sublime. When a debugging session is started, Sublime takes on a new layout with 2 lower areas where the debugging windows are positioned. In my case, the debugging windows appeared but the tabs were still loading in the main window.
To fix this, do the following:
In Sublime, click on Tools > Xdebug > Settings - User and paste the following:
  // Window layout that is being used when debugging.
  "debug_layout" : {
      "cols": [0.0, 0.5, 1.0],
      "rows": [0.0, 0.7, 1.0],
      "cells": [[0, 0, 2, 1], [0, 1, 1, 2], [1, 1, 2, 2]]

  // Group and index positions for debug views.
  "breakpoint_group": 2,
  "breakpoint_index": 1,
  "context_group": 1,
  "context_index": 0,
  "stack_group": 2,
  "stack_index": 0,
  "watch_group": 1,
  "watch_index": 1,

  "super_globals": true,
  "close_on_stop": true
This is also defined in the Default settings of Xdebug in Sublime, but for some reason not completely loaded when debugging.

We're done!



Submitted by Ray Gabriel on Tuesday, July 21, 2015 - 03:17
Thank you for your last tip! (Help, my debugging layout is messed up in Sublime section). It works. :)  
Submitted by Mark Kindred on Wednesday, November 11, 2015 - 01:18
Thanks for the help!
Submitted by UniFreak on Saturday, November 21, 2015 - 04:21
I originally followed this[http://www.sitepoint.com/debugging-xdebug-sublime-text-3/] tutorial, but it couldn't get the xdebug work. now after reading your post I've got the xdebug run sucessfully. Seems the author in sitepoint forgot to mention the xdebug helper. Or without xdebug helper, xdebug client can really work?
Submitted by Sanjaya on Wednesday, December 09, 2015 - 09:43
Great..Thanxx.Good post :) :)
Submitted by simon kerr on Thursday, January 07, 2016 - 09:49
yes. that worked, thanks a lot, good on yer
Submitted by Hilarudeen Sheik Allaudeen on Saturday, January 30, 2016 - 09:53
Thanks much helpful. You saved my life from traditional print/echo.
Submitted by Joe on Thursday, February 11, 2016 - 02:23
Thanks for taking the time to post this!  I'm not sure if I ever would've gotten this working otherwise.
Submitted by Rich on Thursday, March 17, 2016 - 03:03
Debug PHP with Visual Studio Code (FOSS) & Sublime Text http://chensformers.com/2016/03/13/visual-studio-code-foss-in-osx/
Submitted by Miltan on Saturday, April 16, 2016 - 12:10
Hi, My code repository and lampp server in connected via LAN. How can I configure xdebug, so that I can code from my local machine and debug in server ? FYI the code-files are shared via samba sharing and acting as windows network drive. Running Ubuntu 14.04 in dev server and xampp is running on top of that.
Submitted by Gregor on Tuesday, June 14, 2016 - 20:46
That works like a charme. Thanks!
Submitted by Luciano on Wednesday, September 07, 2016 - 18:29
Thanks man! finally it worked! 
Submitted by Jon on Friday, September 23, 2016 - 20:54
Thanks so much! I was going crazy until I read this article!
Submitted by Stanislav on Monday, September 26, 2016 - 18:37
I prefer to use Codelobster to debug PHP code: http://www.codelobster.com
Submitted by Jan on Sunday, January 22, 2017 - 09:59
Thanks heaps for sharing, you saved my day :)
Submitted by Daniel on Thursday, September 21, 2017 - 12:38
Superb! Thanks a lot for the help. Much appreciated!

Add new comment

(If you're a human, don't change the following field)
Your first name.
(If you're a human, don't change the following field)
Your first name.
This challenge is for testing whether or not you are a human visitor and to prevent automated spam submissions.