Configure

Xdebug configuration lives in your php.ini file. Here are the Xdebug profiler configuration settings I recommend. Make sure you specify your own profiler output directory. Restart your PHP process after saving these settings:

xdebug.profiler_enable = 0
xdebug.profiler_enable_trigger = 1
xdebug.profiler_output_dir = /path/to/profiler/results

xdebug.profiler_enable = 0

This instructs Xdebug to not run automatically. We don’t want Xdebug to run automatically on each request, because that would drastically decrease performance and impede development.

xdebug.profiler_enable_trigger = 1

This instructs Xdebug to run on-demand. We can activate Xdebug profiling per-request by adding the XDEBUG_PROFILE=1 query parameter to any of our PHP application’s URLs. When Xdebug detects this query parameter, it profiles the current request and generates a report in the output directory specified by the xdebug.profiler_output_dir setting.

xdebug.profiler_output_dir = /path/to/profiler/results

This is the directory path that contains generated profiler results. Profiler reports can be massive (e.g., 500 MB or larger) for complex PHP applications. Make sure you change this value to the correct filesystem path for your application.

Trigger

The Xdebug profiler does not run automatically because the xdebug.profiler_enable setting is 0. We trigger the Xdebug profiler for a single request by adding the XDEBUG_PROFILE=1 query parameter to any PHP application URL. An example HTTP request URL might be /users/show/1?XDEBUG_PROFILE=1. When Xdebug detects the XDEBUG_PROFILE query parameter, it activates and runs the profiler for the current request. The profiler results are dumped into the directory specified by the xdebug.profiler_output_dir setting.

Analyze

The Xdebug profiler generates results in the CacheGrind format. You’ll need a CacheGrind-compatible application to review the profiler results. Some good applications for reviewing CacheGrind files are:

• WinCacheGrind for Windows

• KCacheGrind for Linux

• WebGrind for web browsers

Mac OS X users can install KCacheGrind with Homebrew using this command:

brew install qcachegrind

Install

The easiest way to install XHProf is with your operating system’s package manager (assuming you installed PHP the same way):

# Ubuntu
sudo apt-get install build-essential;
sudo pecl install mongo;
sudo pecl install xhprof-beta;

# CentOS
sudo yum groupinstall 'Development Tools';
sudo pecl install mongo;
sudo pecl install xhprof-beta;

Append these lines to your php.ini file, and restart your PHP process to load the new extensions:

extension=xhprof.so
extension=mongo.so

XHGUI

XHProf is most useful when paired with XHGUI, Facebook’s companion web application used to review and compare XHProf profiler output. XHGUI is a PHP web application and requires:

• Composer

• Git

• MongoDB

• PHP 5.3+

• PHP mongo extension

I assume these system requirements are installed. I also assume the XHGUI web application lives in the /var/sites/xhgui/ directory. This directory path is probably different on your server, so keep that in mind:

cd /var/sites;
git clone https://github.com/perftools/xhgui.git;
cd xhgui;
php install.php;

The XHGUI web application has a webroot/ directory. Update your web server virtual host’s document root to this directory.

Configure

Open XHGUI’s config/config.default.php file in a text editor. By default, XHProf collects data for only 1% of all HTTP requests. This is fine for production, but you may want to collect data more frequently during development. You can increase XHProf’s data collection by editing these lines in the config/config.default.php file:

'profiler.enable' => function() {
    return rand(0, 100) === 42;
},

Change these lines to:

'profiler.enable' => function() {
    return true; // <-- Run on every request
},

Trigger

You must include the XHGUI web application’s external/header.php file at the very beginning of your PHP application. It’s easiest to use PHP’s auto_prepend_file INI configuration setting. You can set this in the php.ini configuration file:

auto_prepend_file = /var/sites/xhgui/external/header.php

Or you can set this in your nginx virtual host configuration:

fastcgi_param PHP_VALUE "auto_prepend_file=/var/sites/xhgui/external/header.php";

Or you can set this in your Apache virtual host configuration:

php_admin_value auto_prepend_file "/var/sites/xhgui/external/header.php"

Restart PHP, and XHProf will begin collecting and saving information into its MongoDB database. You can review and compare XHProf runs at the XHGUI virtual host’s URL.