Centrifugo Laravel Package

Technical Evaluation

Architecture Fit

• Real-Time Messaging: Centrifugo is a WebSocket/SSE server optimized for Laravel’s event-driven architecture, enabling pub/sub, presence tracking, and private channels—ideal for live notifications, chat, or collaborative tools.
• Decoupled Design: Centrifugo runs as a separate process (not PHP-bound), reducing PHP workload and enabling horizontal scaling. The package bridges Laravel events to Centrifugo channels via Symfony’s event system, aligning with Laravel’s modularity.
• Event-Driven Synergy: Leverages Laravel’s bus:subscribe/bus:publish to abstract Centrifugo’s API, reducing boilerplate for real-time features.

Integration Feasibility

• Laravel Compatibility: Requires PHP 8.4+ and Symfony 6.4+ (via baks-dev/core), which may conflict with older Laravel stacks (e.g., <10.x). Risk: Medium if using non-standard Symfony versions.
• Centrifugo Version Lock: Hardcodes Centrifugo 5.4, which lacks features from v6.x (e.g., Redis 7+ support). Risk: Low unless needing v6.x capabilities.
• Configuration Complexity: Requires manual .env setup and baks:assets:install, adding deployment friction. Risk: Low for devops teams; high for CI/CD pipelines.

Technical Risk

1. Dependency Conflicts:
   • baks-dev/core may introduce non-standard Symfony components (e.g., custom event dispatchers). Mitigation: Audit composer why baks-dev/core for conflicts.
2. Authentication Gaps:
   • Centrifugo’s token-based auth may not integrate with Laravel’s guards (e.g., Sanctum/Passport). Risk: Medium if custom middleware is needed.
3. Frontend Integration:
   • The package lacks bundled client SDKs; teams must manually integrate the Centrifugo JS client. Risk: Low if frontend teams are experienced.
4. Testing Coverage:
   • PHPUnit tests exist but may not cover edge cases (e.g., connection drops, rate limiting). Risk: Low if tests pass locally.

Key Questions

1. Value Over Direct Integration:
   • Does the package add Laravel-specific features (e.g., event bridges, admin UI), or is it a thin wrapper? Compare to laravel-centrifugo.
2. Scaling Assumptions:
   • How does it handle Centrifugo’s horizontal scaling (e.g., Redis clusters, multiple nodes)? Is load balancing supported?
3. Monitoring:
   • Are metrics (e.g., channel subscriptions, message throughput) exposed to Laravel’s tools (e.g., Horizon, Prometheus)?
4. Upgrade Path:
   • How will upgrades to Centrifugo 6.x or newer Laravel/Symfony versions be managed? Is the package actively maintained?
5. Alternatives:
   • For simpler use cases, could Laravel’s built-in Broadcasting (Pusher, Ably) suffice, or is self-hosted Centrifugo a hard requirement?

Integration Approach

Stack Fit

• Laravel Core: Works with Laravel 10.x+ (Symfony 6.4+ compatibility). Older versions may face dependency conflicts.
• Infrastructure:
  • Centrifugo Server: Must run separately (Docker recommended). Requires Redis (or PostgreSQL) for persistence.
  • Laravel: Needs Redis driver (BROADCAST_DRIVER=redis) and Centrifugo URL in .env (e.g., CENTRIFUGO_URL=ws://centrifugo:8000/connection/websocket).
• Frontend: Requires manual integration of the Centrifugo JS client for WebSocket/SSE connections.

Migration Path

1. Pre-Integration:
   • Deploy Centrifugo (Docker compose example in Centrifugo.md) and configure Redis.
   • Install the package: composer require baks-dev/centrifugo.
2. Configuration:
   • Run php bin/console baks:assets:install to set up bundle resources.
   • Update .env with Centrifugo connection details and Laravel event bus settings.
3. Core Integration:
   • Publish Events: Map Laravel events to Centrifugo channels:

     use BaksDev\Centrifugo\Event\CentrifugoEvent;
     event(new CentrifugoEvent('chat:room1', ['message' => 'Hello']));
     

   • Subscribe Clients: Frontend connects to Centrifugo’s WebSocket endpoint and subscribes to channels.
4. Testing:
   • Run php bin/phpunit --group=centrifugo to validate integration.
   • Test real-time flows (e.g., publish from Laravel, receive in frontend).

Compatibility

• Laravel Services:
  • Queue Workers: Use async event dispatching to avoid blocking (e.g., dispatchSync(false)).
  • Broadcasting: Overrides Laravel’s default broadcasting. Verify no conflicts with existing drivers.
• Centrifugo Features:
  • Supports private/public channels, presence, and history. Advanced features (e.g., proxy) may require custom config.
• Authentication:
  • Centrifugo uses JWT/API keys. The package may not integrate with Laravel’s auth; custom middleware may be needed.

Sequencing

1. Phase 1: Core Setup
   • Deploy Centrifugo + Redis.
   • Install and configure the Laravel package.
2. Phase 2: Event Integration
   • Map Laravel events to Centrifugo channels.
   • Test event publishing/receiving.
3. Phase 3: Frontend
   • Integrate Centrifugo JS client.
   • Implement UI for subscriptions/notifications.
4. Phase 4: Scaling
   • Load test Centrifugo (e.g., 10K+ connections).
   • Optimize Redis/Centrifugo config (e.g., num_connections, timeout).

Operational Impact

Maintenance

• Centrifugo Upgrades:
  • Package locks to Centrifugo 5.4; manual upgrades required. Monitor upstream releases for breaking changes.
• Dependency Management:
  • baks-dev/core may introduce maintenance overhead. Use roave/security-advisories to monitor for vulnerabilities.
• Configuration Drift:
  • Centrifugo’s config (e.g., Redis URL, JWT secret) must sync between Laravel and Centrifugo. Use secrets management (e.g., Vault, Laravel Envoy).

Support

• Debugging:
  • Centrifugo logs are separate from Laravel. Centralize logs (e.g., ELK stack) for correlation.
  • Common issues:
    • Connection drops: Check Centrifugo’s num_connections and Redis timeout.
    • Auth failures: Validate JWT/API key generation.
• Vendor Support:
  • Package has no stars/issues; rely on community or baks-dev support. Contribute to the repo for critical fixes.
• Documentation:
  • README is minimal. Supplement with:
    • Centrifugo’s official docs.
    • Laravel-specific examples (e.g., event-to-channel mapping).

Scaling

• Horizontal Scaling:
  • Centrifugo scales via load balancers (e.g., Nginx) and shared Redis. The package should support multiple instances if configured correctly.
  • Laravel’s event queue must handle increased load (e.g., database queue for high throughput).
• Performance Bottlenecks:
  • Redis: Use Redis Cluster for >10K channels.
  • Centrifugo: Monitor CPU/memory (default num_connections=10000 may need tuning).
  • Laravel: Ensure async event dispatching.
• Cost:
  • Self-hosted Centrifugo reduces cloud costs but adds ops overhead.

Failure Modes

Ramp-Up

• Team Skills:
  • Backend: Familiarity with Laravel events, Redis, and Symfony bundles.
  • Frontend: Experience with WebSocket/SSE and Centrifugo’s JS client.
  • DevOps: Docker, load balancing, and monitoring for Centrif