XHGui for storing and reviewing XHProf profiling data

What XHGui stores for PHP applications

XHGui solves the storage and review problem that appears after an application has collected XHProf profiling data. The README separates the roles clearly: an application is profiled, its profiling data is transferred to XHGui, and XHGui saves that information in MongoDB or a PDO database. The interface then provides a graphical way to work with the saved results. This makes XHGui useful for PHP developers who need to inspect requests or CLI runs after collection, rather than only seeing raw profiler output.

The primary use case is therefore a two-part profiling arrangement. The application must first be instrumented with one of the supported profiling PHP extensions, or with the separate perftools/php-profiler package. XHGui does not require that extension merely to run its own interface. The extension belongs on the side of the application being profiled. XHGui receives the resulting profile and stores it for later browsing.

The default storage path is MongoDB. The README also documents PDO storage with SQLite, MySQL, or PostgreSQL, but it warns that PDO may not support every XHGui feature and points readers to issue #320 for backend compatibility details. That warning matters for adoption. A team should not treat MongoDB and PDO as interchangeable without checking the compatibility matrix for the features it expects to use.

The XHGui profiling data flow

The documented flow starts outside XHGui. A web request or CLI script is profiled, and the resulting XHProf data is sent to XHGui. When the profiled application can reach an XHGui instance directly, perftools/php-profiler can submit the data after profiling finishes. This makes XHGui the receiving and presentation layer rather than the profiling engine itself.

For applications that cannot connect directly, php-profiler can capture profiling data in a file for later transfer. XHGui includes an import script for JSONL files. The README warns against importing the same file twice. That warning implies an operational concern beyond launching the web interface: profile imports must be tracked so that a retry does not create duplicate or unintended records. The documentation excerpt ends during that warning, so the exact import command and duplicate-handling behavior are not available here.

In MongoDB deployments, profiles are stored in a results collection in the xhprof database. The recommended indexes cover request time, the main profile's wall time, memory usage, CPU value, URL fields, and server name. These indexes are optional in the installation instructions, but the README presents them as useful for faster page navigation.

MongoDB and PDO backend choices

MongoDB is the documented default. XHGui requires the MongoDB PHP driver version 1.3.0 or later and MongoDB itself version 3.2 or later. The source installation instructions describe starting a MongoDB instance and editing config/config.php when authentication is enabled or the server is not on localhost and the default port. The default configuration therefore assumes a conventional local MongoDB arrangement, but the file is the place where connection details can be changed.

The repository's docker-compose.yml provides a concrete MongoDB deployment. It uses the `xhgui/xhgui:latest` image for XHGui and `percona/percona-server-mongodb:4.4` for MongoDB. It maps XHGui's port 80 to host port 8142 and maps MongoDB's port 27017 to the host. The service also sets `XHGUI_MONGO_HOSTNAME=mongo` and `XHGUI_MONGO_DATABASE=xhprof`. This is a useful reference for the expected service relationship, although the Docker instructions do not explain how to customize every MongoDB authentication setting.

PDO is the alternative documented by the README. It requires PHP's PDO extension and one of the PDO drivers for SQLite, MySQL, or PostgreSQL. The repository includes PDO packages in its Docker image, but the README explicitly qualifies PDO support because some XHGui features may be missing. For a production decision, the compatibility matrix should be checked against the specific reports and queries the team expects from the interface.

Installing XHGui with Docker for a first review

The Docker path is the shortest documented route to a running interface. Copy the example `docker-compose.yml`, start the services, and open the published XHGui port. The following command starts the containers in the background. After it completes, the README directs the reader to open `http://localhost:8142`.

docker-compose up -d

The compose file starts both XHGui and MongoDB. XHGui uses the environment values `XHGUI_MONGO_HOSTNAME=mongo` and `XHGUI_MONGO_DATABASE=xhprof`, while the MongoDB service initializes the `xhprof` database. The compose file also mounts `./config` into the XHGui container and persists MongoDB data in the named `mongodb` volume.

If the interface needs customization, the documented next step is to copy `src/config.default.php` to `config/config.php` and edit the latter file. That copy step is not itself a shell command in the README, so the project-specific configuration file names are more useful than inventing a command around them.

This setup produces the web interface, but it does not profile an application by itself. To obtain data for the first review, the profiled application or CLI script must use the documented `perftools/php-profiler` route, or provide a JSONL file for the import script. The README excerpt does not give a complete profiler invocation, so the first real use is necessarily split between starting XHGui and configuring the separate profiler package.

Installing XHGui from source with MongoDB

For a source installation, the README directs the operator to clone or download the repository, point the webserver at `webroot`, make the `cache` directory writable, start MongoDB, adjust `config/config.php` when needed, install Composer dependencies, and configure rewrite rules. The cache permission command is exact:

chmod -R 0777 cache

The README calls this permissive setting a fallback for a lazy setup. It makes the cache directory writable, but the documentation itself supplies no narrower production permission recommendation. After MongoDB and configuration are ready, install dependencies with Composer:

composer install --no-dev

The webserver must serve the `webroot` directory. Apache users need an override configuration that permits `FileInfo`, and the repository's `.htaccess` supplies the remaining rewrite rules. The Apache example is:

<Directory /var/www/xhgui/>
    Options Indexes FollowSymLinks
    AllowOverride FileInfo
    Require all granted
</Directory>

The README also provides an nginx and FastCGI configuration example. Its `root` directive points at `public/xhgui/webroot/`, which differs from the shorter source-installation instruction that names `webroot`. That difference is a deployment detail to check against the actual checkout and webserver layout rather than a setting to copy blindly.

MongoDB indexes and operational limits

The optional MongoDB indexes are concrete performance configuration, not a claim that XHGui has been benchmarked at a particular throughput. The README says they improve navigation speed by indexing fields used for browsing and sorting. Open a MongoDB shell, select the `xhprof` database, and create the documented indexes with `db.collection.ensureIndex()`.

$ mongo
> use xhprof
> db.results.ensureIndex( { 'meta.SERVER.REQUEST_TIME' : -1 } )
> db.results.ensureIndex( { 'profile.main().wt' : -1 } )
> db.results.ensureIndex( { 'profile.main().mu' : -1 } )
> db.results.ensureIndex( { 'profile.main().cpu' : -1 } )
> db.results.ensureIndex( { 'meta.url' : 1 } )
> db.results.ensureIndex( { 'meta.simple_url' : 1 } )
> db.results.ensureIndex( { 'meta.SERVER.SERVER_NAME' : 1 } )

The README presents these indexes as optional but recommended. It does not document rollback, retention policies, data deletion, authentication setup beyond referring to `config/config.php`, or a production sizing guide. Those omissions are relevant for teams deciding whether the interface can serve as a long-term profiling store. They need to determine those operating details from the selected database and their own deployment rather than assume that the web UI handles them.

Maintenance, releases, and upgrade boundaries

The repository is not marked as archived. Its last push was on 2026-09-07, and the listed releases include `0.23.6`, `0.23.5`, and `0.23.4`, all dated 2025-07-07. The repository's default branch is `0.24.x`, while the Docker Compose file uses the `xhgui/xhgui:latest` image tag. These are separate pieces of information, and an operator should not assume that the `latest` image exactly matches the default branch without checking the image release process.

No license identifier is present in the repository information. The repository metadata says the license is unknown, so this review cannot state what permissions apply to deployment, modification, or redistribution. That is a license due-diligence gap, not a conclusion about acceptable use. The README documents PHP 8.0 through 8.3 as known to work, which gives a stated compatibility range but not a guarantee for every extension, driver, or database combination.

An upgrade also has two separate surfaces: the XHGui code and the database configuration. The README does not describe a schema migration procedure or rollback command in that text. Before changing a deployed instance, verify the release notes or migration files for the selected version and confirm how the active MongoDB or PDO configuration is handled.

When MongoDB is the better fit than PDO

MongoDB is the better documented starting point for a new XHGui deployment. Most of the installation documentation describes it, the default installation uses it, and the Docker Compose file supplies a complete two-service example. Its version requirements and recommended collection indexes are stated directly. That makes the operational path easier to follow than the PDO path, for which the README explicitly warns about missing features.

PDO can still be appropriate when an existing PHP environment already standardizes on SQLite, MySQL, or PostgreSQL and the team accepts backend-specific feature gaps. The difference is not simply “document database versus relational database.” It is that MongoDB is the primary documented path with an explicit storage collection and index recipe, while PDO is presented as a set of drivers accompanied by a compatibility warning. The profiler and GUI remain the same in principle, but report storage behavior and available features may differ.

XHGui is the wrong tool when the requirement is to collect XHProf data but no separate profiling mechanism has been selected. The README explicitly points that job to perftools/php-profiler. It is also a poor fit for a team seeking a self-contained profiling agent, since the profiling extension is not needed to run XHGui itself but is required to profile the target application.

Editorial conclusion

Adopt XHGui when your PHP application already produces XHProf data and your team wants a browser-based place to store and inspect it. Do not choose it as the profiler itself, because the README directs application profiling to perftools/php-profiler. Verify first that your PHP version, selected database backend, webserver routing, and profiler output format match the documented requirements before migrating an existing setup.

Frequently asked questions

Official sources

1. Issues
2. perftools/xhgui on GitHub
3. README
4. Releases