timacdonald / kumulos
Kumulos PHP API SDK
Installs: 426
Dependents: 0
Suggesters: 0
Security: 0
Stars: 1
Watchers: 2
Forks: 0
Open Issues: 1
Type:utility
Requires
- php: >=5.6
This package is auto-updated.
Last update: 2022-07-29 01:36:09 UTC
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.