simtabi/netsapiens-api

A PHP Library for calling the NetSapiens REST API

dev-master 2023-03-13 17:33 UTC

Requires

• php: >=8.0
• guzzlehttp/guzzle: >=7.5.0
• phpfastcache/phpfastcache: >=9.1.3

Requires (Dev)

• phpunit/phpunit: >=9.0

MIT

• Imani Manyara
• Easter Mukora

• netsapiens
• simtabi

README

NetSapiens REST API Client

A PHP REST API client for calling the NetSapiens API (http://netsapiens.com).

API specific documentation can be found online at the ns-api API Reference website.

Features

1. REST API client
2. Command line client — coming soon

Installation

You can install the package via composer:

composer require simtabi/netsapiens

Usage

use Simtabi\NetSapiens\NetSapiens;
use Simtabi\NetSapiens\Helpers\Helpers;

// API auth credentials
$clientId         = ''; // your client id
$clientSecret     = ''; // your client secret
$username         = ''; // your username
$password         = ''; // your password
$baseUrl          = ''; // i.e https://api.netsapiens.com/

$guzzleConfig     = []; // Guzzle HTTP client configuration

// Path to store cache files
$cachePath        = ''; // path to where the cache would be stored

// Initialize the API client
try {
    return NetSapiens::getInstance(
        clientId     : $clientId,
        clientSecret : $clientSecret,
        username     : $username,
        password     : $password,
        baseUrl      : $baseUrl,
        cacher       : function (array $args) use ($cachePath) {
                        $cacheData = $args[0];
                        $cacheId   = $args[1];
                        
                        return Helpers::cacher(
                            items :            $cacheData,
                            cacheId:           $cacheId,
                            cachePath :        $cachePath,
                            lifeTimeInSeconds: Helpers::CACHE_LIFETIME_IN_SECONDS,
                            resetCache:        true,
                        );
    },
        guzzleConfig : $guzzleConfig
    );
} catch (NetSapiensException $exception) {
    // do something if we encountered errors
    echo $exception->getMessage();
}

// you can access resource specific error by calling the following method

Accessing the Authentication object instance

$oAuth2 = $netSapiensClient->getOAuth2();

Accessing all errors encountered during an OAuth2 call

$errors = $netSapiensClient->getOAuth2()->getErrors();

Using the helper method

$netSapiensClient = netSapiensClient($clientId, $clientSecret, $username, $password, $baseUrl, $cacher, $guzzleConfig);

// returns a NetSapiens instance or a string if there were errors found

N.B

If you do not want to use the default caching mechanism. cacher accepts a callback function where you can pass in a custom caching implementation.

Available Resources

Resources marked in green are ready for use.

1. Create a Call Queue

// Call queue details
$phoneNumber = '';
$queue       = '';
$uid         = '';

// Create a call queue
$newCallQueue = $netSapiensClient
                ->getCallQueue()
                ->setQueue($queue)
                ->setUid($uid)
                ->create($phoneNumber);

Only use $netSapiensClient instanceof NetSapiens when using the helper function. i.e

if($netSapiensClient instanceof NetSapiens) {
    $newCallQueue = $netSapiensClient
                    ->getCallQueue()
                    ->setQueId($queue)
                    ->setUid($uid)
                    ->create($phoneNumber);
    
    if ($newCallQueue) {
        // do something if successful
    }
} else {
    // do something if we have errors
}

Accessing the Request object instance

This can only be achieved after making a resource request. For example, you can access the Request instance after creating a call queue.

$callQueue  = $netSapiensClient->getCallQueue()->setQueue($queue)->setUid($uid);
$callNumber = $callQueue->create($phoneNumber);
$errors     = $callQueue->getRequest()->getErrors();

If you do not want to use the default caching mechanism. cacher accepts a callback function where you can pass in a custom caching implementation.

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

Credits

• Imani Manyara
• Easter Mukora
• All Contributors

License

The MIT License (MIT). Please see License File for more information.