Download the PHP package gomoob/php-websocket-server without Composer

Gomoob WebSocket server

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

Introduction

The Gomoob WebSocket server is a simple 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.

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.

Installation

Server side (run the server)

Running a server requires only one line of code.

Client side (PHP)

First pull the project with composer using the following dependency.

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

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.

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

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.

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.

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

Or in PHP with the client we provide.

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.

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

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

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.

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

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.

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

Then the followig Javascript peace of code will apply.

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

Docker container

To help you start quickly we also provide a Docker container here https://hub.docker.com/r/gomoob/php-websocket-server.

Release history

1.2.0 (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)

• 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)

• 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)

• 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)

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

1.0.0 (2016-08-17)

• First release.

About Gomoob

At Gomoob 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 [email protected] or by phone number (+33) 6 28 35 04 49.

Visit also http://gomoob.github.io to discover more Open Source softwares we develop.