Debugging with Xdebug and Sublime Text 3

Debugging – we all do it a lot. Writing code perfectly the first time around is hard and only a few (if any) succeed at it. More than a year ago, Shameer wrote an article on SitePoint about how you can debug your application using Xdebug and Netbeans. In this article, we are going to have a look at how we can debug using Xdebug in combination with Sublime Text.

Getting started

First of all, we need to have the PHP Xdebug extension installed. If you are uncertain on how to get this done, please have a look at the link provided in the introduction. Make sure that Xdebug is working by checking if it’s listed in your phpinfo().
Of course we also need Sublime Text. I will be using the latest version: Sublime Text 3. It should also work with Sublime Text 2.

Setting up Xdebug

We need to configure xdebug by adding the following to your php.ini file, or even better, to an xdebug.ini file as described here under How-to On Linux.

xdebug.remote_enable=1
xdebug.remote_handler=dbgp
xdebug.remote_host=127.0.0.1
xdebug.remote_port=9000
xdebug.remote_log="/var/log/xdebug/xdebug.log"

In general you will be using 127.0.0.1 as your host. However, If you are using vagrant for example, you will be using something like 10.0.2.2, depending on where Xdebug can find your system.

The remote log is not necessary, but in case of problems, it’s the place where you can find information about errors that occurred.

Don’t forget to restart your webserver!

Setting up Sublime Text 3

One of the strengths of Sublime is the fact that you can extend it easily with packages. In this case, we are going to install the Xdebug package. If you haven’t done so already, make sure you can install packages by installing package control.

Once you have the package control installed, you should start Sublime Text 3. Open up the command palette from the tools menu and search for “install package”.

Now you can search for any package you like. In our case, we are going to search for the package “Xdebug client”.

The last bit we have to do is set up the project within Sublime. The easiest way to do this is to open up the root directory of your application, go to projects and click on “save projects as”. I suggest you save the file within the root of your application, so you can save it in your version control system if you are using any and you can configure it easily at all times.

Open up the just created project file. The content will look like this:

{
    "folders":
    [
        {
           "follow_symlinks": true,
           "path": "."
        }
    ]
}

We are going to add a few more lines:

{
    "folders":
    [
        {
            "follow_symlinks": true,
            "path": "."
        }
    ],
    "settings": {
        "xdebug": {
             "url": "http://my.local.website/",
        }
    }
}

As you can see, I only added a URL to my actual web application. I could set more settings for Xdebug, however, this is enough to start with. I could have also set this URL in the Xdebug settings itself, but in that case, I couldn’t work on multiple projects without having to change the Xdebug config each time.

Start the Xdebug session

We can now start the Xdebug session to see if everything is set up properly. In the menu, click on tools -> Xdebug and click on start debugging (launch browser). You will notice that your website is opened up and that ?XDEBUG_SESSION_START=sublime.xdebug is added to the end of the URL. This will start the xdebug session. In Sublime, some extra panels appear where debug information will be shown, after you have set one or more breakpoints.

Breakpoints

Let’s set out first breakpoint. A breakpoint is basically a flag where your application will halt when it reaches it. At the moment it halts, you can inspect all the variables’ values so you know actually what is going on.

We can add a breakpoint by clicking with our right mouse on a line, going to Xdebug and then clicking on add/remove breakpoint. A marker will be added to the line gutter to indicate that a breakpoint has been set.

We open up our browser again and continue with the session we just started. You will notice that as soon as you go to the page where the breakpoint is, the page will stop loading. If you now open up Sublime, you will see a lot of information shown in the Xdebug panels.

The Xdebug stack and Xdebug context are very interesting. In the stack, you can see the whole stacktrace your call went through.

In the context, you will see all global variables, but also the variables you defined yourself. You can click on these variables to see exactly these variables are holding. For instance, in the screenshot below, I clicked on the $_SERVER variable.

Notice that a yellow arrow is pointing at the line the application is currently halted on.

So our application halted and now we can look through the variables defined. However, we are done and we want to move on. What now? When you right mouse click once again and hover over the Xdebug menu, you will have several options:

  • Run Which will run the application until the next breakpoint or until the ending.
  • Run to line which will run until the line you clicked.
  • Step into will step into the current function and stops right after.
  • Step over Will step over the current function and stops right after.
  • Step out Will step out of the current function and stop right after.
  • Stop Will stop debugging.
  • Detach Will also stop debugging.

Run and stop are quite easy to understand. The step methods could be a little confusing. Let’s dive into these with a simple example.

Class Foo() 
{

    public function bar(Array $arr)
    {
        $arr = self::fooBar($arr); // Breakpoint
        return $arr;
    }

    public function fooBar(Array $arr)
    {
        return array_values($arr);
    }
}

Imagine you added a breakpoint to the first line of the method bar. So on the line with the breakpoint comment (// breakpoint).

With step into, the debugger will step into the fooBar method and will stop there at the first line. So in this case, the debugger will halt on the return array_values($arr); line.

Step over will call the method, but will not stop. It will stop at the next line available after calling the method. So in this case, it will stop at return $arr;

Lastly, with step out it will run through the whole bar method and return to the caller. In this case, it will go out of the object, back to the original caller.

If you just decide to run, the application will run further until the moment it is done executing or another breakpoint occurs.

Conclusion

In this article we saw how we could integrate Xdebug with Sublime and made sure we understood how to debug. Almost every IDE suitable for PHP can integrate with Xdebug. If you are interested in debugging like this in Netbeans, have a look at the article mentioned in the introduction. Are you using breakpoints? Or are you using PHP functions like var_dump to get your debug data? Let us know in the comments below!

Free book: Jump Start HTML5 Basics

Grab a free copy of one our latest ebooks! Packed with hints and tips on HTML5's most powerful new features.

  • gafitescudaniel

    and if you add PHP CodeSniffer, PHP Coding Standard Fixer, Linter and Mess Detector Support for Sublime Text from https://github.com/benmatselby/sublime-phpcs it’s a done deal !

  • kreaton

    thank you so much! I managed to set up everything from the very first attempt! My question is: is there a possibility to control debugging (step into, step out, etc.) with hot keys? would be cool! rather than right clicking and navigating to the command each time you need to make a step

  • Michael

    I just tried to set this up with my VM, and found some issues. Here’s what helped me:

    In your xdebug.ini, it’s easier to set xdebug.remote_connect_back=1 than to set xdebug.remote_host (of course, only do this in your dev environment). Also, I needed to set xdebug.remote_autostart=1.

    Then, in order for breakpoints to be picked up, you need to map the files from your VM to your host machine. Add the following to your XDebug settings in the Sublime project file:
    “path_mapping”: {“/var/www/my-project/” : “/local/path/to/my-project/”}

    • Sp4cecat

      Yup, that part is absolutely key if you’re developing non-locally, ie either a local VM or on a remote machine. PHP Storm sorts this out for you, which is one of the many reasons I switched to it from Sublime.

  • http://severin-bruhat.com Séverin Bruhat

    I’ve just tried to set up this awesome package, but I can’t get it working. I’m working with SublimeText 3 on a Drupal project. I have tried to put a breakpoint in the index file on the “menu_execute_active_handler();” method. There is a ” |+| 21″ information in the Xdbug Breakpoint view. But then, when I launch the debug window, nothing append in the debug consol and the execution of the script doesn’t break… any idea ?

    • https://www.peternijssen.nl/ Peter Nijssen

      Did you check if there is any information in the xdebug log? Also, is this part appended to the url? “?XDEBUG_SESSION_START=sublime.xdebug”

      • http://severin-bruhat.com Séverin Bruhat

        There is no information in the log file, actually, there is no log file, I’m working in a windows environment (shame on me ^^) The URL contains XDEBUG_SESSION_START=sublime.xdebug

    • http://severin-bruhat.com Séverin Bruhat

      Problem solved, There was an error in my php.ini settings file. The path to xdebug was wrong, but I had no error in my logs….

    • http://louis.hatier.me/ Louis

      I’m having the same problem (ON ST2 + Debian).

      I changed the path of the remote_log to “/tmp/xdebug.log” but no file is being create,

      My phpinfo tells me that remote_enable is ON, the ST plugin seems to work fine, I can add breakdpoints, but when i load the page (with ?XDEBUG_SESSION_STOP=sublime.xdebug), nothing append in the other windows (context, watch, and stack).

      I think Xdebug works fine, when I dump variables I have the coloration, so I’m out of ideas !

  • rolandojones

    I just recently got started with Xdebug and this was very helpful, thanks!

  • http://severin-bruhat.com Séverin Bruhat

    I’m not sur that the problem is due to the log. I can’t find any error

  • Alabi

    Presently I use var_dump for debugging. Can anybody help with where I can get an article on xdebug + Aptana Studio 3.

  • Trenton Craig

    I’m having trouble getting this to work… I have ubuntu desktop VM, with ST3 installed there (instead of on my windows host). I know the /tmp/cachergrind* files are being created, but I do not see anything come up in the sublime text windows for xdebug… my settings:

    #xdebug
    zend_extension=”/usr/lib/php5/20090626/xdebug.so”
    xdebug.profiler_enable = 1
    xdebug.remote_enable = 1
    xdebug.remote_port = 9000
    xdebug.remote_handler = “dbgp”
    xdebug.remote_mode = req
    xdebug.remote_connect_back = 1
    xdebug.remote_autostart = 1

    My project settings file has the following section:

    “settings”: {
    “xdebug”: {
    “url”: “http://templates/”,
    “close_on_stop”: true
    }
    }

  • damko

    If someone wonders how to customize the xdebug client shortcuts I wrote something

    http://damko.info/blog/2014/04/customized-shortcuts-for-st3-xdebug-client-plugin

  • http://www.sixdayprogrammer.com Christopher Bier

    This is so crazy!!!

  • adamcole

    This doesn’t work for a remote server does it?

  • DasLicht

    delete me

  • kinah

    This comment is off topic but menu isn’t working on my samsung galaxy tab when on landscape mode.

  • Julien Dev

    Hi,
    When i want to debug a page that i get from a redirect it does not work. obviously because it’s a new request.
    Is there a way to tell xdebug (or the sublime plugin) to connect on each request ?

  • Ricardo

    is there a way to change the default browser in sublime or even inside this plugin? thank you!

    • https://www.peternijssen.nl/ Peter Nijssen

      I don’t know. According to the xdebug plugin, it starts the default browser.

  • http://www.dota2.it/ Drake

    Thank you, good article for an easy start.