Centrifugo Laravel Package

Technical Evaluation

What changed in 2.5.0

Architecture fit. The package occupies a narrow but load-bearing seam: PHP workers (RoadRunner) publish to Centrifugo over its HTTP/gRPC API via a RoadRunner plugin. It is not a general-purpose Centrifugo client — it only works inside a RoadRunner worker. That means the package version is effectively pinned to the RoadRunner major version, and any evaluation must treat the two as a single upgrade unit. There is no meaningful "just bump the library" path here.

Integration feasibility. Moderate. The code surface we touch is small (service config in .rr.yaml, one or two publisher call sites, a DI binding), but the blast radius is the whole request lifecycle because it rides on the application server. Two independent migrations are bundled into one release: a Composer identity change and a runtime major-version change. They should be evaluated and, where possible, executed separately.

Technical risk. High, concentrated in three places:

1. Rename mechanics are unverified. Whether this is a soft rename (replace directive, retained PSR-4 namespace) or a hard fork of the vendor path determines whether the change is a one-line composer.json edit or a codebase-wide use statement sweep. The release notes do not say. This is the single highest-value unknown.
2. RoadRunner v2 continuity. "Support RoadRunner v3" is ambiguous between additive (dual-version support in one branch) and replacement (v3-only). If additive, we can adopt the rename on our current runtime and defer the runtime upgrade. If replacement, 2.5.0 is unusable until we complete the RoadRunner upgrade, and 2.4.x becomes a de-facto frozen branch we must track for security patches ourselves.
3. Wire/config compatibility. RoadRunner v3 changes config schema, the goridge/worker protocol, health-check endpoints, and metrics surface. Centrifugo's own API version expectations may also have moved. Any mismatch shows up as worker crash-loops or silent publish failures, not compile errors — the worst failure class for a real-time feature.

Key questions for the maintainers

• Does 2.5.0 include a replace/provide for the old package name, and is the PHP namespace changed or aliased?
• Does 2.5.0 still run on RoadRunner v2? If not, what is the patch/security-support window for the 2.4.x line under the new name?
• Is there a documented migration guide covering .rr.yaml deltas and DI/service-provider registration?
• Which Centrifugo server versions and RoadRunner PHP worker SDK versions are in the tested matrix?
• Is the old Packagist entry going to be marked abandoned with the new name, and who controls publishing rights on roadrunner/*?

Integration Approach

Stack fit. This package is correct for our architecture if we are committed to RoadRunner as the application server for the services that publish to Centrifugo. It is not a fit for queue-worker or CLI contexts outside RoadRunner, and it should not be reused as a generic Centrifugo client elsewhere — a plain HTTP client is the right tool there. Confirm which services actually use it before scoping; the true footprint is usually smaller than the dependency graph suggests.

Migration path — two tracks, deliberately decoupled.

Track A: identity change (low risk, do first).

1. Confirm rename mechanics with maintainers (replace directive vs. hard namespace change).
2. Inventory every reference: composer.json across services, composer.lock, Dockerfiles, SBOM/vulnerability-scanning allowlists, internal runbooks, and any private package that depends on it transitively.
3. If soft rename: bump in one low-traffic service, verify autoload and publisher calls, then roll through the fleet. If hard rename: schedule as a coordinated PR per repo with a code-search-driven use statement rewrite.
4. Update internal allowlist/registry policy so the new vendor path isn't flagged by supply-chain controls.

Track B: RoadRunner v3 (high risk, gated).

1. Compatibility spike on a non-production service: RR v2 + package 2.4.x as baseline → RR v3 + package 2.5.0. Measure publish latency, error rate, worker restart behaviour, cold-start time.
2. Config translation — diff .rr.yaml between v2 and v3 for the Centrifugo plugin section and for server/rpc/log keys, and diff health/metrics endpoints.
3. Rollback rehearsal — confirm we can pin back to 2.4.x + RR v2 and redeploy within one release window.

Compatibility. Treat the PHP package, the RoadRunner binary, the RoadRunner PHP worker SDK, and the Centrifugo server as a four-way compatibility matrix. Pin all four explicitly in the service template and record the tested tuple. Do not allow floating ranges (^2.5) on any of them.

Sequencing.

1. Maintainer clarification (rename semantics, v2 support status).
2. Track A in a canary service.
3. Track A fleet-wide — now the rename cost is sunk while still on RR v2.
4. Track B spike; if clean, adopt in canary behind a feature flag.
5. Fleet rollout of Track B in the same window as an RR base-image update.
6. Retire internal references to the old package name and close out docs.

If the answer to "does 2.5.0 support RR v2" is no, invert: freeze on 2.4.x, start Track B immediately, and treat the rename as a rider on the runtime upgrade rather than a separate step.

Operational Impact

Maintenance. Two ongoing obligations instead of one. The rename means we now track a new Packagist identity, which resets our vulnerability-alerting history and dependency-bot baselines until the new package is registered in our tooling. Expect a short window where CVE alerts for this dependency silently stop firing — close that gap deliberately. If 2.4.x is maintained as a legacy branch under the old name, we inherit a second line to watch.

Support. The maintainer is the RoadRunner organisation, and the release cadence tracks RoadRunner releases rather than Centrifugo's. Support risk is therefore concentrated on RoadRunner's release discipline, not on this package's own code. Establish a documented policy: we support the RR major version we run, and we do not carry our own patches. If 2.4.x has no security-backport commitment, that policy forces the RR v3 upgrade onto a schedule rather than leaving it open-ended.

Scaling. No direct scaling change — throughput is governed by Centrifugo and by RoadRunner worker pool sizing. Two indirect effects to watch: (a) RoadRunner v3 may change worker pool defaults and idle/restart behaviour, which shows up as capacity shifts after deploy without any config change on our side; (b) if the publish path becomes goroutine/protocol-version sensitive, per-worker publish throughput may move at the tail rather than the median. Benchmark at target concurrency during the spike, not just smoke-test.

Failure modes.

Ramp-up. Low for engineers who already work with RoadRunner — the API is small and the migration is mostly configuration. Non-trivial for everyone else: the failure modes here are runtime-level and invisible in application code, so on-call needs the rollback procedure and the synthetic-probe dashboard, not just the changelog. Budget roughly a day of team education plus a written runbook covering the pinning policy, the four-way compatibility tuple, and the rollback path. Treat the "silent publish regression" case as the primary training scenario — it is the one that reaches production without an alert unless we instrument for it.