README

IsaaCloud is a high performance, distributed engagement platform, which utilizes gamification principles to inspire, motivate and build long-lasting relationships with clients, users, business partners and employees.

Isaacloud SDK for PHP

The Isaacloud PHP SDK can be used to access the IsaaCloud API through PHP. The user can make any number of request calls to the API.

Basics

This SDK can be used to connect to Isaacloud REST API at {instance}.isaacloud.com/api. The main class in IsaaCloud/SDK namespace is "isaacloud", and it allows for connecting to the public API. It has convenience methods for DELETE, GET, POST and PUT methods. In the future it will also contain a wrapper, which will offer all methods defined by IsaaCloud API RAML.

How to build it

You can build the PHP SDK via Composer. Follow the steps below.

Install Composer in your system

curl -s https://getcomposer.org/installer | php

Create a ** composer.json **
```
touch composer.json
```

Fill it with the following code

{
  "require": {
      "isaacloud/sdk": "0.0.6"
   }
}

Install!
```
php composer.phar install
```
Add autoloader to your main script
```
require 'vendor/autoload.php';
```

Usage

To make a simple request, specify the path to a resource using the path method, then declare the query parameters and finally, use a chosen REST method to obtain the results.

$isaac = new \IsaaCloud\Sdk\Isaacloud(array("apiUrl"=>YOUR_API_URL))

Sample requests

Get a list of users

$limit = 11
$offset = 10

$result = $isaac->path("/users")
                ->withPaginator($limit,$offset)
                ->get();

Get a user

$result2 = $isaac->path("/users/1")
                 ->get();

//or

$result3 = $isaac->path("/users/{userId}")
                 ->withParameters(array("userId" =>1))
                 ->get();

Resources

You can access via this PHP SDK all resources available in the IsaaCloud REST API. For more information, see https://github.com/isaacloud/api.

with methods

The methods that start with the word with correspond to traits/query parameters in the REST API and are responsible for narrowing the result set. To get the desired effect, you can combine multiple with methods. If you specify a query parameter that a given resource does not provide for, it will be ignored.

The list of methods is presented below:

withToken($token) - sets an access token to the request

$isaac->path("/users")
      ->withToken("Bearer SlAV32hkKG");
// sets "Bearer SlAV32hkKG" as an access token in the request

withParameters(array $parameters = array()) - adds URI parameters manually

$isaac->path("/users/{id}")
      ->withParameters(array("id" => 31))
      ->get()
// returns the user with id 31

$isaac->path("/users")
      ->withParameters(array("fields" => array("firstName", "lastName"))
      ->get();
// returns the users list with only firstName and lastName properties

withPaginator($limit = numeric, $offset = numeric) - limits the number of results and defines the offset, works only with list resources

$isaac->path("/users")
      ->withPaginator(5, 10)
      ->get();  
// returns five elements starting from the tenth one

withGroups(array $groups = array() || $groups = numeric || $groups = string) - returns only the resources with belonging to specified groups
```
$isaac->path("/users")
      ->withGroups(array(1,2,3))
      ->get();  
// returns only the users in groups 1 or 2 or 3
```

withTags(array $tags = array() || $tags = numeric || $tags = string) - returns only the resources belonging to specified tags

$isaac->path("/users")
      ->withTags(array("lorem", "ipsum"))
      ->get();  
// returns only the users with tags "lorem" or "ipsum"

withOrder(array $order = array()) - declares the order in which results in list resources should be returned

$isaac->path("/users")
      ->withOrder(array("firstName"=>"ASC","lastName"=>"DESC"))
      ->get();  
// returns results sorted first by firstName ascending and then by lastName descending

withQuery(array $query = array()) - returns objects that contain specified value in given fields

$isaac->path("/users")
      ->withQuery(array("firstName" => "John"))
      ->get();  
// returns only users named John

Exception handling

If no detailed exception handling is required, you can simply catch the basic IsaacloudConnectionException. If more detailed information about the error is needed, there are several exception classes that extend the general IsaacloudConnectionException case class. Catch a detailed exception before a general one. Check the isaacloud package for more details on available exceptions. Each can return an internal error code and message through the internalCode and message methods. Reviewing these values will give you further insight on what went wrong.

For detailed information about the possible URI calls, available query parameters and request methods, please see our documentation: http://dev.isaacloud.com

Changelog

Version 0.0.6

Added methods to get more curl request informations
Added methods to parse curl headers
Added method to get paginator collection and return it as array after request

Version 0.0.5

expection thrown in withPaginator fixed
return response header, return paginator added

Version 0.0.4

Connector - get request body added
Error handler
SDK parameters array

isaacloud / sdk

Maintainers

Details