atipik/hoa-websocket-bundle

Atipik/HoaWebSocketBundle

, _(*1)

This bundle allows you to use Hoa/Websocket/Server and Hoa/Websocket/Client into Symfony2., _(*2)

With a simple configuration, you will be able to launch your WebSocket server, _(*3)

1. Installation

1.1 Update your composer.json

Add these lines to your require section:, _(*4)

{
    "require": {
        "atipik/hoa-websocket-bundle" : "1.*@dev"
    }
}

1.2 Install dependencies

composer update

1.3 Update your AppKernel.php file

<?php
# app/AppKernel.php
// ...

class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...
            new Atipik\Hoa\WebSocketBundle\AtipikHoaWebSocketBundle(),
            // ...
        );

        return $bundles;
    }

    // ...
}

1.4 Configure your project

To enable this bundle, you must add these lines in your config.yml:, _(*5)

# app/config/config.yml
atipik_hoa_web_socket: ~

You can also specify address and port., _(*6)

# app/config/config.yml
atipik_hoa_web_socket:
    address : 1.3.3.7
    port    : 4242

By default, server will be started on 127.0.0.1:8080, _(*7)

2. Architecture

The Symfony 2 command php app/console hoa:websocketserver has only one job: calling a runner., _(*8)

The runner links modules (your logic code) and WebSocket events which are managed by Atipik\Hoa\WebSocketBundle\WebSocket\Server., _(*9)

When the WebSocket server receives an event, the runner catches it and calls all subscribed modules., _(*10)

3. Server

3.1 Simple Usage

• In your bundle, create a class which extends Atipik\Hoa\WebSocketBundle\WebSocket\Module\Module:

<?php
# src/My/Bundle/WebSocket/Module/MyModule.php
namespace My\Bundle\WebSocket\Module;

use Atipik\Hoa\WebSocketBundle\WebSocket\Module\Module;

class MyModule extends Module
{
}

• Update your services.yml:

# src/My/Bundle/Resources/config/services.yml
services:
    my_bundle.my_module:
        class: My\Bundle\WebSocket\Module\MyModule
        tags:
            - { name: atipik_hoa_web_socket.module }

Don't forget to add atipik_hoa_web_socket.module tag !, _(*11)

• In this class, implement the getSubscribedEvents method:

<?php
# src/My/Bundle/WebSocket/Module/MyModule.php
namespace My\Bundle\WebSocket\Module;

use Atipik\Hoa\WebSocketBundle\WebSocket\Module\Module;

class MyModule extends Module
{
    public function getSubscribedEvents()
    {
        return array(
            'open'    => 'onOpen',
            'message' => 'onMessage',
        );
    }
}

• Add logic code:

You can get the current bucket by using $this->getBucket()., _(*12)

<?php
# src/My/Bundle/WebSocket/Module/MyModule.php
namespace My\Bundle\WebSocket\Module;

use Atipik\Hoa\WebSocketBundle\WebSocket\Module\Module;

class MyModule extends Module
{
    public function getSubscribedEvents()
    {
        return array(
            'open'    => 'onOpen',
            'message' => 'onMessage',
        );
    }

    public function onOpen()
    {
        $this->getLogger()->log('Here comes a new challenger !');
    }

    public function onMessage()
    {
        $data = $this->getBucket()->getData();

        $this->getLogger()->log(
            'Data received in %s: %s',
            __METHOD__,
            $data['message']
        );
    }
}

• Launch your WebSocket server:

php app/console hoa:websocketserver

3.2 Advanced Usage

3.2.1 Modules group

If you want to scale your server, you can affect modules to different group and launch server for one or more group., _(*13)

You can affect many modules in the same group, _(*14)

If you launch the server without group, all modules will be used., _(*15)

• Just override getGroup() method in your module:

<?php
# src/My/Bundle/WebSocket/Module/MyModule.php
namespace My\Bundle\WebSocket\Module;

use Atipik\Hoa\WebSocketBundle\WebSocket\Module\Module;

class MyModule extends Module
{
    // ...

    /**
     * Returns group name
     *
     * @return string
     */
    public function getGroup()
    {
        return 'foo';
    }

    // ...
}

• Launch your server by specifying group:

php app/console hoa:websocketserver -g foo

You can also specify more than one group:, _(*16)

php app/console hoa:websocketserver -g foo -g bar

3.2.2 Override runner class

If you want to modify how the runner works, you should override its class:, _(*17)

• Create a runner class that extends Atipik\Hoa\WebSocketBundle\WebSocket\Runner.
• Update your services.yml:

# src/My/Bundle/Resources/config/services.yml
parameters:
    atipik_hoa_web_socket.runner.class: My\Bundle\WebSocket\Runner

3.2.3 Override server class

If you want to modify how the WebSocket Server works, you should override its class:, _(*18)

• Create a server class which extends Atipik\Hoa\WebSocketBundle\WebSocket\Server.
• Update your services.yml:

# src/My/Bundle/Resources/config/services.yml
parameters:
    atipik_hoa_web_socket.server.class: My\Bundle\WebSocket\Server

3.2.4 Override node class

Hoa/Websocket allows you to override node class to add your own data., _(*19)

Of course, this bundle allow you to specify which class to use:, _(*20)

• Create a node class which extends Hoa\Websocket\Node:

<?php
# src/My/Bundle/WebSocket/Node.php
namespace My\Bundle\WebSocket;

class Node extends \Hoa\Websocket\Node
{
    protected $myData;

    public function getMyData()
    {
        return $this->myData;
    }

    public function setMyData($data)
    {
        $this->myData = $data;

        return $this;
    }

    public function doThingsWithMyData()
    {
        // ...
    }
}

• Update your services.yml:

# src/My/Bundle/Resources/config/services.yml
parameters:
    atipik_hoa_web_socket.node.class: My\Bundle\WebSocket\Node

• You can now access the current node, an instance of your node class:

<?php
# src/My/Bundle/WebSocket/Module/MyModule.php
namespace My\Bundle\WebSocket\Module;

use Atipik\Hoa\WebSocketBundle\WebSocket\Module\Module;

class MyModule extends Module
{
    // ...

    public function onEvent1()
    {
        // ...

        $node = $this->getNode();

        $node->setMyData('foobar');

        // ..
    }

    // ...

    public function onEvent2()
    {
        // ...

        $node = $this->getNode();

        $node->getMyData(); // contain 'foobar' set in event1

        // ..
    }

    // ...
}

4. Client

If you want to communicate with a WebSocket Server, you can use service atipik_hoa_web_socket.client by using $this->get('atipik_hoa_web_socket.client') in your controller or to inject this service directly in services.yml., _(*21)

For more documentation about WebSocket Client, see Hoa/WebSocket's documentation., _(*22)

5. Launch unit tests

composer update
./vendor/bin/atoum

6. More documentation

See Hoa/WebSocket's documentation) to know how to use How/WebSocket and to have an example of JavaScript code., _(*23)