Swoole Blackfire Laravel Package

Product Decisions This Supports

• Observability stack selection for Octane/Swoole: Informs whether Blackfire can remain part of our performance tooling once Laravel runs on Swoole (Octane, Hyperf, or custom Swoole servers), where the standard PHP-FPM-oriented Blackfire probe does not attach cleanly to persistent workers and coroutines.
• Runtime migration risk: De-risks the PHP-FPM → Octane/Swoole migration by confirming we can still profile per-request in the new runtime; "can we observe it?" is a gating question for that roadmap item.
• Build vs. buy for profiling glue: This is a thin integration layer, not a profiler. The decision is whether to adopt an existing bridge versus maintaining an in-house Swoole probe — a classic low-differentiation build-vs-adopt call.
• Vendor/tooling evaluation: Supports comparing Blackfire against Tideways, Xdebug/XHProf, and OpenTelemetry-based APM in a coroutine environment, where compatibility — not features — is often the deciding factor.
• Performance budget enforcement and incident triage: Enables per-request flame graphs and profile comparisons in staging/pre-prod for long-lived worker processes, feeding regression gates and post-incident reviews.
• Platform capability roadmap: Informs whether first-class profiling for Octane workloads is worth investing in as a platform team offering versus leaving to individual squads.

When to Consider This Package

Adopt (or trial) when:

• You run Laravel Octane on the Swoole runtime (or another Swoole-based PHP server) in staging or production.
• You already use or are trialing Blackfire and need it to function under persistent workers and coroutines rather than the classic request lifecycle.
• You want per-request profiling without writing and maintaining your own Swoole probe integration.
• You can pin the version and accept a thin, replaceable dependency — this is glue code, not a system of record.

Look elsewhere when:

• You are on standard PHP-FPM — the native Blackfire extension covers this; no bridge needed.
• You run Octane on RoadRunner — this integration targets Swoole specifically.
• You require vendor SLA or long-term support — 22 stars and 0 dependents signal high bus-factor and abandonment risk; prefer Blackfire's own Swoole guidance/agent, Tideways, or an OpenTelemetry-native approach.
• You need open-source-only or OTel-native telemetry end to end.
• You are not paying for Blackfire — Xdebug/XHProf remain cheaper for local development.

How to Pitch It (Stakeholders)

For executives: As we modernize Laravel onto Octane/Swoole for throughput, our existing profiler stops seeing individual requests — we would be flying blind on performance exactly when the runtime changes most. This package is a small, permissively licensed (Apache-2.0) bridge that restores Blackfire profiling in that environment without custom engineering. It is low-cost to adopt and easy to remove. The trade-off is maturity: a small community and no dependents, so we treat it as a thin, pinned, replaceable dependency — not a strategic commitment — and confine it to non-production or gated production use until proven.

For engineering: It solves one specific problem — Blackfire's probe assumes the PHP-FPM request lifecycle, which Swoole's persistent workers and coroutines break. Rather than hand-rolling instrumentation, this wires the two together so you get per-request profiles in Octane/Swoole. Use it in staging and pre-prod for regression baselines and incident triage; pin the version, wrap it behind our observability configuration, and be prepared to fork or replace it if upstream goes quiet. It is not an APM replacement — it is the compatibility shim that keeps our existing profiler useful.