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).
php components/modules/WebSockets/supervisor.php 'php components/modules/WebSockets/start_cli.php https://example.com'
https://example.com
is web-site addressphp components/modules/WebSockets/supervisor.php 'php components/modules/WebSockets/start_cli.php https://example.com wss://server_address'
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.https://example.com/WebSockets/security_key
https://example.com
is web-site address, server should be running on every physical server if there are few of them.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.
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
details
language
user
session
connection
\Ratchet\ConnectionInterface
)NOTE: There is two specific system actions:
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.
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)
action
- action from server, success
and error
are optional, you may specify any of them if you needdetails
from server will be passed into corresponding callback (if details
is array - each element will be passed as separate argumentoff(action, success, error)
on
, but removes handler (it is possible to remove success
or error
handler only, both parameters are optionalonce(action, success, error)
on
, but removes handler after handling of first responsesend(action, details)
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!');