README.md

KATSANA SDK for PHP

• Installation
• Usages
  • Creating Client
  • Change Timezone
  • Handling Response
  • Using the API

Installation

To install through composer, simply put the following in your composer.json file:

{
    "require": {
        "katsana/katsana-sdk-php": "^1.2",
        "php-http/guzzle6-adapter": "^2.0"
    }
}

Quick Installation

Above installation can also be simplify by using the following command:

composer require "php-http/guzzle6-adapter" "katsana/katsana-sdk-php=^1.2"

HTTP Adapter

Instead of utilizing php-http/guzzle6-adapter you might want to use any other adapter that implements php-http/client-implementation. Check Clients & Adapters for PHP-HTTP.

Usages

Creating Client

You can start by creating a client by using the following code (which uses php-http/guzzle6-adapter and php-http/discovery to automatically pick available adapter installed via composer):

<?php

use Katsana\Sdk\Client;

$katsana = Client::make('client-id', 'client-secret');

In most cases, you will be using the client with Personal Access Token. You can initiate the client using the following code:

<?php

use Katsana\Sdk\Client;

$katsana = Client::personal('personal-access-token');

Change Timezone

By default, all request will return date and time data in UTC, however you may set the request to response with a different timezone by setting the client (globally) such as:

$katsana->onTimeZone('Asia/Kuala_Lumpur');

Or on each resource such as:

$vehicles = $katsana->uses('Vehicles');
$vehicles->onTimeZone('Asia/Kuala_Lumpur');

Handling Response

Every API request using the API would return an instance of Katsana\Sdk\Response which can fallback to \Psr\Http\Message\ResponseInterface, this allow developer to further inspect the response.

As an example:

$response = $katsana->uses('Welcome')->hello();

var_dump($response->toArray());

{
    "platform": "v4.5.13",
    "api": [
        "v1"
    ]
}

Getting the Response

You can get the raw response using the following:

$response->getBody();

However we also create a method to parse the return JSON string to array.

$response->toArray();

Checking the Response HTTP Status

You can get the response status code via:

$response->getStatusCode();

$response->isSuccessful();

$response->isUnauthorized();

Checking the Response Header

You can also check the response header via the following code:

$response->getHeaders(); // get all headers as array.
$response->hasHeader('Content-Type'); // check if `Content-Type` header exist.
$response->getHeader('Content-Type'); // get `Content-Type` header.

Using the API

There are two way to request an API:

Using API Resolver

This method allow you as the developer to automatically select the current selected API version without having to modify the code when KATSANA release new API version.

$vehicles = $katsana->uses('Vehicles'); 

$response = $vehicles->all(); 

This would resolve an instance of Katsana\Sdk\One\Vehicles class (as v1 would resolve to One namespace).

Explicit API Resolver

This method allow you to have more control on which version to be used.

$vehicles = $katsana->via(new Katsana\Sdk\One\Vehicles());

$response = $vehicles->all();