Websocket Event processing

Introduction

This is a guide to explain how to connect a websocket to iland's event stream and process events.

To follow along with this example run the following command:

git clone https://github.com/ilanddev/php-examples.git

And then cd into the web-socket directory and open up the web-socket-example.php file to follow along.

Requirements

Besides the OAuth2 library that we use to authenticate we will also need a websocket client. I am using Pawl which is found here or can be installed using composer with this command:

composer require ratchet/pawl

Connecting the websocket

Connecting to the websocket is fairly simple with Pawl, all we need is the URI for the websocket we are connecting to. For iland's websocket I defined the websocket URI at the beginning with this code:

define('WS_URI', 'wss://api.ilandcloud.com/v1/event-websocket');

Now to connect the Pawl websocket client all we need to do is write this:

\Ratchet\Client\connect(WS_URI)->then(function($conn) {

Since we are interesting in more than just connecting to the websocket we must write our own definitions for when we receive a message.

Authenticating the client

The first message you should receive after connecting to iland's event websocket is AUTHORIZATION. This message indicates that we must send back an authorization token and the company id of the company we wish to process events for.

To get the company id we lazily grab the first one in the user's inventory. To learn how to get a user's inventory read here.

So with the company id and an access token sending the authorization looks like this:

$conn->on('message', function($msg) use ($conn) {
        if($msg == 'AUTHORIZATION') {
            $conn->send(sprintf('companyId=%s,Bearer %s', $GLOBALS['company_id'], getAccessToken()));
        } 

Getting events and processing them

After we are authenticated the next messages we will be receiving are going to be the events and tasks of the company you specified.

Since we are dealing with events in this example we need to make sure the message we get is an event and not a task we do this with the following code:

 $message = json_decode($msg);
            if($message->type == 'EVENT')

Looking at the documentation for what is returned in an event here we can see all the fields we can filter for and then process.

In this example I define some org and vm event types and then filter the event message with the following code:

$event = json_decode($msg)->data;
if (($event->entity_type == 'IAAS_VM' && in_array($event->type, $GLOBALS['vm_event_types'])) ||
    ($event->entity_type == 'IAAS_ORGANIZATION' && in_array($event->type, $GLOBALS['org_event_types']))) {

    echo sprintf('User %s initiated event %s for entity %s',
         $event->initiated_by_username, $event->type, $event->entity_name) . PHP_EOL;
}

Conclusion

To conclude this is a very basic PHP websocket client in the example that doesn't handle re-connects. In my research I found that not many people use PHP for websocket clients but opt to use Javascript instead.