README

Introduction

This CakePHP 3 plugin gives you an easy way to add websocket capability to your web application.

Main Packages

• Cake Frontend Bridge
• Ratchet
• CakePHP Queuesadilla

Requirements

• CakePHP 3.3 or higher
• PHP 7.1

Usage in 4 easy steps

Note: You can checkout our CakePHP App Template for testing it on a clean app setup with preinstalled dependencies.

1. Define a new event

Example for websocket_events.php

...
'userDataUpdated' => [
    'audience' => [
        'includeAllNotAuthenticated' => false,
        'includeAllAuthenticated' => true
    ]
]
...

2. Publish the event in server context (e.g. Shell, Controller, Table...)

Example for UsersController.php

...
use Websocket\Lib\Websocket;
...
if ($this->Users->save($exampleUser)) {
    Websocket::publishEvent('userDataUpdated', ['editedUserId' => $exampleUser->id]);
}
...

3. Let the client receive the event and define a callback

Example for ../users/index_controller.js

...
App.Websocket.onEvent('userDataUpdated', function(payload) {
    if (payload.editedUserId === this.exampleUser.id) {
        alert('Someone changed the data of this user!');
    }
}.bind(this));
...

4. Run the websocket server shell and start testing!

$ bin/cake websocket_server

Installation

1. Require the plugin

You can install this plugin into your CakePHP application using composer.

The recommended way to install composer packages is:

composer require scherersoftware/cake-websocket

2. Load the plugin

The next step is to load the plugin properly inside your bootstrap.php:

Plugin::load('Websocket', ['bootstrap' => true, 'routes' => true]);

3. Configure app config

• File: /config/app.php

  <?php
  ...
  'Websocket' => [
      'ssl' => false,
      'host' => '127.0.0.1',
      'externalHost' => 'cws.dev',
      'port' => 8889,
      'frontendPath' => [
          'ssl' => [
              'path' => '/wss/',
              'usePort' => false
          ],
          'normal' => [
              'path' => '/',
              'usePort' => true
          ]
      ],
      'sessionCookieName' => 'cws',
      'Queue' => [
          'name' => 'websocket',
          'loopInterval' => 0.1,
      ]
  ]
  ...
  

4. Create and configure websocket events

• File: /config/websocket_events.php

  <?php
  return [
      'userDataUpdated' => [
          'audience' => [
              'includeAllNotAuthenticated' => false,
              'includeAllAuthenticated' => true
          ]
      ]
  ];
  

5. Configure AppController.php

In your src/Controller/AppController.php, insert the following pieces of code

Usage:

use Websocket\Lib\Websocket;

beforeFilter():

...
$this->FrontendBridge->setJson('websocketFrontendConfig', Websocket::getFrontendConfig());
...

6. Make the JS websocket lib globally accessible under App.Websocket

• Load the file /webroot/lib/websocket.js after loading the Frontend Bridge assets

7. Setup sessions properly if not alread done

Please follow the Cake Sessions Documentation

8. Setup Apache SSL ProxyPass if necessary

Make sure these modules are activated:

• mod_proxy.so
• mod_proxy_wstunnel.so

Edit your vhosts configuration and add this to the ssl section:

ProxyPass /wss/ ws://localhost:8889/

Roadmap

1.1.0

• Unit Tests
• Add a websocket_connections table which stores all active connections