Perf Collector Bundle Laravel Package

Getting Started

php-bug-catcher/perf-collector is now installable on Symfony 8 stacks — which, for Laravel users, means Laravel releases that pull in Symfony 8 components. If you were blocked on 2.0.0-RC1 (its Symfony constraint made the package unresolvable), RC2 is the first 2.x you can actually composer require on a current framework.

Minimal steps:

composer require php-bug-catcher/perf-collector:2.0.0-RC2 --with-all-dependencies

Pin the exact RC while you evaluate it — see Gotchas. Because the VCS repository block has been dropped, you install from Packagist like any normal dependency; there is no need to add a repositories entry to composer.json, and no SSH/auth setup for a private Git host.

Where to look first, in order:

1. The service provider — check what the package auto-registers (extra.laravel.providers in its composer.json, or bootstrap/providers.php on Laravel 11+). That tells you whether collection is opt-in or always-on.
2. The published config — php artisan vendor:publish --tag=perf-collector-config (tag name may differ; run vendor:publish without a tag to list options). This is where sampling rate, thresholds, and output sinks live.
3. The middleware / listener registration — this is where you control which routes are measured. Start by measuring nothing and enabling one route.

First use case: point it at a single slow endpoint in a staging environment, collect one request cycle, and confirm the payload shape before wiring it into anything shared. A perf collector that writes on every request in production without sampling is a self-inflicted performance problem.

Implementation Patterns

Environment-scoped collection. The most common pattern is enabled in staging, sampled (or disabled) in production. Drive it from config backed by env vars so you can flip it per-environment without a deploy of code:

// config/perf-collector.php
'enabled' => env('PERF_COLLECTOR_ENABLED', false),
'sample_rate' => env('PERF_COLLECTOR_SAMPLE_RATE', 0.01),

Then set PERF_COLLECTOR_ENABLED=true only in .env.staging / your preview environments.

Route-level targeting over global middleware. Rather than instrumenting every request, register the collector against the routes you care about — queued jobs, webhooks, report endpoints. This keeps overhead bounded and the signal-to-noise ratio high. If the package ships middleware, alias it and attach it per-route-group instead of pushing it globally in bootstrap/app.php.

Correlate with your existing observability. A perf collector is most useful when its output can be joined to traces and logs. If it exposes a request/job identifier, propagate it into your logging context (or into a header) so a slow span in your APM maps directly to a collector record. If it has no such hook, add one at the boundary — typically a small middleware that stamps the current correlation ID into the collector's context before the measured work runs.

Wrap the noisy jobs. Queue workers are where per-request instrumentation breaks down: long-running processes, multiple jobs per process, memory that never resets. Measure at the job level (handle() entry/exit) rather than relying on request-scoped collection, and reset any per-job state the collector accumulates.

CI as the real consumer. The high-leverage pattern is not dashboards — it's a regression gate. Run a small benchmark suite in CI, collect with the package, and assert against a committed baseline. This is exactly what the maintainers do themselves (the notes mention CI covering Symfony 8.1), and it's the pattern that catches the "this query got 3x slower" class of bug before merge.

Version the config. Commit config/perf-collector.php rather than relying on package defaults. RC-to-stable upgrades in a 2.x line frequently adjust default thresholds, and a diffable config file turns a silent behaviour change into a review comment.

Gotchas and Tips

RC2 is a release candidate — constrain it exactly. composer require php-bug-catcher/perf-collector will not pick an RC by default under stable minimum-stability. Use the explicit :2.0.0-RC2 constraint, and expect to bump it by hand. Avoid ^2.0@RC in a shared codebase unless you're comfortable with RC3 landing unreviewed.

The Symfony 8 fix is a constraint change, not a code change. The maintainers state no source was modified and the existing suite passes on 8.1. That's reassuring for compatibility, but it also means Symfony 8-specific behaviour has only been exercised by their CI — not by you. Smoke-test your own slow paths on 8.1 before trusting the numbers, particularly anything touching the HTTP kernel or console output, where Symfony majors have historically shifted.

Upgrading from RC1: if RC1 resolved at all for you, RC2 is a no-op at runtime. The only change is the widened constraint plus the removed repositories block. If you previously installed via a VCS entry pointing at the Git host, delete that block from your root composer.json — leaving it in can shadow the Packagist package or pin you to a stale ref.

Don't confuse "installable" with "supported." Symfony 8 support means the constraint no longer blocks resolution. It does not imply the maintainers have tuned thresholds or sampling heuristics for your framework version. Treat collected baselines as environment-specific, not portable across a Symfony/Laravel major upgrade.

Watch for recursion. Collectors that measure the request lifecycle and also write results over HTTP, to a database, or through the queue can measure themselves. If you see suspiciously flat or doubled timings, disable the output sink and check whether collection is re-entering. Exclude the collector's own routes and any health-check endpoints from instrumentation.

Overhead is the failure mode. Verify the cost of collection on a hot path before enabling it broadly: benchmark with collection off, then on, on the same endpoint. If the delta is non-trivial, lower the sample rate rather than removing instrumentation — sparse data beats no data, and beats a slower application.

Debugging silently-missing data: in order — confirm the provider is registered (php artisan about on Laravel 11+ lists providers), confirm enabled resolves true in that environment (config('perf-collector.enabled') via tinker), confirm the route actually passes through the middleware (php artisan route:list -v), and only then look at the collector internals. Config caching (php artisan config:cache) is the usual culprit when a config edit appears to have no effect.

Extension points to favour: custom output sinks and threshold callbacks are the safest places to customise, since they sit at the edges of the package. Avoid subclassing internal collectors or relying on non-public properties — an RC in a 2.x line is precisely where those get reshuffled between releases, and the release notes give you no signal about the internal API's stability.