Perf Collector Bundle Laravel Package

Technical Evaluation

Evidence base: This assessment is derived from release metadata only (v2.0.0-RC2 notes). No source review, API documentation, or prior assessment exists. Confidence is correspondingly low; treat the risk items below as questions to close, not conclusions.

Architecture fit: php-bug-catcher/perf-collector is a performance-instrumentation package — inherently cross-cutting. Expect it to attach to the request lifecycle (kernel listeners/middleware), sample timings, and ship data to a local or remote store. That is architecturally cheap to add (no domain-model coupling) but broad in blast radius: it executes on every request in the hot path. Its Symfony constraint implies a Symfony bundle rather than a Laravel-native package; if we intend to run it inside Laravel, it will be pulling against the framework's pinned symfony/* component versions rather than sitting alongside them.

Integration feasibility: The RC2 change is purely dependency metadata — Symfony 8 is now allowed, CI covers 8.1, and no code changed. Practically this converts a hard install failure into a normal composer require. RC1 was uninstallable on the exact platform the package targets, so there is no meaningful migration population; for us this is a greenfield install either way.

Technical risk:

• Pre-GA status. 2.0.0-RC2 means the public API and configuration schema are not frozen. Anything we build against it may need rework at GA.
• Release-process signal. A release candidate that cannot be installed on its primary target platform indicates the constraint surface is not covered by CI at release time. RC2 fixes the symptom; the underlying hygiene question (does CI test the lower and upper bounds of the constraint matrix, not just the latest?) is unanswered.
• Symfony 8 requires PHP 8.4. The constraint bump silently raises our PHP floor if we adopt it on the Symfony 8 path.
• Distribution change. The VCS repository block is dropped in favour of Packagist. This is operationally an improvement, but it is also the point at which the package becomes a normal transitive dependency — version resolution now happens implicitly on every composer update.

Key questions:

1. Is this a Symfony bundle, a Laravel package, or framework-agnostic with a Symfony adapter? The framing and the constraint disagree; resolve before scoping.
2. What is the 2.0.0 GA timeline, and is there a documented BC policy between RC and GA?
3. Which PHP/Symfony versions are in the CI matrix — is 8.0 the floor, or is 8.1 the only tested version?
4. What is the overhead per request with collection enabled, and is sampling configurable?
5. What data is captured and where does it go — does it touch request payloads, headers, or user identifiers (PII/retention implications)?
6. Is the collector fail-open (never breaks the request) and is there a runtime kill switch?
7. Who maintains it, and what is the issue-response track record?

Integration Approach

Stack fit: If the application is Symfony 8, fit is native and the only question is bundle registration and config surface. If the application is Laravel, treat it as a third-party Symfony-component dependency: verify with composer why-not php-bug-catcher/perf-collector and composer depends symfony/http-kernel that the constraint set does not collide with the framework's pinned components. Laravel's own Symfony component versions lag the Symfony release train, so "supports Symfony 8" may not imply "installable in our Laravel version."

Migration path: There is no migration from RC1 — it could not be installed. Two realistic paths:

• Path A (adopt now): pin 2.0.0-RC2 exactly, do not use a ^2.0@RC range, and accept rework at GA.
• Path B (wait): track the repo, adopt at 2.0.0 GA. Preferred unless there is a concrete profiling need in the next few weeks.

Compatibility checks before any code: PHP floor (8.4 for Symfony 8), Symfony component range, and whether the package declares conflicts with common instrumentation peers (debug toolbars, APM agents, other profilers) — overlapping listeners are a classic source of duplicated timing and double-reported metrics.

Sequencing:

1. Composer spike on a throwaway branch: resolve, install, confirm the container/bundle boots. Cheapest possible kill test.
2. Enable in local/CI only, collection at 100%, confirm no functional test regressions and measure the overhead delta.
3. Staging with production-representative sampling; validate payload shape and storage volume.
4. Production, sampled, behind a feature flag with a disable path that does not require a deploy.
5. Re-evaluate at GA; only then widen the constraint to a caret range.

Operational Impact

Maintenance: Moving to Packagist removes the VCS repository stanza — a small but real win for composer.json hygiene and for onboarding. The offsetting cost is that we now inherit whatever the maintainer publishes. Pin via composer.lock, review lockfile diffs on update, and consider a private mirror or a version allowlist if this lands on the critical path.

Support: No prior assessment and no LTS signal. An RC with two iterations to fix an installability defect is not yet a track record. Assume no vendor support; the maintainer's responsiveness is itself a diligence item.

Scaling: Two axes. Per-request overhead scales linearly with traffic and is the more dangerous one since it sits in the hot path. Storage/ingest volume scales with request count times sampling rate; without sampling and asynchronous flushing, a collector can become a bottleneck it was deployed to diagnose. Establish the overhead budget (e.g. sub-millisecond p50 target) before enabling broadly.

Failure modes to design against:

• Collector throws mid-request → user-facing 500s. Verify fail-open behaviour explicitly; wrap or disable if unproven.
• Backend unavailable → synchronous flush turns into latency spikes and thread/worker exhaustion. Require async flush with bounded buffers.
• Unbounded buffer growth → memory pressure under sustained backend outage. Require a drop policy.
• Dependency resolution breakage → composer update fails or silently downgrades unrelated packages. This is precisely the RC1 failure mode, and it will recur if the package's constraint surface is loose in the other direction.
• Double instrumentation → duplicated spans and inflated metrics, usually diagnosed as "the collector is wrong" rather than "two collectors are running."

Ramp-up: Installation and boot is low effort — hours, not days. Interpreting the collected data and tuning sampling to a level that is informative without being expensive is the real work, and it is per-team. Budget a short enablement session for whoever owns performance, plus a written note on where the disable switch lives and when to use it.