Introduction
In our previous posts, we discussed how to use some tools to explore and debug legacy code. This blog post will explore one of these tools that I personally use quite often in depth: Xdebug and Remote Debugging.
We’ll explore the installation, the required settings tweaks, and some basic tools and workflows to get you started. The least fun and hardest part of this whole process is the installation.
Having xdebug up and running will speed up your code investigations and will really help you dig into troublesome code. It will also give you the best insight into code you aren’t familiar with works without resorting to die statements and var_dumps for small windows.
Development Only
Please only install this on your development and staging environments! Do not install this on any public facing server!
Remote Debugging
I want to take a minute and explain the concept of remote debugging with Xdebug. Until a few years ago, I would install XDebug only to get the “pretty error printing” features. While these features allowed some better control over how I was viewing errors and my var_dump results, it really added nothing I critically needed. Remote debugging now makes XDebug a short list of ‘need to install’ things when setting up a new environment.
Xdebug offers mechanisms to allow you to set breakpoints in your code to stop it’s execution and view the current state. This means you can say “stop here and let me take a look around at what the code is doing at this moment” on the server itself. You actually connect to the server and can poke around, set some conditional break points (where you stop execution when a variable is set to a certain value) and even evaluate some raw PHP on the server given certain conditions.
To accomplish this, you must connect a debugging tool to your server with a specified and exposed port and talk to it using a protocol provided by XDebug. Your debugger is the tool you use on your machine, XDebug is the tool/port/settings collection you use to connect to your server.
If this sounds like the basic IDE debugging tools you have used with other languages like C++ and JAVA (and also like something overcomplicated for being such a normal feature for other development stacks), it should. It’s pretty much the same thing. The biggest difference here is that this was not a widely used debugging method for hosted PHP. I’d like to help change that with this blog post.
Installing the Xdebug Extension
The xdebug project and github page offer some installation instructions that feel woefully lacking. Also, they offer little advice tailored to individual setups and environments. I’ll try and provide some examples of common installation methods.
Please note that these methods assume you are installing on the same server you host your development environment that serves the PHP code you wish to debug. This means, if you are running a vagrant box or docker container to host your code, install xdebug on this server instance. If you host your locally code on the same machine you are edit and maintain the code on, install xdebug on this machine. See the section above for some clarification on remote debugging.
All of these instruction assume you have administrator access and some level of comfortability with the *unix command line. If you do have access to your server in this capacity, or you are not comfortable with running these commands, you might want to find a grown up to help you.
pecl / pear
You can install Xdebug extension with the pecl tool and then tweak your php.ini file to include the installed extension. The official docs recommend this route first actually. The installation instructions are the same with the pear tool as they are for pecl. I have found this is the easiest installation method if you are running your server on a MacOS environment.
After you are sure you have pecl installed, run this command on your command line.
pecl install xdebug
apt-get / yum
If you are running your server on an Ubuntu/Debian/CentOS machine, you can install the xdebug with your specific package manager.
sudo apt-get install php5-xdebug
or
yum install php5-xdebug
Homebrew
This is a method I have never tried personally but I know there are some recipes specifically for installing xdebug with homebrew.
From what I read, you will need to add the homebrew-php repository and install this from the command line as well. Check out this repo link for more information.
Compiling it yourself
Another method I have never tried personally, but I know its possible. If you are want to do this yourself, you might be beyond the scope of this post. I’ll just point you to the project page for the most up to date information.
Update your php.ini file
Find your newly installed php extension and add this line to your php.ini file
zend_extension=“/usr/local/php/modules/xdebug.so”
Replace the “xdebug.so” file with whatever your tool installed. It’s also safe to create a symlink with the filename “xdebug.so” as well. If you have trouble finding this file, try the following command to find the extension file:
find / -name ’*xdebug*.so’ 2> /dev/null
Verifying your XDebug Installation
Restart apache and create a test file called test.php with the following lines of code and load it into your browser:
<?php
phpinfo();
Search for “xdebug” and you should see something like this in your browser:
If you see a line that looks like the one highlighted above, congrats, you have installed xdebug!
Port Forwarding
You will need to expose some ports on your server to allow connections from your debugging client. How you accomplish this will certainly depend on your individual environment setup, but I would like to note this to save you the time I lost trying to find out why I could not connect.
And we will explain the port you will need to be expose and forward in this next section…
Xdebug INI Settings
Here are some of the INI settings you will need to update in order to enable remote connections. These settings will be found in your php.ini file, or a possible xdebug.ini file if one was created by your install method.
- xdebug.remote_host
- This setting allows you to specify an address where you debugging client is connecting from.
- In most cases, this will be set to “localhost”, but may differ in your development environment.
- This setting is ignored if xdebug.remote_connect_back is set to TRUE. See more info below.
- xdebug.remote_autostart
- This setting enables remote debugging, turn this on!
- xdebug.remote_port
- This setting allows you to specify a port for your debug client to connect to the remote server with. You will need this value when configuring your remote debugging tool.
- This is typically set to 9000 but you can update this to any port that isn’t being used if you feel contrary.
- xdebug.var_display_max_children
- This setting allows you to specify the amount of array children and object’s properties are shown when you use a var_dump or use your debugging client’s function trace tool.
- By default this is set to 128, but you can set it to -1 if you want to remove the limit entirely.
- xdebug.var_display_max_data
- Like var_display_max_children, this setting allows you to set a maximum string length that is shown when variables are displayed in var_dumps or function traces.
- By default this is set to 128, but you can set it to -1 if you want to remove the limit entirely.
- xdebug.var_display_max_depth
- Another setting that allows you to set a limit when using var_dump or function tracing, but this one sets the nested levels of array elements and object properties displayed.
- By default, this is set to 128, but again if you live dangerously you can remove the limit entirely and set it to -1.
- xdebug.scream
- Setting this value to true will disable the @ (the “shut up”) operator entirely.
- This is super useful when you find out when you predecessor was just hiding a critical error behind the @ operator and you can finally go to be because you found the elusive notice showing the variable was never set in the first place and you had no idea and thats why you can’t get the page to load when you don’t have a cookie set in IE 9.
- xdebug.remote_connect_back
- Setting this value to true will allow you to connect and attach a remote debugging client to your server from any address.
- This setting is great for shared development environments but is quite dangerous since it will just allow anyone to connect who tries. YES, anyone.
- Also of note, this will override the xdebug.remote_host setting.
Remote Debugging Tools
Editors
While I personally like to use the stand alone tools, I do know a lot of people who prefer to use these editors to remote debug.
While I’m sure a cursory google search can lead you to some better instructions on how to install and configure these tools, I thought it was worth mentioning since a lot of people use these tools and they offer the remote debugging tools you might want to use.
Stand Alone Tools & Helpers
This is a tool I use on an almost daily basis. Its relatively small and lightweight, and gets out of the way when I am done. I also mentioned it in our last blog post. I do need to note that this tool does not seem to be updated frequently and occasionally crashes without warning. That being said, I still highly recommend it.
This is a simple chrome extension that allows you to toggle the xdebug remote debugging cookie for a given URL. This is great to quickly start and stop a remote debugging session.
It’s pretty much an unobtrusive button that lives in chrome. I would install it now if I were you.
Conclusion
I barely touched the surface of remote debugging using xdebug, but I hope I inspired you to install and configure it now. Stop using var_dump and die statements and debug like a grown up!
