README

This package is a modern PHP SDK for the Kumulos API.

Installation

You can install using composer from Packagist.

composer require timacdonald/kumulos

Although it is not recommended, because this package does not contain any dependencies, you can simply download and include the files in your project.

Versioning

This package uses Semantic Versioning. You can find out more about what this is and why it matters by reading the spec or for something more readable, check out this post.

Usage

Create a Kumulos API object and then simply call the methods you've created in your API on the API object.

use TiMacDonald\Kumulos\Api;

/**
 * Create our api object instance.
 */
$api = new Api($key, $secret);

/**
 * Call an API method on the object, passing in an associative array of values.
 */
$api->createUser([
    'name' => 'Tim MacDonald',
    'twitter' => '@timacdonald87',
    'github' => 'timacdonald',
    'website' => 'timacdonald.me'
]);

/**
 * Check if it failed.
 */
if ($api->failed()) {
    // deal with failure, perhaps with an exception
    throw new Exception($api->response()->message(), $api->response()->statusCode());
}

/**
 * Retrieve the response payload.
 */
$userId = $api->response()->payload();

Normalized Status Codes

Kumulos responds with custom status codes, but if you would like to normalize these status codes to the standard HTTP response codes, you can simply call the following methods:

// Check if it failed
if ($api->failed()) {
    // deal with failure, perhaps with an exception
    throw new Exception($api->response()->normalizedMessage(), $api->response()->normalizedStatusCode());
}

Wiring Up DI in Laravel

If you are utilising the Laravel framework, you will want to put you API key and secret in you environment (.env) file.

...
DB_USERNAME=homestead
DB_PASSWORD=secret

KUMULOS_API_KEY=your-api-key-here
KUMULOS_API_SECRET=your-secrethere

The in your ./config/services.php file, you can add the Kumulos service like so:

return [
    'kumulos' => [
        'key' => env('KUMULOS_API_KEY'),
        'secret' => env('KUMULOS_API_SECRET')
    ],
    ...

Great. Now the config is sorted, lets bind it to the IOC container. In your app service provider's register method, simply add the following binding method:

$this->app->bind(\TiMacDonald\Kumulos\Api::class, function ($app) {
    return new \TiMacDonald\Kumulos\Api(
        $app['config']->get('services.kumulos.key'),
        $app['config']->get('services.kumulos.secret')
    );
});

Now you can have the container resolve your API class for you without having to 'new' up an instance.

<?php

namespace App\Http\Controllers;

use TiMacDonald\Kumulos\Api;

class UserController extends Controller
{
    public function store(Api $api)
    {
        $api->createUser([
            'name' => 'Tim MacDonald',
            'twitter' => '@timacdonald87',
            'github' => 'timacdonald',
            'website' => 'timacdonald.me'
        ]);

        //
    }
}

What Next

Add ability to force standardised response messages and code.
Add Laravel service provider for binding as per docs.
Throw exceptions instead of checking for failure.

Thanksware

You are free to use this package, but I ask that you reach out to someone (not me) who has previously, or is currently, maintaining or contributing to an open source library you are using in your project and thank them for their work. Consider your entire tech stack: packages, frameworks, languages, databases, operating systems, frontend, backend, etc.

timacdonald / kumulos

Maintainers

Details