Profiling PHP Applications with Tideways XHProf and XHGui

This article focuses on how to profile PHP applications with Tideways XHProf and XHGui. I myself prefer this approach than the old XDebug and Webgrind so most of my recent projects have been utilizing this. Since this is just simply a note, Google is your friend for the mentioned tools.

0. Install PHP 7.2 FPM (with Nginx, and CLI) as usual

1. Install MongoDB and PHP MongoDB extension

Remember that we need MongoDB version >= 3.0 for XHGui, so we cannot use the built-in Ubuntu 16.04 mongodb package.

apt-key adv --keyserver hkp:// --recv 9DA31620334BD75D9DCB49F368818C72E52529D4
echo "deb [ arch=amd64 ] trusty/mongodb-org/4.0 multiverse" | tee /etc/apt/sources.list.d/mongodb-org-4.0.list
apt-get update
apt-get install -y mongodb-org
service mongod start

apt install -y php7.2-mongodb php-pear php7.2-dev
pecl install mongodb
systemctl restart php7.2-fpm


2. Install Tideways XHProf extensions

git clone
cd php-xhprof-extension/
make install
echo "" > /etc/php/7.2/mods-available/tideways_xhprof.ini
ln -s /etc/php/7.2/mods-available/tideways_xhprof.ini /etc/php/7.2/cli/conf.d/10-tideways_xhprof.ini
ln -s /etc/php/7.2/mods-available/tideways_xhprof.ini /etc/php/7.2/fpm/conf.d/10-tideways_xhprof.ini
systemctl restart php7.2-fpm

3. Install XHGui

  1. Download and install dependencies:
    mkdir -p /home/xhgui
    chown -R www-data:www-data /home/xhgui
    cd /home/xhgui
    git clone .
    php install.php
  2. Setup Nginx virtual host for XHGui:
    cat > "/etc/nginx/sites-available/xhgui.conf" <<END
    server {
        listen   80;
        root   /home/xhgui/webroot/;
        index  index.php;
        location / {
            try_files \$uri \$uri/ /index.php?\$args;
        location ~ \.php\$ {
            include snippets/fastcgi-php7.2.conf;
            fastcgi_param SCRIPT_FILENAME \$document_root\$fastcgi_script_name;
    #	fastcgi_pass;
    #       fastcgi_pass unix:/run/php/php7.2-fpm.sock;
    ln -s /etc/nginx/sites-available/xhgui.conf /etc/nginx/sites-enabled/xhgui.conf
    systemctl restart nginx

    Now we can access the XHGui web interface via

  3. Enabling Profiling in our App: we are going to include the xhgui/external/header.php file to our web app.
    • We can simply do it by adding the following directive to the PHP block of the corresponding web app:
      # Inside file /etc/nginx/sites-available/my_web_app.conf
      location ~ \.php$ {
         # Other directives
         fastcgi_param PHP_VALUE "auto_prepend_file=/home/xhgui/external/header.php";
    • Then, restart Nginx and we are good to go.
  4. Done, you can access the XHGui now. Remember that XHGui only profiles 1 out of 100 requests received, so you need to put enough load and actions on the target website ( to have the result in XHGui.


Leave a Reply