Ratchet

WampServer (Pub/Sub & RPC)

Purpose of this Component

The WAMP (WebSocket Application Messaging Protocol) specification gives developers (that's you!) a more structured and easy way for your client (JavaScript) and server (Ratchet-PHP) to interact.WAMP provides the RPC and PubSub patterns.WAMP specifies URIs for endpoint handles and JSON for payload transmissions. It is recommended taking a quick read over the WAMP Specification to get an understanding of how and why to use it.

If you choose to build your application on theWAMP spec (highly recommended) you will need a JavaScript library to implement the client side. AutobahnJS is a client to interact withWAMP servers and is highly recommended to use with Ratchet. Using AutobahnJS has a requirement of a deferred library. They recommend using when or jQuery's deferred library. The programming reference for AutobahnJS can be found on the Autobahn web site.

Note: Although the documentation specified to use URI's as Topic context, there is no enforcement on client or server; you can use any string to identify these topics.

Topics

The WampServer component provides a new class that is passed to your application: the Topic class. This is a container that stores all of the Connections who have subscribed to that topic. It also features some useful methods such as broadcast to send a message to every one of its subscribers.

When calling Connection methods that require "string $topic" you can pass the Topic class or its id.

If you are familiar with other forms of messaging, topics are equivalent to channels.

Events triggered by this Component

As found in the API Docs: Triggered events are propagated through a WampServerInterface object passed to the __construct.

  • onOpen (ConnectionInterface $conn) - A new client connection has been opened
  • onClose (ConnectionInterface $conn) - A client connection has been closed
  • onCall (ConnectionInterface $conn, string $id, Topic $topic, array $params) - The client has made an RPC to the server. You should send a callResult or callError in return
  • onSubscribe (ConnectionInterface $conn, Topic $topic) - The client has subscribed to a channel, expecting to receive events published to the given $topic
  • onUnsubscribe (ConnectionInterface $conn, Topic $topic) - The client unsubscribed from a channel, opting out of receiving events from the $topic
  • onPublish (ConnectionInterface $conn, Topic $topic, string $event) - The user publishes data to a $topic. You should in return an Event Command to Connections who have Subscribed to the $topic
  • onError (ConnectionInterface $conn, Exception $error) - An error has occurred with a Connection

Configuration methods

None

Functions callable on Connections

  • event (string $topic, string $msg) - Publish/Send data to a client that has subscribed to a topic
  • callResult (string $id, array $data) - A response to a client Call. Make sure to pass the corresponding $id from the onCall event
  • callError (string $id, string $topic, string $desc = '', string $details = null) - A response to the client after making a Call informing of an error processing the Call. Make sure to pass the corresponding $id from the onCall event
  • close - Gracefully close the connection to the client

Parameters added to each Connection

WAMP
(string $sessionId) - A unique ID given to the client
(array $subscriptions) - A collection of Topics the client has subscribed to

Wraps other components nicely

Wrapped by other components nicely

Usage 

<?php
// Your shell script
    $server = new \Ratchet\App('localhost');
    $server->route('/pubsub', new BasicPubSub);
    $server->run();

<?php
use Ratchet\ConnectionInterface as Conn;

/**
 * When a user publishes to a topic all clients who have subscribed
 * to that topic will receive the message/event from the publisher
 */
class BasicPubSub implements Ratchet\Wamp\WampServerInterface {
    public function onPublish(Conn $conn, $topic, $event, array $exclude, array $eligible) {
        $topic->broadcast($event);
    }

    public function onCall(Conn $conn, $id, $topic, array $params) {
        $conn->callError($id, $topic, 'RPC not supported on this demo');
    }

    // No need to anything, since WampServer adds and removes subscribers to Topics automatically
    public function onSubscribe(Conn $conn, $topic) {}
    public function onUnSubscribe(Conn $conn, $topic) {}

    public function onOpen(Conn $conn) {}
    public function onClose(Conn $conn) {}
    public function onError(Conn $conn, \Exception $e) {}
}