PHPackages                             gomoob/php-websocket-server - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. gomoob/php-websocket-server

ActiveLibrary[HTTP & Networking](/categories/http)

gomoob/php-websocket-server
===========================

WebSocket server with tags management, forward your messages on the right clients with ease !

1.2.0(9y ago)10623[4 issues](https://github.com/gomoob/php-websocket-server/issues)MITPHPPHP >=5.6

Since Aug 17Pushed 9y ago1 watchersCompare

[ Source](https://github.com/gomoob/php-websocket-server)[ Packagist](https://packagist.org/packages/gomoob/php-websocket-server)[ RSS](/packages/gomoob-php-websocket-server/feed)WikiDiscussions master Synced 4w ago

READMEChangelog (6)Dependencies (17)Versions (8)Used By (0)

Gomoob WebSocket server
=======================

[](#gomoob-websocket-server)

> WebSocket server with tags management, forward messages on the right clients with ease !

[![Total Downloads](https://camo.githubusercontent.com/5b902d557f20f85a394935085884b05b4bbb0934e1138ce35741cf1c4b305ac4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f676f6d6f6f622f7068702d776562736f636b65742d7365727665722e7376673f7374796c653d666c6174)](https://packagist.org/packages/gomoob/php-websocket-server)[![Latest Stable Version](https://camo.githubusercontent.com/cf44e8f421257b63d43b3e776405f2cb7d2dfe4482ded3044a5d50e843701efd/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f676f6d6f6f622f7068702d776562736f636b65742d7365727665722e7376673f7374796c653d666c6174)](https://packagist.org/packages/gomoob/php-websocket-server)[![Build Status](https://camo.githubusercontent.com/b076928b315a3eb1972f02c62044b10cd762f3784b91b8cd04c30f089ea1137b/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f676f6d6f6f622f7068702d776562736f636b65742d7365727665722e7376673f7374796c653d666c6174)](https://travis-ci.org/gomoob/php-websocket-server)[![Coverage](https://camo.githubusercontent.com/a73616752453f5f186c3b22f988605b29280c44e1c9f8c3af4a303531aa72352/68747470733a2f2f696d672e736869656c64732e696f2f636f766572616c6c732f676f6d6f6f622f7068702d776562736f636b65742d7365727665722e7376673f7374796c653d666c6174)](https://coveralls.io/r/gomoob/php-websocket-server?branch=master)[![Code Climate](https://camo.githubusercontent.com/a9c4bc3b77ee18875c95c28d59c97fcd9db7dabd7551ca65fd62e6e861550bbb/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636c696d6174652f6769746875622f676f6d6f6f622f7068702d776562736f636b65742d7365727665722e7376673f7374796c653d666c6174)](https://codeclimate.com/github/gomoob/php-websocket-server)[![License](https://camo.githubusercontent.com/a4ddd17277df888af16656b4d82c56ab530ca8250cd258c04ac6890924e38a97/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f676f6d6f6f622f7068702d776562736f636b65742d7365727665722e7376673f7374796c653d666c6174)](https://packagist.org/packages/gomoob/php-websocket-server)

Introduction
------------

[](#introduction)

The Gomoob WebSocket server is a simple [Ratchet](http://socketo.me "Ratchet") server which works with custom tags to easily forward messages to clients depending on custom tags.

As an example let's suppose we have a Web Application with English and French users. English users should receive English messages, French users should receive French messages.

Each application opens a Web Socket with a particular `language` tag.

```
// Web Application in English mode
var enWebSocket = new WebSocket('ws://localhost:8080?tags={"language":"EN}');

...

// Web Application in French mode
var frWebSocket = new WebSocket('ws://localhost:8080?tags={"language":"FR}');

...
```

On server side the Gomoob WebSocket server keeps track of the associations between tags and WebSocket connections. For example this simple PHP peace of code allows to easily forward a message to all clients connected with the `language=FR` tag.

```
// PHP Server (in most cases a Web Server) to Web Socket server client, allows to send one message which is forwared to
// several opened WebSocket connections
$phpClient = new WebSocketClient('ws://localhost:8080');
$phpClient->send(WebSocketRequest::create($message, ['language' => 'FR']);
```

Installation
------------

[](#installation)

### Server side (run the server)

[](#server-side-run-the-server)

Running a server requires only one line of code.

```
require __DIR__ . '/vendor/autoload.php';

echo "WebSocket server started, enter Ctrl+C to stop server." . PHP_EOL;
\Gomoob\WebSocket\Server\WebSocketServer::factory()->run();
```

### Client side (PHP)

[](#client-side-php)

First pull the project with composer using the following dependency.

```
{
    "require": {
        "gomoob/php-websocket-server": "^1.0.0"
    }
}
```

Then simply use the `\Gomoob\WebSocket\Client\WebSocketClient` class to send your messages.

```
// Open a Server / Server WebSocket connection
$phpClient = new WebSocketClient('ws://localhost:8080');

// Forward a message to all the WebSocket client connections associated to 'tag1' and 'tag2'
$response = $phpClient->send(
    WebSocketRequest::create(
        $message,
        [
            'tag1' => 'tag1Value',
            'tag2' => 'tag2Value'
        ]
    )
);
```

If you want to write solid unit tests we also provide the `\Gomoob\WebSocket\Client\WebSocketClientMock`class. This class is a utility mock which is very easy to use.

```
// Somewhere in our code we use a \Gomoob\WebSocket\IWebSocketClient ...
// We suppose this code is implemented in MyPowerfulService->serviceMethod();
$phpClient->send(WebSocketRequest::create('Message 0.')->setTags(['tag0' => 'tag0Value']));
$phpClient->send(WebSocketRequest::create('Message 1.')->setTags(['tag1' => 'tag0Value']));
$phpClient->send(WebSocketRequest::create('Message 2.')->setTags(['tag0' => 'tag0Value', 'tag1' => 'tag1Value']));

// Then we write a test case by replacing the real WebSocket client implementation with the mock one
class SampleTestCase extends TestCase
{
    public function setUp() {
        $this->webSocketClient = new WebSocketClientMock();
        $this->myPowerfulService->setWebSocketClient($this->webSocketClient);
    }

    public function testServiceMethod() {

        // Calls the method to test
        $this->myPowerfulService->serviceMethod();

        // Checks the right requests were sent
        $webSocketRequests = $this->webSocketClient->findByTags(['tag0' => 'tag0Value']);
		$this->assertCount(2, $webSocketRequests);
		$this->assertContains($webSocketRequest0, $webSocketRequests);
		$this->assertNotContains($webSocketRequest1, $webSocketRequests);
		$this->assertContains($webSocketRequest2, $webSocketRequests);
    }
}
```

Advanced configuration
----------------------

[](#advanced-configuration)

The default behavior of the Gomoob WebSocket server is the following !

- Expose port `8080` and authorize connections from all IP addresses (i.e `0.0.0.0`) ;
- Accept only plain string messages (exceptions are encountered if JSON messages are sent / received) ;
- Use a default PSR logger which output messages on the terminal ;
- Do not manage any authorization checks.

If one of those behaviors does not fit your need please read the following sub sections. You can also read the `src/test/server.php` file which shows how to start a server with custom message parsing and authorizations.

### Message parser

[](#message-parser)

By default the WebSocket server will accept plain string messages, if you try to send a JSON object then you'll encounter the following exception.

```
The 'message' property is not a string, you must configure a message parser to parse messages !

```

This is the expected behavior, if you want the server to manage custom PHP object messages then you have to :

- Make your PHP object messages extends `\JsonSerializable` and implement the `jsonSerialize()` method correctly ;
- Implement a custom message parser to create your custom PHP object messages when a plain JSON object is received.

A sample message object is provided in the `\Gomoob\WebSocket\Message\Message` class, feel free to read the associated source code to understand how it works. You'll also found a sample message parser in the `\Gomoob\WebSocket\Message\MessageParser`.

To explain how to manage custom PHP object messages let's suppose we have the following message object to send.

```
class MyMessage {
    private $messageProperty1;
    public function __construct($messageProperty1) {
        $this->messageProperty1 = $messageProperty1;
    }
    public function getMessageProperty1() {
        return $this->messageProperty1;
    }
}
```

Sending such a message in a browser on Javascript would require the following code.

```
var socket = new WebSocket('ws://localhost:8080');
socket.send(
    JSON.stringify(
        {
            message : {
                messageProperty1 : "Hello !"
            },
            tags : {
                tag1 : 'tag1Value'
            }
        }
    )
);
```

Or in PHP with the client we provide.

```
WebSocketClient::factory('ws://localhost:8080')->send(WebSocketRequest::create(new MyMessage('Hello !')));
```

As this this will not work because on server side the Gomoob WebSocket server will not know how to parse the messages and how to re-create those messages to forward them to clients who opened WebSocket connections.

The first thing to do is to implement the `\JsonSerializable` class and the `jsonSerializeMethod()` in our `MyMessage` class.

```
class MyMessage implements \JsonSerializable {
   ...
   public function jsonSerialize() {
       return [
           'messageProperty1' => $this->messageProperty1;
        ];
   }
}
```

Then we have to implement a message parser by extending the `\Gomoob\WebSocket\IMessageParser` class.

```
use Gomoob\WebSocket\IMessageParser;

class MyMessageParser implement IMessageParser {
    public function parse(array $arrayMessage)
    {
        // Ensure the array contains only valid key names
        foreach (array_keys($arrayMessage) as $key) {
            if (!is_string($key) || !in_array($key, ['messageProperty1'])) {
                throw new \InvalidArgumentException('Unexpected property \'' . $key . '\' !');
            }
        }

        // The 'messageProperty1' property is mandatory
        if (!array_key_exists('messageProperty1', $arrayMessage)) {
            throw new \InvalidArgumentException('No \'messageProperty1\' property found !');
        }

        return new MyMessage($arrayMessage['messageProperty1']);
    }
}
```

Finally we have to provide our parser when we create our WebSocket server.

```
WebSocketServer::factory(
    [
    	'messageParser' => new MyMessageParser()
    ]
)->run();
```

### Authorization Manager

[](#authorization-manager)

By default the WebSocket server will accept all connections and message sendings, in most cases this behavior is not expected because anybody could open a WebSocket on your server and try to forward messages to all connected clients without authorization.

You can implement a custom authorization manager by implementing the `\Gomoob\WebSocket\IAuthManager`interface, this interface has the following signature.

```
/**
 * Interface which defines an authorization manager. An authorization manager allows to control authorization while
 * opening Web Socket connections and sending messages over Web Sockets.
 *
 * @author Baptiste Gaillard (baptiste.gaillard@gomoob.com)
 */
interface IAuthManager
{
    /**
     * Function used to indicate if connection opening is authorized.
     *
     * @param \Ratchet\ConnectionInterface $connection the current Ratchet connection.
     *
     * @return boolean `true` if the connection opening is authorized, `false` otherwise.
     */
    public function authorizeOpen(ConnectionInterface $connection);

    /**
     * Function used to indicate if message sending is authorized.
     *
     * @param \Ratchet\ConnectionInterface $connection the current Ratchet connection.
     * @param \Gomoob\WebSocket\IWebSocketRequest $webSocketRequest the current Gomoob WebSocket request.
     */
    public function authorizeSend(ConnectionInterface $connection, IWebSocketRequest $webSocketRequest);
}
```

So its very easy to manage authorizations, just return `true` or `false` with the `authorizeOpen(...)` or `authorizeSend(...)` functions.

#### The `ApplicationsAuthManager`

[](#the-applicationsauthmanager)

To easier authorization we provide an authorization manager which allows to declare several applications with `key`and `secret` properties.

This authorization manager is available in the `\Gomoob\WebSocket\Auth\ApplicationsAuthManager` class, it works with a very simple YAML configuration file.

Here is a sample instanciation of the manager with a WebSocket server.

```
WebSocketServer::factory(
    [
    	'authManager' => ApplicationsAuthManager::factory(
    	    [
    	        'authorizeOpen' => false,
    	    	'configurationFile' => __DIR__ . '/auth.yml'
    	    ]
    	)
    ]
)->run();
```

The content of the `auth.yml` file could be the following.

```
applications:
  -
    key: application1
    secret: B4ajW3P7jfWEYPZsQV8mnteHg97G67uW
    authorizeOpen: true
  - key: application2
    secret: 33yLWdynhaqm9tYjDFKf8gB8zmAPKdDP
    authorizeOpen: false
```

Then the followig Javascript peace of code will apply.

```
// Does not work because required 'key' and 'secret' URL parameters are not provided
var socket1 = new WebSocket('wss://myserver.org:8080');

// Works because the 'key' and 'secret' URL parameters provided are valid
var socket2 = new WebSocket('wss://myserver.ord:8080?key=application1&secret=B4ajW3P7jfWEYPZsQV8mnteHg97G67uW');

// Does not work because the request does not provide the 'key' and 'secret' properties
socket2.send(
    JSON.stringify(
        {
            message : {
                messageProperty1 : "Hello !"
            }
        }
    )
);

// Works because the request provides valid 'key' and 'secret' properties
socket2.send(
    JSON.stringify(
        {
            message : {
                messageProperty1 : "Hello !"
            },
            metadata : {
                key : 'application2',
                secret : '33yLWdynhaqm9tYjDFKf8gB8zmAPKdDP'
            }
        }
    )
);
```

The same rules are also applicable with the PHP client we provide.

```
WebSocketClient::factory('ws://localhost:8080')->send(
    WebSocketRequest::create(
        new MyMessage('Hello !')
    )->setMetadata(
        [
            'key' => 'application2',
            'secret' => '33yLWdynhaqm9tYjDFKf8gB8zmAPKdDP'
        ]
    )
);
```

Docker container
----------------

[](#docker-container)

To help you start quickly we also provide a Docker container here .

Release history
---------------

[](#release-history)

### 1.2.0 (2016-08-23)

[](#120-2016-08-23)

- Moves the `TagsTree` class to `\Gomoob\WebSocket\Util\TagsTree` ;
- Add a new `TagsTree->reset()` method ;
- Add a new `\Gomoob\WebSocket\Client\WebSocketClientMock` class to easier unit testing ;
- Update composer dependencies.

### 1.1.0 (2016-08-18)

[](#110-2016-08-18)

- Add more PHP Documentor documentation about the goals of `metadata` in the `\Gomoob\WebSocket\IWebSocketRequest` interface and the `\Gomoob\WebSocket\Request\WebSocketRequest` class ;
- Add management of `defaultMetadata` in the `\Gomoob\WebSoscket\IWebSocketClient` interface and the `\Gomoob\WebSocket\Client\WebSocketClient` class ;
- Add management of `defaultTags` in the `\Gomoob\WebSocket\IWebSocketClient` interface and the `\Gomoob\WebSocket\Client\WebSocketClient` class ;
- Improve `\Gomoob\WebSocket\Message\Message` serialization ;
- Improve `\Gomoob\WebSocket\Request\WebSocketRequest` serialization ;
- Now all the factory methods can be calls with a `factory(...)` method or an alias `create(...)` method.

### 1.0.3 (2016-08-17)

[](#103-2016-08-17)

- Fix `port` and `address` options problems while creating a `WebSocketServer`, the parameter were not transmitted to the Ratchet server ;
- Now the default port number is `80` which is the default Ratchet server port.

### 1.0.2 (2016-08-17)

[](#102-2016-08-17)

- Add missing `symfony/yaml` composer dependency, otherwise problems was encountered while running `composer update --no-dev` ;
- Add missing `monolog/monolog` composer dependency, , otherwise problems was encountered while running `composer update --no-dev`.

### 1.0.1 (2016-08-17)

[](#101-2016-08-17)

- Configure specific Eclipse validator rules ;
- Add MIT license.

### 1.0.0 (2016-08-17)

[](#100-2016-08-17)

- First release.

About Gomoob
------------

[](#about-gomoob)

At [Gomoob](https://www.gomoob.com) we build high quality software with awesome Open Source frameworks everyday. Would you like to start your next project with us? That's great! Give us a call or send us an email and we will get back to you as soon as possible !

You can contact us by email at  or by phone number (+33) 6 85 12 81 26 or (+33) 6 28 35 04 49.

Visit also  to discover more Open Source softwares we develop.

###  Health Score

29

—

LowBetter than 57% of packages

Maintenance12

Infrequent updates — may be unmaintained

Popularity19

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity63

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

6

Last Release

3600d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/4852e6f187378c657f58d61a19e474105855a236b23255204baf14218c5c657f?d=identicon)[bgaillard](/maintainers/bgaillard)

![](https://www.gravatar.com/avatar/22dd33f77ada75e74bcd51e4a573d8ad99d13586c8220c5c5eb9228fc5eb3b03?d=identicon)[simonbaudry](/maintainers/simonbaudry)

---

Top Contributors

[![bgaillard](https://avatars.githubusercontent.com/u/1327782?v=4)](https://github.com/bgaillard "bgaillard (32 commits)")

---

Tags

gomoobphpratchetwebsocketwebsocket-serverwebsocketRatchetgomoob

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/gomoob-php-websocket-server/health.svg)

```
[![Health](https://phpackages.com/badges/gomoob-php-websocket-server/health.svg)](https://phpackages.com/packages/gomoob-php-websocket-server)
```

###  Alternatives

[craftcms/cms

Craft CMS

3.6k3.6M3.0k](/packages/craftcms-cms)[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k13](/packages/tempest-framework)[phpro/grumphp

A composer plugin that enables source code quality checks.

4.3k16.7M997](/packages/phpro-grumphp)[pimcore/pimcore

Content & Product Management Framework (CMS/PIM/E-Commerce)

3.8k3.8M495](/packages/pimcore-pimcore)[shopware/platform

The Shopware e-commerce core

3.4k1.5M3](/packages/shopware-platform)[gos/web-socket-bundle

Symfony Web Socket Bundle

6202.2M8](/packages/gos-web-socket-bundle)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)