Download the PHP package elephantio/elephant.io without Composer

Elephant.io

Installation

We are suggesting you to use composer, using composer require elephantio/elephant.io. For other ways, you can check the release page, or the git clone urls.

Usage

To use Elephant.io to communicate with socket.io server is described as follows.

Options

Elephant.io accepts options to configure the internal engine such as passing headers, providing additional authentication token, or providing stream context.

• headers

  An array of key-value pair to be sent as request headers. For example, pass a bearer token to the server.

• auth

  Specify an array to be passed as handshake. The data to be passed depends on the server implementation.

  On the server side, those data can be accessed using:

• context

  A stream context options for the socket stream.

• persistent

  The socket connection by default will be using a persistent connection. If you prefer for some reasons to disable it, set persistent to false.

• reuse_connection

  Enable or disable existing connection reuse, by default the engine will reuse existing connection. To disable to reuse existing connection set reuse_connection to false.

• transports

  An array of enabled transport. Set to null or combination of polling or websocket to enable specific transport.

• transport

  Initial socket transport used to connect to server, either polling or websocket is supported. The default transport used is polling and it will be upgraded to websocket if the server offer to upgrade and transports option does not exclude websocket.

  To connect to server with polling only transport:

  To connect to server with websocket only transport:

• binary_as_resource

  When client receives a binary data, by default it will be presented as resource. Set to false to retain it as string instead. Be careful, when you read the resource content, it is necessary to seek the stream to the begining using fseek($handle, 0) first.

Methods

Elephant.io client (ElephantIO\Client) provides the following api methods:

• initialize()

  An alias to connect().

• connect()

  Connect to socket.io server. In case of server connection is unsuccessful, an exception ElephantIO\Exception\SocketException will be thrown. It also connects to default / namespace and will trigger ElephantIO\Exception\UnsuccessfulOperationException upon unsuccessful attempts.

• close()

  An alias to disconnect().

• disconnect()

  Disconnect from server and free some resources.

• of($namespace)

  Connect to a namespace, see connect() above for possible errors.

• emit($event, array $args, $ack = null)

  Send an event to server. To request an acknowledgement from server, set $ack to true. When an acknowledgement is requested, a packet will be returned on successful operation.

• wait($event, $timeout = 0)

  Wait an event to be received from server.

• drain($timeout = 0)

  Drain and get returned packet from server, used to receive data from server when we are not expecting an event to arrive.

• ack($packet, array $args)

  Acknowledge a received event.

• getEngine()

  Get the underlying socket engine.

Debugging

It's sometime necessary to get the verbose output for debugging. Elephant.io utilizes Psr\Log\LoggerInterface for this purpose.

Here is an example of debug logging:

Examples

The the example directory shows how to get a basic knowledge of library usage.

Special Thanks

Special thanks goes to Mark Karpeles who helped the project founder to understand the way websockets works.