Xhprof Laravel Package

Getting Started

Xhprof is a PHP extension + UI bundle for profiling PHP applications at function-level granularity. Since it's an extension, the first step is installing the xhprof PECL package (e.g., pecl install xhprof) and enabling it in php.ini (extension=xhprof.so on Linux). Once installed, you trigger profiling by calling xhprof_enable() at the start of your script (e.g., early in the front controller or middleware), then xhprof_disable() at the end, which returns raw profiling data. Pass that data to the built-in HTML UI (usually xhprof_html/index.php) for visualization. For Laravel, the simplest first use case is wrapping a single route’s execution to diagnose a slow endpoint.

Implementation Patterns

• Manual instrumentation: Wrap a specific script or CLI job with xhprof_enable() / xhprof_disable() for one-off diagnostics.
• Laravel middleware integration: Create a middleware that starts profiling on request entry and saves results (optionally to disk or a profiling storage system) on response. Store the run ID in a query param or header for the HTML UI.
• Conditional activation: Enable profiling only for authenticated admins or based on request headers (e.g., X-Profile: 1), using config flags to avoid performance impact on production users.
• Storage backends: Use the xhprof_save_run() function to write profiling runs to a directory, then browse via the UI or integrate with systems like Blackfire or custom dashboards.
• CLI profiling: Use xhprof_enable() inside artisan commands to profile queue workers or exports.

Gotchas and Tips

• PHP version compatibility: Xhprof’s PECL extension is not actively maintained for PHP 8+; consider tideways/xhprof or XHProf fork for modern PHP versions.
• Memory overhead: Profiling adds significant memory overhead; never enable it globally in production—only on demand.
• Run ID management: The UI expects runs to be saved in a specific directory (/tmp/xhprof by default) with filenames like run_id.xhprof. Use xhprof_save_run() and ensure the web server can read that directory.
• UI limitations: The bundled HTML UI is minimal and dated; for better analysis, export to JSON and use tools like FlameGraph or Tideways Dashboard.
• Startup conflicts: Ensure auto_prepend_file or auto_append_file in php.ini aren’t interfering with manual profiling calls—especially in CLI or FPM contexts. Use xhprof_disable() only once per enable() call to avoid segfaults.