Clank Bundle Laravel Package

Getting Started

ClankBundle is a Symfony2 bundle, not a Laravel package, so "getting started" in a Laravel app really means deciding whether you are going to vendor the bundle or mine it for parts. First moves:

1. Read the source before installing. With 0 stars and 0 dependents, treat the repo as reference code, not a dependency. The interesting pieces are the TopicManager, the RPC/periodic service abstractions, and the ClankServer console command that wraps Ratchet\Server\IoServer.
2. Check PHP/Symfony constraints. It targets Symfony 2.x and PHP 5.x-era Ratchet (cboden/ratchet ~0.3). Modern PHP 8 will usually install after adding "cboden/ratchet": "^0.4" in your root composer.json and allowing the bundle with --ignore-platform-reqs for the Symfony constraints, but expect friction.
3. Run the bundled server command standalone. The bundle ships a clank:server console command. The fastest sanity check is to clone the repo, point bin/console at a throwaway Symfony 2 skeleton, and confirm the Ratchet loop boots and accepts a socket.
4. First real use case: topic-based pub/sub. A client connects, subscribes to a topic, and the server pushes messages to everyone subscribed. That's the one feature most teams actually want from this codebase.

In Laravel terms, the equivalent day-one setup is: composer require cboden/ratchet directly, write an artisan clank:serve command modeled on the bundle's server command, and copy the TopicManager into app/WebSockets/.

Implementation Patterns

The bundle's opinionated patterns are worth borrowing even if you never install it as a bundle.

• Server command as the process entrypoint. One long-running artisan/console command owns the Ratchet loop. Schedule restarts via Supervisor. Treat it like a queue worker, not a web request.
• Topic manager for fan-out. Wrap Ratchet's ConnectionInterface collection behind a topic abstraction so controllers/services publish to topic:orders rather than iterating connections. Emit on subscribe, unsubscribe, and disconnect.
• RPC handlers. The bundle exposes a pattern where the JS client calls a named method and the server routes to a service. In Laravel, model this as invokable classes registered in a WsRpcRegistry and resolved from the container.
• Periodic services. A timer that fires every N seconds to push updates (heartbeats, price ticks). Implement with React\EventLoop\LoopInterface::addPeriodicTimer. Keep the callback short; it blocks the whole loop.
• Session bridging. The bundle's session provider hands the Symfony session into the WS connection so $conn->Session->get('user_id') works. In Laravel you'd do the same by reading a signed token/handshake cookie in onOpen and storing identity on the connection object yourself.
• Integration with the HTTP app for publishing. Use Redis pub/sub (or a broadcast() event) so HTTP requests can nudge the WS loop. ClankBundle assumes in-process publishing; a multi-process setup needs an external bus.
• Client side. The bundle expects a small JS helper that opens the socket, subscribes to topics, and dispatches RPC responses to callbacks. Any modern client (WebSocket + JSON envelopes) is fine; you're not locked into theirs.

Gotchas and Tips

• It is not a Laravel package. There's no service provider, no facade, no config publishing. You will be porting. Budget for that up front.
• Symfony2 is EOL. The bundle's config tree, container compilation, and event system target dead APIs. Expect to delete the bundle skeleton and keep the handler classes.
• Zero stars, zero dependents. No community to lean on. Pin Ratchet to a version you tested and vendor the copied files under app/ so upstream abandonment doesn't block you.
• Long-running process leaks. Ratchet connections and topic lists grow forever if you only remove on onClose. Log count($connections) periodically; a memory creep here is almost always a topic that never prunes.
• Blocking the loop. Any synchronous DB or HTTP call inside onMessage or a periodic timer stalls every connected client. Push heavy work to a queue (dispatch()->onQueue('ws')) and publish from the worker.
• Session/auth edge cases. Handshake cookies are sent once; reconnects can carry stale sessions. Re-auth on reconnect, and don't trust Session after a token expires mid-connection.
• Debugging. Ratchet\Server\IoServer logs to stderr by default; wire a Psr\Log implementation (Monolog) through the server command rather than echo. Use a raw wscat -c ws://localhost:8080 to isolate server bugs from JS bugs.
• Extension points that stay useful after porting: topic lifecycle hooks (onSubscribe, onUnsubscribe), the RPC dispatcher contract, and the periodic-service interface. Everything else is Symfony2 glue.
• Consider the alternatives before porting. cboden/ratchet directly, beyondcode/laravel-websockets (Pusher protocol, works with Laravel Echo), or moving to a managed service (Soketi, Pusher, Ably) is usually less work than reviving a dormant Symfony2 bundle in a Laravel codebase.
• If you do install it, run it in an isolated Symfony 2 process and connect Laravel to it over Redis pub/sub. Don't try to boot the bundle inside a Laravel artisan command — the container and kernel assumptions will fight you.