How to Install and Use XHProf for PHP Performance Profiling

Introduction

XHProf is a lightweight hierarchical profiler for PHP that records call counts, execution time, CPU usage, and memory consumption. It provides an HTML‑based UI for browsing and sharing profiling data, supports call‑graph visualisation, and can compare multiple runs.

Installation

PECL Installation

Details are available in the PECL manual. The package page (https://pecl.php.net/package/xhprof) lists releases, source files, maintainers, and changelogs.

Source Installation

wget https://pecl.php.net/get/xhprof-2.3.9.tgz
 tar -zxvf xhprof-2.3.9.tgz
 cd ./xhprof-2.3.9/extension
 phpize
 ./configure --with-php-config=/usr/local/php-7.4/bin/php-config
 make
 make install

php.ini Configuration

[xhprof]
extension=xhprof.so;
xhprof.output_dir=/tmp/xhprof;

Verify Installation

/var/www # php --ri xhprof

xhprof

xhprof support => enabled
Version => 2.3.9

Usage

Middleware Integration (XhprofMiddleware)

class XhprofMiddleware implements MiddlewareInterface {
    /**
     * @desc: process description
     * @param Request $request
     * @param callable $handler
     * @return Response
     */
    public function process(Request $request, callable $handler): Response {
        $xhprof = $request->get('xhprof', 0);
        $extension = extension_loaded('xhprof');
        if ($xhprof && $extension) {
            // Include XHProf library files from the downloaded package
            include_once public_path() . "/xhprof/xhprof_lib/utils/xhprof_lib.php";
            include_once public_path() . "/xhprof/xhprof_lib/utils/xhprof_runs.php";
            xhprof_enable(XHPROF_FLAGS_NO_BUILTINS + XHPROF_FLAGS_CPU + XHPROF_FLAGS_MEMORY);
        }

        $response = $handler($request);
        if ($xhprof && $extension) {
            $data = xhprof_disable();
            $objXhprofRun = new \XHProfRuns_Default();
            $objXhprofRun->save_run($data, sprintf('%s', date("YmdHis")));
        }
        return $response;
    }
}

Viewing Reports

Access URL: http://webman.xhprof.com/xhprof/xhprof_html/index.php

Existing runs

Webman\App::Webman{closure}

Graphical display

Metric Definitions

Function Name : Name of the method.

Calls : Number of times the method was invoked.

Calls % : Percentage of this method's calls relative to the total calls of sibling methods.

Incl. Wall Time (µsec) : Inclusive execution time including child calls.

IWall % : Percentage of inclusive wall time.

Excl. Wall Time (µsec) : Exclusive execution time of the method itself.

EWall % : Percentage of exclusive wall time.

Incl. CPU (µsec) : Inclusive CPU time including child calls.

ICpu % : Percentage of inclusive CPU time.

Excl. CPU (µsec) : Exclusive CPU time of the method itself.

ECPU % : Percentage of exclusive CPU time.

Incl. MemUse (bytes) : Inclusive memory usage including child calls.

IMemUse % : Percentage of inclusive memory usage.

Excl. MemUse (bytes) : Exclusive memory usage of the method itself.

EMemUse % : Percentage of exclusive memory usage.

Incl. PeakMemUse (bytes) : Peak inclusive memory usage.

IPeakMemUse % : Percentage of peak inclusive memory usage.

Excl. PeakMemUse (bytes) : Peak exclusive memory usage.

EPeakMemUse % : Percentage of peak exclusive memory usage.