This article describes how to debug, trace and profile PHP scripts in Ubuntu using a special PHP extension – xdebug, which was created by one of the PHP language developers Derick Rethans.
This article does not claim to be a complete coverage of a vast area of debugging code, but it will be useful for those new to debugging in PHP.
Features of Xdebug
Xdebug is a PHP extension that allows you to use a remote debugger in the IDE via breakpoints. You can use it to monitor variable values. As a result, errors in your code are detected faster than with error_log, print_r and var_dump.
Another useful function is stack trace. It outputs the detailed path that led the application to the error. It contains the parameters passed to the function. Xdebug can also be used as a profiler to find code bottlenecks. If you add external tools, you can visualize performance graphs. For example you can use WebGrind, a set of PHP scripts to easily display statistics directly in your browser.
Furthermore, you can use Xdebug to see how much of the code is executed during a request. This gives you information about how well the code is covered by the tests.
Installing xdebug
The first thing to do before getting started is to install the extension. Before installing it, make sure that your version of PHP >= 4.3 (older versions of the extension doesn’t work, but in most cases it is not needed anymore).y With popular Linux distributions, installing this extension is very easy. Depending on the type of your distribution, run one of the following commands with root privileges:
- For Debian/Ubuntu – aptitude install php5-xdebug
- For Fedora/CentOS/RedHat – yum -y install php-pecl-xdebug
- For Gentoo – emerge dev-php5/xdebug
If your distribution is not among those listed above, or installation from the repository is not available for some reason, it is an option to compile the extension from source. To do this, download the archive with the latest version of the extension from the Xdebug offsite, unzip the archive, go to the folder with the source tree and run the compilation:
phpize
./configure --enable-xdebug
makeIf compilation is successful, file xdebug.so will be created in the directory modules/ – this is the desired extension. Now copy it into the folder with the php extensions and add to your Apache config file the line:
extension=xdebug.soAfter the extension has been installed by any of the above methods – restart Apache! To check if the extension is installed successfully, you can create in any of the VirtualHosts Apache file info.php with the following content:
and run this script in your browser. If the installation is successful you will see in the list of installed extensions a separate table with XDebug options.
Setting up xdebug
Edit php.ini:
sudo gedit /etc/php/apache2/php.iniA full description of the available configuration options could be the subject of a separate article. For those who are new to debugging PHP I suggest the following config:
[debug]
; Remote settings
xdebug.remote_autostart=off
xdebug.remote_enable=on
xdebug.remote_handler=dbgp
xdebug.remote_mode=req
xdebug.remote_host=localhost
xdebug.remote_port=9000
; General
xdebug.auto_trace=off
xdebug.collect_includes=on
xdebug.collect_params=off
xdebug.collect_return=off
xdebug.default_enable=on
xdebug.extended_info=1
xdebug.manual_url=http://www.php.net
xdebug.show_local_vars=0
xdebug.show_mem_delta=0
xdebug.max_nesting_level=100
;xdebug.idekey=
; Trace options
xdebug.trace_format=0
xdebug.trace_output_dir=/tmp
xdebug.trace_options=0
xdebug.trace_output_name=crc32
; Profiling
xdebug.profiler_append=0
xdebug.profiler_enable=0
xdebug.profiler_enable_trigger=0
xdebug.profiler_output_dir=/tmp
xdebug.profiler_output_name=crc32Global settings of the extension, which will act for all sites are added to config php.ini. Settings for individual sites can be specified in .htaccess files using the php_value directive or even in the php scripts themselves by calling ini_set().
Getting information about the script work
Right after the extension is installed, you might notice some changes in the form of improved error output in PHP in your browser or changed output of var_dump(). But this is not the only thing you can do with this extension.
If you use the above configuration, the standard error message will be extended with output of local variables, global variables, and the $SERVER array. You can also add the output of variables which are passed to the script by GET or POST method. To do this, add the lines xdebug.dump.GET=* or xdebug.dump.POST=* to config.
Warning: The advanced error output will only work if display_errors is set to On in the PHP configuration, and if you have not overridden the default error handler with register_error_handler()
To better understand the paragraph above, I advise you to temporarily stop reading this article and run a small script, like this one, on the configured web server:
After running this script instead of the standard message about an attempt to
Fatal error: Call to undefined function
bar() in black letters on a white background you will see a nice table,
which will also contain a lot of additional useful information for
debugging the script.
Thus, the mere presence of the extension saves the programmer the trouble of adding the so called debug output.
Configure Vim for PHP Debugging
Now a plugin for Vim which enables PHP debugging is required . Firstly Vim needs a directory for plugins: from the main menu click Places -> Home Folder, this should open a new file browser window. From this window, click View -> Show Hidden Files and check whether a directory named .vim exists (note the full stop at the start of the directory name), if not right-click, select Create Folder (and enter ‘.vim’) to create it.
Open a Web browser and go to this address:
http://www.vim.org/scripts/script.php?script_id=1929Download this script—currently named debugger.zip—to the .vim directory (hidden files can be shown in the save as box by right-clicking in the file list and selecting Show Hidden Files). From the file browser opened earlier double-click the zip file, then in the window that appears right-click the plugin directory and click Extract. Click Extract to extract the plugin to the .vim directory (check the extract file selection box has defaulted to the .vim directory before extracting, if the files are not in that directory the plugin will not work). The PHP debugging script for Vim should now be installed.
To check the plugin is where it should be, navigate to the: .vim/plugin/ directory using the file browser. Inside this directory should be two files:
- debugger.py
- debugger.vim
PHP Debugger Testing
As an example let’s take /export/data/discuz/test.php (/ export / data / discuz is my Discuz! X root directory).
The content of test.php looks like this:
<?php
phpinfo();
$name = "cdai";
print("hello {$name}");
?>Open test.php with vim, switch to print (“hello {$name}”); on this line, type:VrAdd a breakpoint to the command.
PressF5Start listening, and you should be able to access the test.php page with your browser within five seconds.
http://localhost/test.php?XDEBUG_SESSION_START=1
note: UrlMust be added toXDEBUG_SESSION_START=1Parameters include debugging.
After entering the URL, the call will stop at the breakpoint line. Screenshot below:
