Pusher PHP Library

This is a PHP library for interacting with the Pusher REST API.

Register at http://pusher.com and use the application credentials within your app as shown below.

Installation

You can get the Pusher PHP library via a composer package called pusher-php-server. See https://packagist.org/packages/pusher/pusher-php-server

Or you can clone or download the library files.

We recommend you use composer.

Pusher constructor

Use the credentials from your Pusher application to create a new Pusher instance.

$app_id = 'YOUR_APP_ID';
$app_key = 'YOUR_APP_KEY';
$app_secret = 'YOUR_APP_SECRET';

$pusher = new Pusher( $app_key, $app_secret, $app_id );

By default calls will be made over a non-encrypted connection. To change this to make calls over HTTPS:

$pusher = new Pusher( $app_key, $app_secret, $app_id, false, 'https://api.pusherapp.com', 443 );

Publishing/Triggering events

To trigger an event on one or more channels use the trigger function.

A single channel

$pusher->trigger( 'my-channel', 'my_event', 'hello world' );

Multiple channels

$pusher->trigger( [ 'channel-1', 'channel-2' ], 'my_event', 'hello world' );

Arrays

Objects are automatically converted to JSON format:

$array['name'] = 'joe';
$array['message_count'] = 23;

$pusher->trigger('my_channel', 'my_event', $array);

The output of this will be:

"{'name': 'joe', 'message_count': 23}"

Socket id

In order to avoid duplicates you can optionally specify the sender's socket id while triggering an event (http://pusherapp.com/docs/duplicates):

$pusher->trigger('my-channel','event','data','socket_id');

Debugging

You can either turn on debugging by setting the fifth argument to true, like so:

$pusher->trigger('my-channel', 'event', 'data', null, true)

or with all requests:

$pusher = new Pusher($key, $secret, $app_id, true);

On failed requests, this will return the server's response, instead of false.

Logging

You can pass an object with a log function to the pusher->set_logger function so that you can log information from the library.

class MyLogger {
    public function log( $msg ) {
        print_r( $msg . "\n" );
    }
}

$pusher->set_logger( new MyLogger() );

JSON format

If your data is already encoded in JSON format, you can avoid a second encoding step by setting the sixth argument true, like so:

$pusher->trigger('my-channel', 'event', 'data', null, false, true)

Authenticating Private channels

To authorise your users to access private channels on Pusher, you can use the socket_auth function:

$pusher->socket_auth('my-channel','socket_id');

Authenticating Presence channels

Using presence channels is similar to private channels, but you can specify extra data to identify that particular user:

$pusher->presence_auth('my-channel','socket_id', 'user_id', 'user_info');

Presence example

First set this variable in your JS app:

Pusher.channel_auth_endpoint = '/presence_auth.php';

Next, create the following in presence_auth.php:

<?php
header('Content-Type: application/json');
if ($_SESSION['user_id']){
  $sql = "SELECT * FROM `users` WHERE id='$_SESSION[user_id]'";
  $result = mysql_query($sql,$mysql);
  $user = mysql_fetch_assoc($result);
} else {
  die('aaargh, no-one is logged in')
}

$pusher = new Pusher($key, $secret, $app_id);
$presence_data = array('name' => $user['name']);
echo $pusher->presence_auth($_POST['channel_name'], $_POST['socket_id'], $user['id'], $presence_data);
?>

Note: this assumes that you store your users in a table called users and that those users have a name column. It also assumes that you have a login mechanism that stores the user_id of the logged in user in the session.

Application State Queries

Generic get function

pusher->get( $path, $params ) 

Used to make GET queries against the Pusher REST API. Handles authentication.

Response is an associative array with a result index. The contents of this index is dependent on the REST method that was called. However, a status property to allow the HTTP status code is always present and a result property will be set if the status code indicates a successful call to the API.

$response = $pusher->get( '/channels' );
$http_status_code = $response[ 'status' ];
$result = $response[ 'result' ];

Get information about a channel

get_channel_info( $name )

It's also possible to get information about a channel from the Pusher REST API.

$info = $pusher->get_channel_info('channel-name');
$channel_occupied = $info->occupied;

This can also be achieved using the generic pusher->get function:

pusher->get( '/channels/channel-name' );    

Get a list of application channels

get_channels()

It's also possible to get a list of channels for an application from the Pusher REST API.

$result = $pusher->get_channels();
$channel_count = count($result->channels); // $channels is an Array

This can also be achieved using the generic pusher->get function:

pusher->get( '/channels' );

Get a filtered list of application channels

get_channels( array( 'filter_by_prefix' => 'some_filter' ) )

It's also possible to get a list of channels based on their name prefix. To do this you need to supply an $options parameter to the call. In the following example the call will return a list of all channels with a 'presence-' prefix. This is idea for fetching a list of all presence channels.

$results = $pusher->get_channels( array( 'filter_by_prefix' => 'presence-') );
$channel_count = count($result->channels); // $channels is an Array

This can also be achieved using the generic pusher->get function:

$pusher->get( '/channels', array( 'filter_by_prefix' => 'presence-' ) );

Get user information from a presence channel

$response = $pusher->get( '/channels/presence-channel-name/users' )

The $response is in the format:

Array
(
    [body] => {"users":[{"id":"a_user_id"}]}
    [status] => 200
    [result] => Array
        (
            [users] => Array
                (
                    [0] => Array
                        (
                            [id] => a_user_id
                        )
                    /* Additional users */    
                )
        )
)

Running the tests

Requires phpunit.

• Got to the tests directory
• Rename config.example.php and replace the values with valid Pusher credentials or create environment variables.
• Execute phpunit . to run all the tests.

License

Copyright 2010, Squeeks. Licensed under the MIT license: http://www.opensource.org/licenses/mit-license.php