websocket_servers

Websocket Servers lets you run real-time WebSocket servers directly in Drupal using PHP (the Ratchet library). Define a server as configuration and attach behavior with pluggable handler plugins.

It gives your site a live, two-way channel to the browser — for chat, notifications, presence, live dashboards, or a streaming AI assistant — all within your Drupal/PHP stack. Describe a server as configuration, add a small handler plugin (or enable a bundled one), and manage each running instance from the back office or Drush.

Features

Define servers as configuration. A Websocket Server is an exportable config entity: give it a label, a machine name, and pick a handler. From each server you create one or more instances — the actual running endpoints.

Run instances with fine-grained control. Every instance has a unique port, an optional connection path, an enabled/disabled state, and optional HTTP Basic authentication on the handshake. The instances listing shows a live status dot, the ws:// URL, and the port.

• Pluggable behavior. Behavior comes from a WebsocketServerHandler attribute plugin type. Extend the provided base handler (which supplies sensible onOpen()/onClose()/onError() defaults) and implement onMessage() — that's the whole contract. Any module can ship handlers; they're auto-discovered.
• Permission-scoped execution ("run as"). Each instance can reference a Drupal user. While a handler processes events, it runs as that user (or as the anonymous user when none is set), so any content it reads or writes is bounded by that account's permissions and authored by it. This gives each socket a principled, least-privilege identity.
• Production-friendly runtime. Enabled instances are served by a single supervised manager process (Ratchet on ReactPHP, event-loop, non-blocking). You register one command with systemd or supervisor and it serves every enabled instance, reconciling automatically as you add, enable, disable, or change them.
• Back office + CLI. Manage servers, instances, and settings in the UI, or script everything with Drush (websocket:instance:create|enable|disable|delete|list, websocket:run, websocket:manager).

Bundled submodules (enable only what you need):

• Websocket Servers Example — a ready-made "Example websocket server" echo handler so you can test the full pipeline (configure → run → connect → message) in minutes, and a reference for writing your own.
• Websocket Servers Log — records client (received) and server (sent) messages and adds a Logs listing you can filter by instance and message type, with two toggles on the settings form.
• Websocket Servers AI — an "AI assistant handler" that forwards each client message to a selected AI assistant (via the AI module) and returns the reply. Because it runs under the instance's run-as user, the assistant only does what that account is allowed to do.

Typical use cases: live chat and support widgets, real-time notifications and presence, collaborative/live editing, streaming dashboards, pushing updates to a decoupled (headless) frontend, and conversational AI over a socket.

Post-Installation

Install with Composer (this also pulls in Ratchet) and enable the module:

composer require drupal/websocket_servers
drush en websocket_servers websocket_servers_example -y

Then go to Administration » Configuration » Web services » Websocket Servers (/admin/config/services/websocket-servers). You'll find tabs for Servers, Instances, and Settings (plus Logs if the log submodule is on).

1. You need at least one handler available. Enable Websocket Servers Example to start without writing code, or provide your own handler plugin.
2. Create a Websocket Server (label, machine name, handler).
3. Create an Instance: choose a free port, optionally a path, optional Basic-auth credentials, and optionally a "run as" user; then enable it.
4. Open the Settings page and register the supervised manager command with your process manager (systemd or supervisor) so it stays running — the page shows the exact command for your site, e.g.:
   

   drush --root=/var/www/html/web websocket:manager

5. Connect a WebSocket client to the instance URL shown in the list (ws://host:port/path) and start exchanging messages.

For local testing you can run a single instance in the foreground with drush websocket:run <id> instead of registering the daemon. WebSocket servers are long-lived processes that live outside the normal web request, so the supervised manager is how they're kept alive in production.

Similar projects

• Websocket
• Websockets

What's distinctive here is how Drupal-native it is: servers are config entities, instances are content entities with a back-office UI and Drush, behavior is a standard plugin type, and each socket can run under a specific Drupal user's permissions.

Supporting this Module

Maintaining and supporting this module takes time. If it helps your project, please consider contributing back — issues, patches, reviews are all welcome.

Buy me a coffee 🥤

Have a question, found a bug, or built a handler worth sharing? Open an issue in the project's issue queue — feedback and contributions are very welcome.