Xhprof Buggregator Bundle Laravel Package

Getting Started

This is a thin Symfony bundle that wires the XHProf PHP profiler into Buggregator's trapper, so profiled requests show up as flamegraphs in the Buggregator UI without you hand-rolling a UDP sender. Treat it as glue, not a framework.

Minimal setup:

1. Install the XHProf extension in the PHP runtime you profile with (either xhprof or tideways_xhprof — confirm which one your PHP image ships, since the bundle's collector has to match).
2. composer require --dev iluckhack/xhprof-buggregator-bundle
3. Enable the bundle in config/bundles.php (Flex usually does this; verify).
4. Run Buggregator locally, e.g. docker run --rm -p 8000:8000 -p 9912:9912 -p 9913:9913 ghcr.io/buggregator/server:latest, and open http://localhost:8000.
5. Point the bundle at the trapper. Inspect the actual config tree before guessing: bin/console config:dump-reference xhprof_buggregator The keys you care about are the trapper host/port (Buggregator's XHProf trapper is typically UDP 9912) and an enable/disable flag scoped to dev/test.

First useful use case: profile one request. Hit your app through the browser, then open the XHProf tab in Buggregator. If a flamegraph appears, the wiring is correct — everything else (sampling, triggers, exclusions) is tuning.

Implementation Patterns

Gate it to non-production. The bundle belongs in require-dev and should be enabled only in dev (and maybe a staging environment). In config/packages/dev/xhprof_buggregator.yaml, enable it and set the trapper endpoint. Keep the prod config absent so you can't accidentally ship profiling to customer traffic.

Triggered profiling instead of always-on. Profiling every request in a busy dev environment floods the trapper and makes the Buggregator UI useless. Prefer a trigger — a header (X-Profile: 1), a cookie, or a query param — so you profile deliberately. If the bundle exposes sampling, keep the rate low (1–10%) and combine it with path exclusions.

Exclude noise. Health checks, _profiler, _wdt, static assets, and messenger worker polls will dominate your sample set. Add path/regex exclusions in the bundle config (or in your firewall/RequestMatcher if the bundle doesn't support them directly). This is the single biggest quality-of-life change after first setup.

Local docker-compose workflow. Put Buggregator next to your app in docker-compose.yml, add host.docker.internal (or the service name) as the trapper host, and expose the trapper port. This makes profiling reproducible across the team instead of "works on my machine."

Pair with the Symfony profiler, don't replace it. XHProf gives you wall-time and call-graph data across the whole request; the Symfony profiler gives you DB queries, events, and cache stats. Use XHProf when you suspect a CPU-bound or call-graph problem, and the profiler when you suspect I/O. Cross-reference the two — a slow query shows up in both, but only the XHProf flamegraph shows you what called it.

Use it as a Blackfire/Tideways substitute for small teams. If you don't want to pay for Blackfire or run a Tideways server, this bundle + Buggregator + the XHProf extension is a credible free local profiling stack. The trade-off is fewer features (no comparisons, weaker aggregation), so it's best for "why is this endpoint slow today" rather than long-term performance tracking.

Gotchas and Tips

Extension mismatch is the #1 failure. xhprof and tideways_xhprof expose different function names and data formats. If Buggregator shows nothing or errors, first check php -m | grep -i xhprof and confirm the bundle's collector supports that extension. A profile that silently produces zero samples almost always means the wrong extension or a disabled xhprof_enable() path.

UDP is lossy. Buggregator's trapper is UDP by default. Large profiles (long requests, deep call graphs) can be truncated or dropped. If flamegraphs are incomplete, profile a narrower scope (a single controller action, a console command) rather than a whole page with dozens of subrequests.

Firewall and Docker networking. The trapper port must be reachable from the PHP process, which is often in a different container than Buggregator. 127.0.0.1 inside a PHP container is not the host. Use the compose service name or host.docker.internal, and verify with nc -u -z <host> 9912 (or send a test packet) before debugging the bundle.

Config cache. After changing the bundle's YAML, run bin/console cache:clear — Symfony bundles with compiler passes routinely cache the resolved endpoint, and a stale cache looks exactly like "the bundle is broken."

Version drift and low maintenance signal. Seven stars, zero dependents, last release March 2024. That's not a red flag on its own — the surface area is small — but assume you may need to fork or patch it if Buggregator's trapper protocol or Symfony's bundle API shifts. Pin the version in composer.json, and skim the bundle source (it's small) so you know exactly what it does. If it stops working, the fallback is ~30 lines of register_shutdown_function + stream_socket_client('udp://...') sending the xhprof payload directly.

Don't profile CLI blindly. Messenger workers and cron jobs can run for minutes; a full-request XHProf profile of a worker is enormous and rarely useful. Scope profiling to a single message handler or command invocation, or skip CLI entirely.

Extension point: wrap the collector. If you need to tag profiles (branch name, commit SHA, user ID), do it by decorating the bundle's collector service or by sending a header that your app forwards. Buggregator's UI filters on tags, so this is worth the 10 minutes if multiple developers share one Buggregator instance.

Debugging checklist when nothing appears: extension loaded → bundle enabled in the correct env → config cache cleared → trapper host/port reachable from the PHP container → Buggregator logs show incoming packets → profile is small enough to survive UDP. Work the list in that order; each step eliminates half the remaining problem space.