Centrifugo Bundle Laravel Package

Technical Evaluation

Architecture fit

• The package is a Symfony bundle, not a Laravel package. It ships a Bundle subclass registered through Symfony's kernel, a DependencyInjection extension with a config tree, and services auto-wired via the Symfony container. None of that lifecycle exists in Laravel, so it cannot be composer required and used as-is in a Laravel application.
• Architecturally, the underlying concern is small and well-bounded: Centrifugo is a standalone Go WebSocket server, and the PHP side only needs to (a) mint connection/subscription JWT or HMAC tokens and (b) call the HTTP API (/api/publish, /api/broadcast, /api/presence, /api/history). That is a thin HTTP client plus a token signer — roughly a few hundred lines. The bundle is mostly DI plumbing around that.
• Fit is therefore good conceptually, poor mechanically for a Laravel stack. The value is the reference implementation of the protocol, not the packaging.

Integration feasibility

• Low-friction options, in order of preference:
  1. Use a maintained, framework-agnostic PHP client (or plain Guzzle/Http:: calls) and write ~1 Laravel service provider + config file.
  2. Fork this repo, strip the Symfony DI layer, and port the client/signer into a CentrifugoService bound in a Laravel provider.
  3. Only if the target app is actually Symfony: install directly and register the bundle.
• Direct adoption requires pulling in symfony/http-kernel, symfony/dependency-injection, and symfony/config. Laravel already depends on some Symfony components, but not the bundle/kernel contracts, so you would be adding framework surface area for no benefit.

Technical risk

• Adoption signal is weak: 11 stars, 0 dependents, score 0.085. This looks like an internal extraction from Kismia's own stack rather than a community project. Assume no upstream support and budget for owning the code.
• Version drift is the top risk: Centrifugo's HTTP API and token format changed across v2 → v3/v4/v5 (e.g., api_key-style auth vs. token-based API auth, JWT claim names, info/b64info handling). A bundle of this age may target an older Centrifugo. Verify before committing.
• Unverified hygiene: no visible CI, test suite, security policy, or docs in the brief. Composer constraints (PHP and Symfony versions) are unknown and may pin you to EOL runtimes.
• Bundle-specific risk: implicit container wiring and config defaults can mask misconfiguration (e.g., wrong secret, wrong API endpoint) until runtime.

Key questions

• Which Centrifugo server versions does this bundle target, and does it support token-based API auth?
• Does it cover both connection JWT and API requests, or only one side?
• What are the composer.json PHP/Symfony constraints, and is the license permissive (MIT)?
• Does it implement presence/history, or only publish?
• Is there any commit activity in the last 24 months? Any tagged release?
• Is the team's actual target a Laravel app or a Symfony app? (This determines whether the package is even relevant.)

Integration Approach

Stack fit

• If the target is Laravel: do not adopt the package as a dependency. Treat it as a protocol reference. Implement a small CentrifugoClient (publish/broadcast/presence/history) and a CentrifugoTokenService (JWT signing with the shared secret), bound as singletons in a service provider with a config/centrifugo.php (endpoint, API key, HMAC secret, token TTL).
• If the target is Symfony: install directly, register the bundle, and publish/validate config. Risk drops to version compatibility only.

Migration path

1. Spike (1–2 days): read the bundle source, confirm which Centrifugo endpoints and token claims it uses, and diff against your deployed Centrifugo version.
2. Decide build vs. adopt: for Laravel, build the thin wrapper (est. 1–3 dev-days). For Symfony, adopt and pin.
3. Introduce behind an interface: define RealtimePublisher / RealtimeTokenIssuer contracts in your domain so the transport is swappable and testable with a fake.
4. Retire the dependency if forked — keep it as an internal package under your org rather than a tagged third-party require.

Compatibility

• Confirm PHP runtime (8.1+ required for modern Laravel; the bundle may declare 7.x).
• Confirm Centrifugo server version and API auth mode; align JWT claims (sub, exp, info) with client-side expectations.
• Ensure the HTTP client honors your platform's TLS, proxy, and timeout conventions.

Sequencing

1. Token issuance first — stateless, read-only, easiest to validate with a single WebSocket client.
2. Backend publish from domain events, initially synchronous in a queue worker.
3. Presence/history last — highest coupling to Centrifugo version and least critical.

Operational Impact

Maintenance

• Effectively you own it. With 0 dependents and 11 stars, there is no community to absorb upgrades. Plan for a named owner and a fork under your GitHub org.
• Budget roughly 1–2 days per year for dependency bumps, plus ad-hoc work on Centrifugo server upgrades.

Support

• No vendor SLA, no security disclosure process, no issue triage. Any CVE in the HTTP client or JWT library surfaces through your own dependency tree, not the bundle's.
• Documentation is likely thin; onboarding relies on reading source.

Scaling

• The PHP side is thin and stateless — it scales linearly with your app tier; the real fan-out load sits on Centrifugo (which handles it well). The publish path is an outbound HTTP call: watch connection pooling, timeouts, and worker concurrency.
• Token issuance is cheap (HMAC/JWT sign) and cacheable; keep TTLs short enough to allow secret rotation without mass disconnects.

Failure modes

• Centrifugo unavailable → publish calls fail. Publish must be fire-and-forget from a queued job with retry/backoff, never inline in a user request.
• Secret mismatch or rotation → all WebSocket handshakes fail with opaque 401s; token TTL and dual-key rollout need an explicit runbook.
• Clock skew → JWT exp/nbf validation fails intermittently across hosts; enforce NTP.
• API version drift → silent 400/404s on publish after a server upgrade; add contract tests against a pinned Centrifugo container in CI.
• Misconfiguration masked by DI defaults → wrong endpoint/secret discovered only in staging; add a startup health check that pings the API.

Ramp-up

• Technically shallow: a mid-level dev can read the bundle and reproduce it in a day. The real cost is organizational — accepting ownership of an unmaintained, single-vendor artifact for a small amount of glue code. Recommendation: for a Laravel stack, skip the dependency, port the logic, and spend the saved risk budget on Centrifugo-side operability (HA, monitoring, secret rotation).