Debug PHP like Pro: Intellij Idea + VirtualBox + XDebug

VirtualBox + XDebug overview

For a long time I used to use built-in PHP debugging function like var_dump, debug_backtrace, spl_object_hash etc. That tools are very useful but there is one tool combining all of them. I’m talking about XDebug PHP module. With XDebug you can stop code execution in any place you need and get all information about objects, variables and call stack in one window.

breakpoint overview

Landscape overview

In this article I use host machine with Windows 7 and Intellij Idea onboard. A VirtualBox virtual machine with Ubuntu Server 14.04 and PHP 5.3 (it’s very old, I know, but it doesn’t metter is this case ūüôā ).

Getting started. Network configuration

XDebug uses your network connection for transferring data that is why valid network configuration is critical. Your VirtalBox machine must have at least one “Host-Only Adapter” newtork connection

virtualbox network config

Check virtual and host machines network settings. They must have IP addresses from same subnet.

Virtual machine (Ubuntu)

vlad@ubuntu:~$ ifconfig
eth1      Link encap:Ethernet  HWaddr 08:00:27:30:9c:31
          inet addr:  Bcast:  Mask:
          inet6 addr: fe80::a00:27ff:fe30:9c31/64 Scope:Link
          RX packets:165 errors:0 dropped:0 overruns:0 frame:0
          TX packets:11 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000
          RX bytes:16592 (16.5 KB)  TX bytes:1422 (1.4 KB)

Host machine (Windows)

host network config

Verify network connection with ping command.

Setup XDebug PHP module

Install XDebug PHP module in Ubuntu with the commands below.

For PHP 5

sudo apt-get install php5-xdebug
sudo php5enmod xdebug

Facing troubles with installation? Check this post

For PHP 7

sudo apt-get install php-xdebug
sudo phpenmod xdebug

Check the module was installed properly with php -v command:

vlad@ubuntu:~$ php -v
PHP 5.3.10-1ubuntu3.26 with Suhosin-Patch (cli) (built: Feb 13 2017 20:37:53)
Copyright (c) 1997-2012 The PHP Group
Zend Engine v2.3.0, Copyright (c) 1998-2012 Zend Technologies
    with Xdebug v2.1.0, Copyright (c) 2002-2010, by Derick Rethans

Configure XDebug module

Open PHP config (/etc/php5/apache2/php.ini) with your favorite text editor and append these lines to the end:


Note remote_host value must be your host machine IP address. Since in Ubuntu PHP has separate configs for Apache and CLI append same lines to /etc/php5/cli/php.ini file.

Configure Intellij Idea

In Intellij Idea go to Settings -> Languages and Frameworks -> PHP -> Debug and verify settings.

intellij xdebug config

intellij xdebug config

Note ip address and port must be same with XDebug module config.

You are almost ready! Click on “Start listening for PHP Debug connections” button in the top panel of Intellij Idea.

xdebug listening

Choose a test page (index would be great) code and set your first breakpoint.

xdebug breakpoint

Refresh the page in browser.

For the frist time Idea most likely will show you a popup window with mapping settings

xdebug intellij mapping settings

I recommend you use default option “Import mappings from deployment” because I believe you already have a working deployment config for uploading code to the vritual machine.

After you accept settings your code execution will stop on the breakpoint you set and you will see all necessary debug information: variables values, objects state, call stack.

xdebug breakpoint

When you are ready to proceed the code execution just press on green triangle marked in the picture above.

Here we are! You don’t need var_dump any more!


“Cannot find a local copy of the file” error

"Cannot find a local copy of the file" error

The error appears if you missed your mapping configuration. Go to your server config and add mappings manually

xdebug mapping settings

“ unable to find valid certification path” error

Occurs if you use  development HTTPS server without a valid SSL certificate. You need to import invalid certificate to the java cert storage.  Open the site in browser and open Developer tools. Go to Security tab:

" unable to find valid certification path" error

Click on “View certificate” button. Save the certificate to file

ssl cert export

ssl cert export

ssl cert export

Add exported certficate to Java certificate storage:

H:\Windows\system32>cd H:\Program Files (x86)\JetBrains\IntelliJ IDEA 2016.3.2\jre\jre\lib\security
H:\Program Files (x86)\JetBrains\IntelliJ IDEA 2016.3.2\jre\jre\lib\security>keytool -keystore cacerts 
-importcert -alias %your_dev_server_domain% -file %certificate_filename%
Enter keystore password:
.....output omitted......
Trust this certificate? [no]:  yes
Certificate was added to keystore

Restart Intellij Idea