why deepstreamHub? compare us getting started faq
use cases
products
developers
company
blog contact

The deepstream PHP SDK enables PHP developers to create, read, update and delete records, emit events and make RPCs. It also provides a batch mode that allows to combine multiple operations into a single transaction.

Under the hood the PHP SDK is using the deepstream HTTP API to execute individual and batch requests.

Installation

The deepstream PHP SDK can be installed via composer as composer require deepstreamhub/deepstream.io-client-php or browse the source on Github

Basic usage

<?php

use Deepstreamhub\DeepstreamClient;

// Instanciates a client and emits an event
$client = new DeepstreamClient( '<YOUR APP\'s HTTP URL>', array());

$client->emitEvent( 'news/sports', 'something about football is happening');

Creating the client

DeepstreamClient( $url, $authData )

argument type optional description
$url String false App HTTP URL available in your App Admin page
$authData Array true Auth token used for all your requests

The DeepstreamClient class creates a client instance to be used for all methods calls. The token option required for the $authData is a session token returned from a previous request to the app's HTTP auth url (see http authentication) or generated via the deepstreamHub's dashboards token auth type. If you're using open auth the the token is optional.

Examples:

// Instanciates a client with token session
$client = new DeepstreamClient( '<YOUR APP\'s HTTP URL>', array(
    'token' => 'xxxx'
));

// Instanciates a client for an app that uses open auth
$client = new DeepstreamClient( '<YOUR APP\'s HTTP URL>', array());

Methods

setRecord( $recordName, [$path], $data )

argument type optional description
$recordName String false The name of the record e.g. "cities/hamburg".
$path String true The record path.
$data Various true The data to be set. If no path is set, this must be an object.
ret description
Boolean The name of the record e.g. "cities/hamburg".

Updates a record. Records that do not already exist will be created. The optional "path" param may be used to update only part of a record.

Examples:

// Writing full data
$client->setRecord( 'user/johndoe', array(
    'firstname' => 'John',
    'lastname' => 'Doe',
    'age' => 32,
    'pets' => array( 'hamster', 'cat' )
));

// Writing partial data
$client->setRecord( 'user/johndoe', 'age', '33' );

getRecord( $recordName )

argument type optional description
$recordName String false The name of the record.
Returns:
Mixed return data. If the request succeed it returns the record object otherwise false.

Retrieves a Record previously created with the given name.

Example:

$firstname = $client->getRecord( 'user/johndoe' )->firstname;

deleteRecord( $recordName )

argument type optional description
$recordName String false The name of the record.
Returns:
true if the request was successful

Deletes a record from the cache and storage. Deletion will succeed even if the record does not exist.

Example:

$client->deleteRecord( 'user/johndoe' );

getRecordVersion( $recordName )

argument type optional description
$recordName String false The name of the record.
Returns:
The version number of the record

The version property may be used to ensure updates are not based on stale data. For an update to succeed, the version provided must be 1 greater than the current version, otherwise a version conflict will occur. To force an update the version can be omited.

Example:

$version = $client->getRecordVersion( 'user/johndoe' );

Records are the documents in deepstreamHub’s realtime datastore. A record is identified by a unique id and can contain any kind of JSON data. Clients and backend processes can create, read, write, update and observe the entire record as well as paths within it. Any change is immediately synchronized amongst all connected subscribers.

Records can be arranged in lists and collections and can contain references to other records to allow for the modelling of relational data structures.

You can learn more about records in the records tutorial.

makeRpc( $rpcName, [$data] )

argument type optional description
$rpcName String false The name of the RPC to call.
$data Various true The RPC data argument
Returns:
Mixed return data. If the request succeed it returns the response from the RPC provider, otherwise false.

Executes a remote procedure call.

Examples:

// with data
$twentyfour = $client->makeRpc( 'multiply-by-two', 12 );

$result = $client->makeRpc( 'new-order', array(
  'id' => 'sad1da1t6yt2-asd1',
  'quantity' => 2
));

// without data
$client->makeRpc( 'logout' );

Remote Procedure Calls are deepstreamHub’s request-response mechanism. Clients and backend processes can register as “providers” for a given RPC, identified by a unique name. Other endpoints can request said RPC.

deepstreamHub will route requests to the right provider, load-balance between multiple providers for the same RPC, and handle data-serialisation and transport.

emitEvent( $eventName, [$data] )

argument type optional description
$eventName String false The name of the event subscription
$data Various true A data payload
Returns:
true if the request was successful.

Emits an event

Examples:

// with data
$client->emitEvent( 'new-message', 'hey, what\'s up?' );

$client->emitEvent( 'sensors/garden', array(
  'temperature' => 23.6,
  'soil-moisture' => 12.7,
  'humidity' => 63
));

// without data
$client->emitEvent( 'ping' );

Events are deepstreamHub’s publish-subscribe mechanism. Clients and backend processes can subscribe to event-names (sometimes also called “topics” or “channels”) and receive messages published by other endpoints.

Events are non-persistent, one-off messages. For persistent data, please use records.

startBatch()

Returns:
void.

Initiates a set of batch operations that will be executed as a single request. No actual request will be sent until executeBatch is called. All the methods called in a batch operation will return true and the result of all operations is returned by the executeBatch method.

Example:

$client->startBatch();
// operations go here...

executeBatch()

Returns:
An Object with the response of all operations.

Executes a set of batch operations previously started.

Example:

$client->startBatch();
$client->emitEvent( 'new-message', 'hey, what\'s up?' );
$client->getRecord( 'user/johndoe' );
$client->setRecord( 'user/mike', 'age', 12 );
$client->executeBatch();