Over the weekend I spoke at WordCamp London about using XDebug, it was a quick lightning talk, and I wanted to write out what I went through and some additional bits because a few people said they’d like something like that to get them started. Plus usually after a WordCamp I usually just post a simple blog about ‘Oh yeah this happened and it was fun’ so I wanted to write something more useful after it!
It’s also worth mentioning that I’m not a developer, so this is a very basic ‘How to get started’ guide showing you just some of the things XDebug can do. It’s a much more powerful tool than outlined here, and you should definitely do some extra research after reading!
So uh, yeah! Here goes.
Setting XDebug up on a local environment (MAMP)
The easiest way to get started with XDebug is with MAMP on your computer, because it comes already installed. If you’re using a different local development solution there’s tonnes of guides online for a variety of them. I just used MAMP because I found it by far the quickest and easiest to set up for beginners.
Here are the steps:
- Download and install MAMP from: https://www.mamp.info/en/
When MAMP is installed and opened you will have a window like the one to the right. Click ‘Start servers’ to fire up your local environment.
This will load up a webpage with useful resources for your local development area. It’ll look like the screenshot below – and will include links to your homepage and php info page.
From here, click on the ‘phpInfo’ page, this gives you useful information about the version of PHP and the modules associated with it running on your test server. we specifically want to use this page to find out where our php.ini config file is located.
Now we know where the file is located, we can navigate there on our computer. So if you go to the folder where the php.ini files located and open it up in your preferred text editor program, you can edit some of the options here. We are going to enable XDebug by finding this line at the bottom:
This is the XDebug module, which is disabled by default, to enable it all you need to do is remove the semi-colon from the start and add whichever XDebug options you want to enable, so here’s what my XDebug lines look like in php.ini after enabling it:
Finally, I enable onsite errors on my test server so I can see them immediately on the page. To do this I change the line in my php.ini file currently saying ‘display_errors = Off’ to:
Then use the MAMP main screen to restart my server. When that is done you can check your php.ini file to see if XDebug is listed as enabled, or you can go ahead and start breaking some PHP code, because with display errors enabled it will show you on your homepage like this:
You don’t have to enable onsite errors, but I find them easy to work with, instead you can choose log files to send them to, for a full list of options check out: https://xdebug.org/docs/
Profiling is a super handy tool that XDebug offers. It helps to find out where memory issues lie, by saving data about your called functions in a cachegrind file.
To enable profiling, you first need to add this to your php.ini file (or possibly .htaccess depending how your server is set up and if you’re using actual online hosting):
This enables profiling, and your site will start generating a cachegrind file full of useful insights. For ease of obtaining this, you can set your own path for where the cachegrind file(s) will be saved:
From there, I can download and save my cachegrind file to my computer. Opening it will give you all the information obtained, but it’s pretty much unreadable because of the file format. But with a program like Webgrind you can open the cachgrind file in a much more readable and user-friendly format. For Mac users like myself however, the easiest way to do this is by installing and running Qcachegrind. Which is installed as follows:
- Open Terminal on your Mac.
- type ‘brew install qcachegrind’
- Type ‘brew install graphviz’
Now you can run Qcachegrind and open the file you saved earlier, as follows:
Obviously change the directory to wherever you downloaded and saved your cachegrind file. When this is ran it will load up a window that looks something like this:
This screenshot does contain a lot of information, but it is far more readable than just opening up the cachegrind file in your text editor. The left side panel gives you load times for individual functions, in order of what takes the longest. With this you can easily identify if a plugin is slowing your WordPress site down, because it might have a specific function taking a long time here.
The right side gives a more graphical representation of these load times. Bigger boxes are bigger and longer-to-run functions. It does give a lot more information than this, but this is mostly what I’ve used qcachegrind for, and its definitely worth running if you want to get some deep insights in to what is running and causing slowdown on your site.
Breakpoints and FYIs
I don’t do a lot of hardcore development myself, so breakpoints aren’t something I regularly use. But they’re definitely worth looking in to because it allows you to use XDebug with your code editor and set a line in your file to stop the script running at that point.
I’m going to link to the documentation for Atom for that, but yeah, check breakpoints out:
Other things to be aware of when running XDebug on your servers are:
- XDebug is resource intensive, so if you do enable it on any live hosting, make sure you turn it off any time it is not being actively used by yourself to debug code. Ideally just run it on your staging.test environments.
- Keep in mind on-site errors will also need switching off if you don’t want them showing up.
- Cachegrind files and extended error logs can fill up server space quickly, so again, only enable it when needed!
Thanks for reading through this, if anyone needs further help getting started with XDebug feel free to get in touch. I’m not sure how good I am at writing tutorials so if anyone gets stuck I’d love to know if something needs making clearer!
Also check out 34SP.com‘s WordPress hosting as we have XDebug ready to run on our servers which helps us to help you debug your site!
Check out the official documentation for a full list of options and features and have a rad time debugging! – https://xdebug.org/docs/