PHP client library SDK for Ably realtime messaging service
Clone or download
Latest commit e35c404 Oct 21, 2018

README.md

Ably

A PHP REST client library for www.ably.io, the realtime messaging service.

Supported Platforms

This SDK supports PHP 5.6 and 7.0+

We regression-test the library against a selection of PHP versions (which will change over time, but usually consists of the versions that are supported upstream). Please refer to .travis.yml for the set of versions that currently undergo CI testing.

We'll happily support (and investigate reported problems with) any reasonably-widely-used PHP version. If you find any compatibility issues, please do raise an issue in this repository or contact Ably customer support for advice.

Documentation

Visit https://www.ably.io/documentation for a complete API reference and more examples.

Installation

Via composer

The client library is available as a composer package on packagist. If you don't have composer already installed, you can get it from https://getcomposer.org/.

Install Ably from the shell with:

$ composer require ably/ably-php --update-no-dev

Then simply require composer's autoloader:

require_once __DIR__ . '/vendor/autoload.php';

Manual installation

Clone or download Ably from this repo and require ably-loader.php:

require_once __DIR__ . '/ably-php/ably-loader.php';

Using the REST API

Introduction

All examples assume a client and/or channel has been created as follows:

$client = new Ably\AblyRest('your.appkey:xxxxxx');
$channel = $client->channel('test');

Publishing a message to a channel

$channel->publish('myEvent', 'Hello!'); // => true

Querying the History

$messagesPage = $channel->history(); // => \Ably\Models\PaginatedResult
$messagesPage->items[0]; // => \Ably\Models\Message
$messagesPage->items[0]->data; // payload for the message
$messagesPage->next(); // retrieves the next page => \Ably\Models\PaginatedResult
$messagesPage->hasNext(); // false, there are no more pages

Presence on a channel

$membersPage = $channel->presence->get(); // => \Ably\Models\PaginatedResult
$membersPage->items[0]; // first member present in this page => \Ably\Models\PresenceMessage
$membersPage->items[0]->clientId; // client ID of first member present
$membersPage->next(); // retrieves the next page => \Ably\Models\PaginatedResult
$membersPage->hasNext(); // false, there are no more pages

Querying the Presence History

$presencePage = $channel->presence->history(); // => \Ably\Models\PaginatedResult
$presencePage->items[0]; // => \Ably\Models\PresenceMessage
$presencePage->items[0]->clientId; // client ID of first member
$presencePage->next(); // retrieves the next page => \Ably\Models\PaginatedResult

Generate Token and Token Request

$tokenDetails = $client->auth->requestToken();
// => \Ably\Models\PresenceMessage
$tokenDetails->token; // => "xVLyHw.CLchevH3hF....MDh9ZC_Q"

$client = new Ably\AblyRest( $tokenDetails->token );
// or
$client = new Ably\AblyRest( array( 'tokenDetails' => $tokenDetails ) );

$token = $client->auth->createTokenRequest();
// => {"id" => ...,
//     "clientId" => null,
//     "ttl" => 3600,
//     "timestamp" => ...,
//     "capability" => "{\"*\":[\"*\"]}",
//     "nonce" => ...,
//     "mac" => ...}

Fetching your application's stats

$statsPage = client->stats(); // => \Ably\Models\PaginatedResult
$statsPage->items[0]; // => \Ably\Models\Stats
$statsPage->next(); // retrieves the next page => \Ably\Models\PaginatedResult

Fetching the Ably service time

$client->time(); // in milliseconds => 1430313364993

Laravel

If you're using Laravel, you may want to check out ably-php-laravel wrapper, which is a wrapper with Laravel-specific helper classes.

Support, feedback and troubleshooting

Please visit http://support.ably.io/ for access to our knowledgebase and to ask for any assistance.

You can also view the community reported Github issues.

To see what has changed in recent versions of Bundler, see the CHANGELOG.

Known limitations

  1. This client library requires PHP version 5.4 or greater
  2. msgpack support is currently missing in PHP client library, as there is no stable PHP msgpack library available.

Running the tests

The client library uses the Ably sandbox environment to provision an app and run the tests against that app. In order to run the tests, you need to:

git clone https://github.com/ably/ably-php.git
cd ably-php
composer install
git submodule init
git submodule update
./vendor/bin/phpunit

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Ensure you have added suitable tests and the test suite is passing (run vendor/bin/phpunit)
  5. Push to the branch (git push origin my-new-feature)
  6. Create a new Pull Request

Release Process

This library uses semantic versioning. For each release, the following needs to be done:

License

Copyright (c) 2017 Ably Real-time Ltd, Licensed under the Apache License, Version 2.0. Refer to LICENSE for the license terms.