General concepts

The GoMoob Pushwoosh PHP Library is written to be almost identic to the standard Pushwoosh REST API.

Calls to the Pushwoosh REST Web Services are done using a Pushwoosh client class.

All calls are done the same way :

Create a Request object.
Call a method on the Pushwoosh client and receive a Response object.
Check if the call is successful with the isOk() method of the received Response object.

<?php 
// Pushwoosh sample resquest / response with the '/createMessage' Web Service
$request = CreateMessageRequest::create()->addNotification(...);
$response = $pushwoosh->createMessage($request);

if($response->isOk()) {
    // Successful call
} else {
    // In error call
}
?>

Pushoosh clients

The API provides 2 Pushwoosh clients which redeclare the methods described in the official Pushwoosh Remote API guide .

A standard Pushwoosh client defined by the Gomoob\Pushwoosh\Client\Pushwoosh class
A mock Pushwoosh client defined by the Gomoob\Pushwoosh\Client\PushwooshMock class

Those two classes implement the Gomoob\Pushwoosh\IPushwoosh interface where you'll find a copy of the documentation of each method described in the Pushwoosh Remote API guide .

The `Pushwoosh` class

The Gomoob\Pushwoosh\Client\Pushwoosh class represents a concrete Pushwoosh client which calls the Pushwoosh Remote API Web Services.

Server URL

By default the Pushwoosh class uses the https://cp.pushwoosh.com/json/1.3 Pushwoosh server URL.

If you are using a Pushwoosh enterprise plan then you have a dedicated server URL like https://your-company.pushwoosh.com. You can indicate to php-pushwoosh to use this custom URL with the following code.

<?php 
// Pushwoosh client configuration sample with custom API server URL
$pushwoosh = Pushwoosh::create('https://your-company.pushwoosh.com');

// Or using the constructo
$pushwoosh = new Pushwoosh('https://your-company.pushwoosh.com');
?>

CURL options

The Pushwoosh client class uses CURL to send HTTP requests to the Pushwoosh Web Services. The default CURL configuration should work without any problem, but in some rare cases you'll want to change specific CURL options.

Here is a sample to change the CURLOPT_CONNECTTIMEOUT and CURLOPT_TIMEOUT on the CURL client which is used in the library.

<?php 
// Changing CURL options using several setter calls
$pushwoosh->getCURLClient()->setAdditionalCurlOpt(CURLOPT_CONNECTTIMEOUT, 2);
                           ->setAdditionalCurlOpt(CURLOPT_CURLOPT_TIMEOUT, 5);

// Changing CURL options using only one setter call
$pushwoosh->getCURLClient()->setAdditionalCurlOpts(
    [
        CURLOPT_CONNECTTIMEOUT => 2,
        CURLOPT_CURLOPT_TIMEOUT => 5
    ]
);
?>

Configuration

Before using your Pushwoosh client you first have to configure it, in most cases you configure your client in one place in a project, then you use it where you want.

The configuration properties to configure are the following :

application : The Pushwoosh application ID to be used by default by all the requests performed by the Pushwoosh client. This identifier can be overwritten by request if needed. If the applicationGroups parameter is defined then the application parameter must not be defined.
applicationsGroup : The Pushwoosh applications group code to be used to defautl by all the requests performed by the Pushwoosh client. This identifier can be overwritten by requests if needed. If the application parameter is defined then the applicationsGroups parameter must not be defined.
auth : The API access token taken from the Pushwoosh control panel (create this token at https://cp.pushwoosh.com/api_access).

<?php 
// Pushwoosh client configuration sample
$pushwoosh = Pushwoosh::create();
$pushwoosh->setApplication('XXXXX-XXXXX')
$pushwoosh->setAuth('xxxxxxxx');
?>

Once a Pushwoosh client is configured the application (or applicationsGroup) and auth parameters will be automatically injected in the JSON payloads sent to the Pushwoosh servers.

This is much more quick and easy than providing your Pushwoosh creadentials each time you make a request (although proving specific credentials for each request is also possible).

Web Service methods

The Pushwoosh clients define one method for each Web Service endpoint of the Pushwoosh Remote API.

You'll find documentation and several samples about each method by following those links.

The `PushwooshMock` class

The PushwooshMock class represents a mock Pushwoosh client, it defines the same methods as the Pushwoosh class but it do not call the Pushwoosh Remote API Web Services.

Instead this class works in memory and simulates the Pushwoosh servers. This class is convenient when you want to write unit tests.

Requests

Each request sent to the Pushwoob REST Web Services is represented by a xxxRequest request object / class defined in the Gomoob\Pushwoosh\Model\Request namespace.

Request classes

The request objects are passed to Pushwoosh client methods to request the Pushwoosh Web Services. Their is one request class for each available Pushwoosh Web Service endpoint.

/createMessage => CreateMessageRequest
/deleteMessage => DeleteMessageRequest
/getNearestZone => GetNearestZoneRequest
/pushStat => PushStatRequest
/registerDevice => RegisterDeviceRequest
/setBadge => SetBadgeRequest
/setTags => SetTagsRequest
/unregisterDevice => UnregisterDeviceRequest

Overwriting credentials using requests

In general you configure the application, applicationsGroup and auth parameters at one place on your Pushwoosh client.

But, in some cases you'll want to use specific credentials at request time, it's possible to overwrite the credentials parameters configured in your Pushwoosh client for only one particular request.

<?php 
$request = CreateMessageRequest::create();
$request->setApplication('XXXXX-XXXXX')
$request->setAuth('xxxxxxxx');

// Here the credentials used are those configured in the request object
// and not the ones configured in the Pushwoosh client
$response = $pushwoosh->createMessage($request);
?>

Responses

Each response received from the Pushwoob REST Web Services is represented by a xxxResponse response object / class defined in the Gomoob\Pushwoosh\Model\Response namespace.

Then you call a method by using a request object and receive a response object with a success message or the detail of an error.

Response classes

The available response objects returned from the Pushwoosh client methods are the followings.

/createMessage => CreateMessageResponse
/deleteMessage => DeleteMessageResponse
/getNearestZone => GetNearestZoneResponse
/pushStat => PushStatResponse
/registerDevice => RegisterDeviceResponse
/setBadge => SetBadgeResponse
/setTags => SetTagsResponse
/unregisterDevice => UnregisterDeviceResponse

API design

Creation methods

All the concrete classes provided by the Data Model layer (Request, Response and Notification classes) can be instantiated using the new operator or a static create method.

For example the 2 following code are equivalent.

<?php 
$request = CreateMessageRequest::create();
?>

<?php 
$request = new CreateMessageRequest();
?>

Setters

All the setters provided by the Data Model classes (Request, Response and Notification classes) return the instance associated to the object where the call has been done.

For example the 2 following codes are equivalent.

<?php 
$request = CreateMessageRequest::create()
    ->setApplication('XXXXX-XXXXX')
    ->setAuth('xxxxxxxx')
    ->addNotification($notification0)
    ->addNotification($notification1);
?>

<?php 
$request = CreateMessageRequest::create();
$request->setApplication('XXXXX-XXXXX');
$request->setAuth('xxxxxxxx')
$request->addNotification($notification0)
$request->addNotification($notification1);
?>