Development environments with VirtualBox, XDebug and VS Code

Submitted by Juan on Sun, 04/08/2018 - 23:34
Bug & VS Code

When I work on web development I rather prefer to use a VirtualBox machine running on a Linux environment than installing everything on my computer. I do it because of the following reasons:

  1. I avoid installing software directly on my workstation: I'm talking about services such as Apache, MySQL, Ruby when compiling Sass, Git, npm, etc.
  2. I find more comfortable to work with the command line tools of a Linux environment, especially when I'm working on a Windows box where the shell emulation tools are not good enough as a real Unix server.
  3. Generally speaking, the servers where the web projects are deployed in the real world are Unix-based architectures. In addition to the previous point, developing a project within an environment that resembles to the server where it's expected to be deployed results in a more transparent process.
  4. The fun stuff: if you make a mess and blow everything off while playing with your server, the problem will keep isolated and you don't have to worry about anything on your personal computer.

Ok, maybe I haven't found the Holy Grail of development environments but I have found lately very comfortable this method when working with PHP projects on Visual Studio Code and debugging them on XDebug, so here I share te recipe for anyone who could be interested on giving it a try.

First step: the server

I'm assuming that you have already a VirtualBox virtual machine with Ubuntu 16 with its LAMP architecture up and running. The following commands must be executed as root user or by passing the sudo command as you will be editing system files. The first thing to do is to install the XDebug library for PHP with the following command on your terminal:

apt-get install php-xdebug

Next you have to configure your newly added module. In this example I'm doing it with nano but of course you can use any editor you feel comfortable with as vim or anything else. Please be aware of the PHP version you're using (mine is 7.2) as this could change the location of your config files.

nano /etc/php/7.2/mods-available/xdebug.ini

There you have to add the following lines to get access to the XDebug stack traces:
xdebug.show_error_trace = 1

Now we have to edit the Apache PHP config file. Again, the location of this file may vary according to your PHP version:

 nano /etc/php/7.2/apache2/php.ini

Inside this file we have to add the following lines. Their goal is to allow another users to connect to your virtual machine and run the debug services of XDebug:

xdebug.remote_enable = 1
xdebug.remote_autostart = 1
xdebug.remote_connect_back = 1

We are done. It will be necessary to restart your Apache service for the changes to take effect. If you want to prove that everything is on its right place you can do it by running a phpinfo command on a web page:

PHP Info

Second step: Visual Studio Code

For the client side you must install the following VS Code extensions:

The configuration of these two extensions are made per project or it would be better to say per VS Code workspace.

To configure ftp-sync we have to press the F1 key and run the command Ftp-sync: Init so a new ftp-sync.json file will be generated in the VS Code workspace folder and there we must setup the SFTP access credentials to the virtual machine, looking something like this:

    "remotePath": "/var/www/myproject/",
    "host": "fischer.test",
    "username": "bobby",
    "password": "mypassword",
    "port": 22,
    "secure": false,
    "protocol": "sftp",
    "uploadOnSave": true,
    "passive": false,
    "debug": false,
    "privateKeyPath": null,
    "passphrase": null,
    "ignore": [
    "generatedFiles": {
        "uploadOnSave": true,
        "extensionsToInclude": [],
        "path": ""

In this example, fischer.test is the hostname I have configured before on my computer to access directly to my virtual machine and /var/www/myproject is where the root directory of my project is located.

Maybe we would need to perform a first synchronization of the project by pressing F1 and picking Ftp-sync: Remote to local if the files of our project are already on the server. The only uncomfortable part of this method is that we must synchronize everything I have modified a file, or we could modify several files and synchronize later the whole folder where they are stored. But c'mon, it's worth just two or three clicks.

Now you have to setup the PHP Debug extension by clicking the gear button on the Debug section of the sidebar on VS Code:

VS Code Debug Config

This will create a launch.json file where we must add a pathMappings directive to allow the remote debugging, looking something like the next snippet of code:

    "configurations": [
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "port": 9000,
            "pathMappings": {
                "/var/www/myproject": "${workspaceRoot}",

The key of the pathMapping must be the root location of the project in the virtual machine, I mean, the same we used as remotePath in the ftp-sync configuration; the value must be the location of our project in our computer so ${workspaceRoot} is enough for this case.

Now store the config file and you are ready: you can now set breakpoints and do variable inspections just like the big guys do. You can start the debugging process by going to the Debug tab on VS Code and clicking the Start debugging button with the Listen for XDebug option selected.

My debug is working!

For now I just have a hug left for you and to say: Happy debugging, my friend!