Debug WordPress with Eclipse PDT and Xdebug

I have set up my local development machine (Mac Mini(late 2014) , El Capitan 10.11.6) for WordPress PHP development and debugging, specifically for WordPress Plugin Development. I prefer to use Eclipse PDT and Xdebug for debugging.

We use our own internal POMAMA, script to configure our workstations, which automatically configures Apache, mySQL and few other components we use. I also have HomeBrew installed on my mac.

We also use our quick start guide to install WordPress for local development  on your development machines.

The only issue I had really was configuring Eclipse PDT for debugging using Xdebug. This was due to little gotcha’s, I ran into initially that I lost a bit of time on so I thought I would document this with the hope of saving somebody else time. (Always believe in paying forward 🙂 )


Our approach to WordPress development has evolved. We now make use of Docker for development environments.

You may want to read our posts Using Docker for WordPress Development & Docker and WordPress debug environment

Install Xdebug via HomeBrew

In my particular instance we are developing and testing for WordPress using PHP 7.0 , if you looking for a particular PHP version of xdebug simply swap out the version numbers

[pastacode manual=”brew%20install%20php70-xdebug” provider=”manual” lang=”sh”/]

Install xdebug-osx

Due to the fact that a few of PHP frameworks, in our case CakePHP and Laravel, all need xdebug to be deactivated for when they do generation, it install a handy little CLI program to toggle Xdebug on and off.

[pastacode manual=”brew%20install%20xdebug-osx” provider=”manual” lang=”sh”/]

This enable to simply switch xdebug on or off from the terminal :

[pastacode manual=”xdebug-toggle%20on%20%20%23%23Switch%20on%0D%0Axdebug-toggle%20off%20%23%23%20Switch%20off” provider=”manual” lang=”php”/]

Edit Xdebug Config

We need to make a few edits to the xdebug configuration, if you’re using POMAMA, you can get the information as regards it’s location from PHPInfo,

xdebug.ini config

We’ll use nano to edit this file, these are the settings that worked for me. You may want to edit them for your environment

[pastacode manual=”sudo%20nano%20%20%2Fusr%2Flocal%2Fetc%2Fphp%2F7.0%2Fconf.d%2Fext-xdebug.ini” provider=”manual” lang=”sh”/]

xdebug.ini changes

[pastacode manual=”″ provider=”manual” lang=”sh”/]

Restart Apache

We now need to restart our apache webserver for the changes to take effect.  Ensure you have toggled xdebug to on before you restart.

[pastacode manual=”sudo%20apachectl%20-k%20restart” provider=”manual” lang=”sh”/]

Eclipse Configuration

Open your eclipse PDT and open your WordPress Project . We make use of Eclipse Neon internally so the screens may look a little different depending on your version of Eclipse. I am assuming you have created a new PHP Project and imported your WordPress installation.

Configure a new PHP Web Application debug configuration


Configure the debugger to be xDebug and configure it to use the same port as you set as the remote_host in xdebug.ini


Uncheck the Break at First Line checkbox, as you don’t really want to step through 1000’s of lines of code to get to your issue 🙂


Enter your base URL for your wordpress installation.

In our case we make use of dnsmasq to create local dns names so our base url is usually  If you followed our links earlier your setup should be similar.


You can now click finish.

Start Debugging

You should now be able to place a break point at any area of the code your interested in, hit the debug and open the Debug Perspective.

Top Tip

If you run into issues with a “Waiting for Debug”  play around with the port numbers, but usually 3001 works well for us.

Follow Me