InstapushPHP: PHP wrapper for instapush.im¶
InstapushPHP is full php wrapper for instapush.im APIs that use the wonderful PHP-HTTP.
instapush.im uses a simple REST API to receive messages from your application and send them to devices running mobile clients.
InstapushPHP will make it easy to interact with theses APIs :
- Abstraction of the http client so you can use : Curl, Guzzle 5, Guzzle 6, etc.
- Abstraction of request and response.
- Auto transformation of response into Objects.
- Easy installation process using composer
- Respect of PSR recommendations from the PHP-FIG.
- Code quality guaranteed
- And much more.
Installation¶
The installation process of the InstapushPHP.
With Composer¶
You can use Composer to install the last version of the library.
$ composer require fnayou/instapush-php
Now, all you have to todo is to choose and install the HTTP Client you want to use.
Note
Note that we implement Discovery feature, so if you already use a http client like Guzzle then no more actions are required
Please, take some minutes to check Client Section of the PHP-HTTP documentation.
Use With cURL Client¶
In order to use cURL Client all you have to do is :
$ composer require fnayou/instapush-php
$ composer require php-http/curl-client
Use With Guzzle 6 Adapter¶
In order to use Guzzle 6 Adapter all you have to do is :
$ composer require fnayou/instapush-php
$ composer require php-http/guzzle6-adapter
Usage¶
InstapushPHP is easy and simple to use.
Initiate InstapushPHP Client¶
First of all if you are already using a http client like curl or guzzle, then let Discovery feature make the magic and all you have to do is to initiate InstapushPHP and start requesting:
use Fnayou\InstapushPHP\InstapushClient;
// initiate Instapush client
$apiClient = InstapushClient::create('user-token', 'app-id', 'app-secret');
// continue requesting ...
if you want to define http cURL client
use Fnayou\InstapushPHP\InstapushClient;
use Http\Client\Curl\Client as CurlClient;
$curlOptions = [
CURLOPT_CONNECTTIMEOUT => 10,
CURLOPT_SSL_VERIFYPEER => false,
];
// initiate cURL client
$curlClient = new CurlClient(null, null, $curlOptions);
// initiate Instapush client
$client = new InstapushClient($curlClient);
$apiClient = $client::create('user-token', 'app-id', 'app-secret');
// continue requesting ...
if you want to define Guzzle client
use Fnayou\InstapushPHP\InstapushClient;
use GuzzleHttp\Client as GuzzleClient;
use Http\Adapter\Guzzle6\Client as GuzzleAdapter;
$config = [
'timeout' => 60.0,
'allow_redirects' => true,
'verify' => false,
];
// initiate guzzle client
$guzzleClient = new GuzzleClient($config);
$guzzleAdapter = new GuzzleAdapter($guzzleClient);
// initiate Instapush client
$client = new InstapushClient($guzzleAdapter);
$apiClient = $client::create('user-token', 'app-id', 'app-secret');
// continue requesting ...
Note
no matter what http client you will use, the request of APIs will be the same.
Type of instance¶
InstapushPHP provide 3 types of instance :
Instance to use Instapush applications API and it require only UserToken:
use Fnayou\InstapushPHP\InstapushClient;
// initiate Instapush client for User use
$apiClient = InstapushClient::createForUser('user-token');
Instance to use Instapush events and notifications APIs and it require AppId and AppSecret:
use Fnayou\InstapushPHP\InstapushClient;
// initiate Instapush client for App use
$apiClient = InstapushClient::createForApp('app-id', 'app-secret');
Instance to use full Instapush APIs but for specific user and specific application:
use Fnayou\InstapushPHP\InstapushClient;
// initiate Instapush client for both user and app use
$apiClient = InstapushClient::create('user-token', 'app-id', 'app-secret');
Note
Please check Instapush REST documentation for more information.
Requesting APIs¶
InstapushPHP make it easy to request Instapush.im APIs.
Note
Please check Instapush REST documentation for more information about REST APIs.
List of applications¶
In order to get list of applications for given user, all you have to do
use Fnayou\InstapushPHP\InstapushClient;
// initiate Instapush client for User use
$apiClient = InstapushClient::createForUser('user-token');
// list of applications
/** @var \Fnayou\InstapushPHP\Model\Applications $applications */
$applications = $apiClient->applications()->list();
The response $applications
will be instance of Fnayou\InstapushPHP\Model\Applications
that extend Doctrine\Common\Collections\ArrayCollection
.
Note
Full description of Fnayou\InstapushPHP\Model\Applications model.
Add application¶
In order to add application for given user, all you have to do
use Fnayou\InstapushPHP\InstapushClient;
use Fnayou\InstapushPHP\Model\Application;
// initiate Instapush client for User use
$apiClient = InstapushClient::createForUser('user-token');
// initiate new Application Model
$newApplication = new Application('My New Application');
// add the new application
/** @var \Fnayou\InstapushPHP\Model\Application $application */
$application = $apiClient->applications()->add($newApplication);
The response $application
will be instance of Fnayou\InstapushPHP\Model\Application
.
Note
Full description of Fnayou\InstapushPHP\Model\Application model.
List of events¶
In order to get list of events for given application, all you have to do
use Fnayou\InstapushPHP\InstapushClient;
// initiate Instapush client for App use
$apiClient = InstapushClient::createForApp('app-id', 'app-secret');
// list of events
/** @var \Fnayou\InstapushPHP\Model\Events $events */
$events = $apiClient->events()->list();
The response $events
will be instance of Fnayou\InstapushPHP\Model\Events
that extend Doctrine\Common\Collections\ArrayCollection
.
Note
Full description of Fnayou\InstapushPHP\Model\Events model.
Add event¶
In order to add event for given application, all you have to do
use Fnayou\InstapushPHP\InstapushClient;
use Fnayou\InstapushPHP\Model\Event;
// initiate Instapush client for App use
$apiClient = InstapushClient::createForApp('app-id', 'app-secret');
// initiate new Event Model
$newEvent = new Event(
'event_exemple',
'the {example_1} is pretty cool, more than the {example_2}',
['example_1', 'example_2']
);
// add the new event
/** @var \Fnayou\InstapushPHP\Model\Event $event */
$event = $apiClient->events()->add($newEvent);
The response $event
will be instance of Fnayou\InstapushPHP\Model\Event
.
Note
Full description of Fnayou\InstapushPHP\Model\Event model.
Post notification¶
In order to post notification for given application, all you have to do
use Fnayou\InstapushPHP\InstapushClient;
use Fnayou\InstapushPHP\Model\Notification;
// initiate Instapush client for App use
$apiClient = InstapushClient::createForApp('app-id', 'app-secret');
// initiate new Notification Model
$notification = new Notification(
'event_exemple',
[
'example_1' => 'Guzzle Client',
'example_2' => 'cURL Client',
]
);
// post notification, response will be boolean `true` if success
$response = $apiClient->notification()->post($notification);
The response will be boolean
if success.
Note
Full description of Fnayou\InstapushPHP\Model\Notification model.
Handling Exception¶
InstapushPHP can handle exception/error in 2 different ways.
The method setHandleException
specify if you want to throw an ApiException
or to return ApiError
model:
use Fnayou\InstapushPHP\Exception\ApiException;
use Fnayou\InstapushPHP\InstapushClient;
// initiate Instapush client
// handling is set to true by default so it will throw an `ApiException`
$apiClient = InstapushClient::createForUser('user-token');
// if you want to get `ApiError` instead
$apiClient->setHandleException(false);
ApiException¶
ApiException
extend from Http\Client\Exception\HttpException
so you can access Request and Response objects:
use Fnayou\InstapushPHP\Exception\ApiException;
use Fnayou\InstapushPHP\InstapushClient;
// initiate Instapush client
$apiClient = InstapushClient::createForUser('user-token');
try {
/** @var \Fnayou\InstapushPHP\Model\Applications $applications */
$applications = $apiClient->applications()->list();
} catch (ApiException $apiException) {
/** @var \Psr\Http\Message\RequestInterface $request */
$request = $apiException->getRequest();
/** @var \Psr\Http\Message\ResponseInterface $response */
$response = $apiException->getResponse();
}
ApiError¶
if handling exception is turned off then you will get and ApiError
object:
use Fnayou\InstapushPHP\InstapushClient;
use Fnayou\InstapushPHP\Model\ApiError;
// initiate Instapush client
$apiClient = InstapushClient::createForUser('user-token');
$apiClient->setHandleException(false);
$applications = $apiClient->applications()->list();
if ($applications instanceof ApiError) {
/** @var \Fnayou\InstapushPHP\Model\ApiError */
$apiError = $applications;
var_dump($apiError->getMessage());
var_dump($apiError->getStatus());
}
Note
Full description of Fnayou\InstapushPHP\Model\ApiError model.
Applications¶
Applications
object will be used in List of applications API.
Note
Applications
object extend Doctrine\Common\Collections\ArrayCollection.
Application¶
Application
object will be used in Add application API and List of applications API.
Field | Type | Description |
---|---|---|
title | string | the title of application |
appId | string | the application ID |
appSecret | string | the application Secret |
Events¶
Events
object will be used in List of events API.
Note
Events
object extend Doctrine\Common\Collections\ArrayCollection.
Event¶
Event
object will be used in Add event API and List of events API.
Field | Type | Description |
---|---|---|
title | string | the title of the event |
message | string | the push message with trackers |
trackers | array | the trackers used within message |
Notification¶
Notification
object will be used in Post notification API.
Field | Type | Description |
---|---|---|
event | string | the title of the event to use |
trackers | array | the trackers and there values |
ApiError¶
ApiError
will be created and returned only if you set the handleException
to false
in your InstapushClient
instance.
Note
Please check Handling Exception documentation.
Field | Type | Description |
---|---|---|
status | string | the http status of the API request |
message | string | the message returnedby the API |
\ Sort by:\ best rated\ newest\ oldest\
\\
Add a comment\ (markup):
\``code``
, \ code blocks:::
and an indented block after blank line