confidencesapp / oktave-sdk-php
The Oktave PHP SDK
Requires
- php: ^7.4 || ^8.0
- ext-json: *
- guzzlehttp/guzzle: ~6.0|~7.0
Requires (Dev)
- mockery/mockery: dev-master
- phpunit/phpunit: ^9.0
- vlucas/phpdotenv: ^5.0
README
This official PHP SDK for interacting with Oktave.
Installation
You can install the package manually or by adding it to your composer.json
:
{
"require": {
"confidencesapp/oktave-sdk-php": "^0.3.0"
}
}
Instantiating the SDK Client:
Pass in the configuration to the client:
$config = [ 'client_id' => '{your_client_uuid}', 'client_secret' => '{your_client_secret}', 'webhook_secret' => '{your_webhook_secret}', // optional, required for request signature validation ]; $oktave = new Oktave\Client($config);
Or configure after construct:
$oktave = new Oktave\Client() ->setClientID('uuid') ->setClientSecret('ok_cltsec_...') ->setWebhookSecret('ok_whsec_...'); // optional, required for request signature validation
Note: if you are unsure what your client_id
, client_secret
or webhook_secret
are, please go to
your account and copy them.
For multiple teams users:
Pass in the team ID to the client:
$config = [ // ... 'team_id' => '{your_team_uuid}' // optional, required to specify a team ID ]; $oktave = new Oktave\Client($config);
Or configure after construct:
$oktave = new Oktave\Client($config) ->setTeamId('uuid'); // optional, required to specify a team ID
Attention! If no team
is specified, the team on which the OAuth client has been declared is used by default.
Note: if you are unsure what your team
is, please go to
your account and copy it.
Reset to the default team without its ID:
// set the team to null. $oktave = new Oktave\Client($config) ->setTeamId(null);
Note: the team value can be updated at anytime, for example between resource calls.
On-Premise Customers
If you are an on-premise customer and have your own infrastructure with your own domain, you can configure the client to use your domain:
$oktave->setBaseURL('https://api.yourdomain.com');
Or by adding the api_endpoint
field to the $config
array you pass to the constructor.
Using the client
Multiple Resources
To return a list of your resources
// return a list of your blacklist items $oktave->blacklistItems->all();
Pagination
To return a paginated list of your resources
// return a list of your paginated blacklist items // items per page accepted values : 10, 20, 50, 100 $result = $oktave->blacklistItems->perPage(20)->page(5)->all(); $result->data() // contains the ressource collection $result->meta() // contains the current pagination meta /* [ 'current_page' => 5, 'per_page' => 20, 'total' => 95 ] */
Single Resource by ID
Fetch a Resource by ID:
$oktave->blacklistItems->get($blacklistItemID);
Handling Exceptions
Aside from errors that may occur due to the call, there may be other Exceptions thrown. To handle them, simply wrap your call in a try catch block:
try { $oktave->blacklistItems->all(); } catch (Exception $e) { // do something with $e }
Internally, there are several custom Exceptions which may be raised - see the Exceptions directory for more information.
Webhook request verification
To verify a webhook request signature
// return true if the request signature is valid $oktave->webhooks->verifySignatureFromGlobals();
$eventID = isset($_SERVER['HTTP_OKTAVE_EVENT_ID']) ? $_SERVER['HTTP_OKTAVE_EVENT_ID'] : null; $requestTimestamp = isset($_SERVER['HTTP_OKTAVE_TIMESTAMP']) ? (int) $_SERVER['HTTP_OKTAVE_TIMESTAMP'] : null; $signature = isset($_SERVER['HTTP_OKTAVE_SIGNATURE']) ? $_SERVER['HTTP_OKTAVE_SIGNATURE'] : null; // return true if the request signature is valid $oktave->webhooks->verifySignature($eventID, $requestTimestamp, $signature);
Test
phpunit
Generate a coverage report:
phpunit --coverage-html ./ignore