WebSockets module, provides WebSockets integration into CleverStyle CMS both on server and on client

WebSockets server is running in background and listen for incoming connections.

It is highly recommended to have working exec() function in PHP (otherwise fallback will be used, but not guaranteed to work) and Nginx should be configured properly (Nginx config sample).

There are two ways to run WebSockets server:
CLI (recommended): php components/modules/WebSockets/supervisor.php 'php components/modules/WebSockets/start_cli.php https://example.com'
Where https://example.com is web-site address
CLI (multiple servers): php components/modules/WebSockets/supervisor.php 'php components/modules/WebSockets/start_cli.php https://example.com wss://server_address'
Similar to previous, but with additional parameter wss://server_address, where server_address should be an address via which one WebSockets server can reach another, for instance, it can be IP address of the server inside private network, also it might contain port number and path if needed.
Can be running on as many servers as needed.
Web: open https://example.com/WebSockets/security_key
Where https://example.com is web-site address, server should be running on every physical server if there are few of them.
And security_key should be replaced by security key from module settings.

Web will automatically switch to CLI if available. Also instead of supervisor.php you can use any other supervisor you like, no details here - you should know what to do.

Usage on server

When request comes from client, event WebSockets/message will be dispatched, where action is action that came from user.

Callback will receive as argument array with fields:

action
action that came from client
details
message for action that came from client
language
to handle multilingual features
user
user id
session
session id
connection
internal connection object (implements \Ratchet\ConnectionInterface)

NOTE: There is two specific system actions:

Client/authentication
Is generated when user passes authentication, useful as real connection event when we know who is actually connected
Client/disconnection
Is generated when connection to client closes by any reason

To send response back to client (or clients) \cs\modules\WebSockets\Server::instance()->send_to_clients($action, $details, $response_to, $target = false) method is used

Example:

	
<?php
use
	cs\Event,
	cs\modules\WebSockets\Server;
// Register actions
Event::instance()->on('WebSockets/message', function ($data) {
	if ($data['action'] !== 'hello') {
		return;
	}
	$Server = Server::instance();
	// Send `hello` action back to the same user with the same content
	if ($data['details']) {
		$Server->send_to_clients(
			'hello',
			$data['details'],
			Server::SEND_TO_SPECIFIC_USERS,
			$data['user'] // Back to the same user
		);
	} else {
		$Server->send_to_clients(
			'hello:error',
			$Server->compose_error(
				400,
				'No hello message:('
			),
			Server::SEND_TO_SPECIFIC_USERS,
			$data['user'] // Back to the same user
		);
	}
});
?>
	

::send_to_clients() method may be called anywhere, even on regular pages (for example, after AJAX request or just on page opening), also client will receive message even if he is connected to another server or have multiple tabs opened - response will be delivered to each tab.

Is response should represent error, :error suffix should be added to action and ::compose_error() method is used to compose generic error response if necessary.

Usage on client

If module depends on WebSockets module - connection with server will be established automatically and cs.WebSockets object will become available with next methods:

on(action, success, error)
Handler of server responses.
action - action from server, success and error are optional, you may specify any of them if you need
details from server will be passed into corresponding callback (if details is array - each element will be passed as separate argument
off(action, success, error)
Similar to on, but removes handler (it is possible to remove success or error handler only, both parameters are optional
once(action, success, error)
Similar to on, but removes handler after handling of first response
send(action, details)
Will send data to server

Example:

	
// Since everything is asynchronous - lets add handler first
cs.WebSockets.once('hello', function (message) {
	alert(message);
});
// Now send request to server
cs.WebSockets.send('hello', 'Hello, world!');