Weave Code
Laravel Xhprof Laravel Package
laracraft-tech/laravel-xhprof
Laravel XHProf is an easy profiling package that helps you find performance bottlenecks in your Laravel apps. Enable it, browse your app, then inspect detailed XHProf or Tideways call graphs through a built-in web UI to see exactly where time is spent.
Laravel XHProf brings function-level PHP profiling to Laravel through the XHProf extension. It instruments HTTP requests and Artisan commands, stores each profile, and lets you inspect call graphs, wall time, and memory usage to pinpoint slow code and bottlenecks.
Enable it with environment variables and a published config file—ideal for local and staging environments. Sampling and storage are configurable, keeping overhead low while surfacing the hot paths that matter.
- Automatic request & Artisan profiling
- Environment-based toggling and sampling
- Profile viewer for call graphs and timings
- Configurable profile storage
- Publishable config with sensible defaults
Frequently asked questions about Laravel Xhprof
- How do I install laracraft-tech/laravel-xhprof in a Laravel app?
- Install it with Composer using composer require laracraft-tech/laravel-xhprof, then publish the config and migration files with the vendor:publish command. Make sure the XHProf PHP extension (xhprof.so) is installed and enabled in both your web and CLI PHP configurations before running it. Register the profiling middleware so web requests are captured, and open the built-in dashboard route to inspect the stored runs. No custom routes or controllers are required for basic usage.
- Which Laravel versions does laravel-xhprof support?
- The package is actively maintained for Laravel 10 through 13, with dedicated compatibility releases for each major version. Laravel 10 support landed in v1.0.9, Laravel 11 in v1.1.0, Laravel 12 in v1.2.0, and Laravel 13 in v1.3.0. You should still validate against your exact Laravel minor and PHP version before committing, because the compatibility work tracks framework releases rather than a fixed support matrix.
- Do I need to install the XHProf PHP extension to use this package?
- Yes. laracraft-tech/laravel-xhprof is a wrapper around XHProf, so the xhprof.so extension must be installed and enabled in both your web SAPI and CLI PHP configurations. You can confirm it is loaded by running php -m | grep xhprof. This is the main adoption blocker: shared hosting, managed platforms, or locked-down base images may not let you install the extension, in which case you need a fallback such as Tideways or Blackfire.
- How do I control when laravel-xhprof profiles a request?
- Profiling is gated by configuration, so you can restrict it to environments such as local or staging, limit it to an allowlist of routes, and set a sampling rate. Version 1.3.0 also added the ability to skip profiling when the URL contains a given needle, which is handy for excluding health checks or polling endpoints. Keep profiling disabled in production and enable it only for targeted debugging, since it adds measurable request overhead.
- Where does laravel-xhprof store profile data, in the database or in files?
- By default profiles are persisted to the database in an xhprof_runs table created by the package migration, so you need to publish and run that migration before profiling works. File storage is available as an alternative, which avoids adding rows to your database but complicates multi-instance setups because the files must live on a shared volume. Decide between the two early, because database storage creates a retention and pruning obligation that you own.
- Can laravel-xhprof profile Artisan commands and queue workers?
- Web requests are profiled automatically through middleware, but CLI commands and queue workers require explicit instrumentation. You wrap the code you want to measure with the package's start and stop calls, or integrate it at the command level. Plan this work into your adoption estimate rather than assuming the package covers CLI profiling out of the box.
- Is laravel-xhprof safe to run in production?
- It can run in production, but it is not designed as an always-on APM tool. It profiles individual requests and reports wall time, CPU, and memory, but it does not provide infrastructure metrics, distributed tracing, real user monitoring, or long-term trend analysis. Enable it selectively for short debugging windows, keep sampling low, and do most investigations in staging.
- How do I stop the xhprof_runs table from growing too large?
- Set a retention policy and prune old profiles on a schedule, or switch to file storage if you expect high volume. Database storage adds rows and blobs to your application database, which affects backup and restore times as well as staging database stability. Also make sure you are on the latest migration, since older schemas used column types that could truncate large profile payloads and produce misleading results.
- How does laravel-xhprof compare to Tideways, Blackfire, and Laravel Telescope?
- Laravel Telescope gives you a broad debugging view of requests, queries, and events but does not do function-level profiling the way XHProf does. Tideways and Blackfire are commercial profiling platforms with hosted dashboards, tracing, and production-safe overhead in exchange for licensing costs. laracraft-tech/laravel-xhprof is a free, self-hosted option that keeps data in your own database or files, which suits teams that want request-level profiling without a vendor contract.
- Is laracraft-tech/laravel-xhprof actively maintained and safe to depend on?
- It is a single-maintainer community package with a relatively small following, a few hundred GitHub stars, and very few dependent packages, so expect to read the source when you hit edge cases. The Laravel 10 through 13 compatibility releases show ongoing maintenance, but you should pin versions and test upgrades in a branch. Assign an internal owner so bugs and questions have somewhere to go rather than relying on upstream response times.
Weaver
How can I help you explore Laravel packages today?