Methods

This document details the methods of the PHP client library.

Initializing the client

Begin by initializing an instance of Deskpro\API\DeskproClient, with the URL to your Deskpro instance.

<?php
use Deskpro\API\DeskproClient;
$client = new DeskproClient('http://deskpro.company.com');

Guzzle is used to make HTTP requests. A default Guzzle client will be used by the library, but a custom instance may be provided.

<?php
use Deskpro\API\DeskproClient;
use GuzzleHttp\Client;
$httpClient = new Client([
'timeout' => 60
]);
$client = new DeskproClient('http://deskpro.company.com', $httpClient);
// Or use the setter method.
// $client->setHTTPClient($httpClient);

An instance of Psr\Log\LoggerInterface may also be passed to the constructor when initializing the client.

<?php
use Deskpro\API\DeskproClient;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;
$logger = new Logger('name');
$logger->pushHandler(new StreamHandler('path/to/your.log', Logger::DEBUG));
$client = new DeskproClient('http://deskpro.company.com', null, $logger);
// Or use the setter method.
// $client->setLogger($logger);

Authenticating

Many API methods require authentication. Set the ID of the user to authenticate with and either the auth "key" or "token".

<?php
use Deskpro\API\DeskproClient;
$client = new DeskproClient('http://deskpro.company.com');
// Use the setAuthKey method to authenticate using a key.
$personId = 1;
$authKey = 'dev-admin-code';
$client->setAuthKey($personId, $authKey);
// Use the setAuthToken method to authenticate using a token.
$personId = 1;
$authToken = 'AWJ2BQ7WG589PQ6S862TCGY4';
$client->setAuthToken($personId, $authToken);

Get

Sends a GET request to the API.

DeskproClientInterface::get($endpoint, array $params = []) : APIResponseInterface

<?php
use Deskpro\API\DeskproClient;
use Deskpro\API\Exception\APIException;
$client = new DeskproClient('http://deskpro.company.com');
$client->setAuthKey(1, 'dev-admin-code');
try {
$resp = $client->get('/articles');
print_r($resp->getData());
} catch (APIException $e) {
echo $e->getMessage();
}
// Parameters are interpolated into the provided URL.
// The next request will be made to "/articles/101?limit=25".
$params = [
'id' => 101,
'limit' => 25
];
$client->get('/articles/{id}', $params);

Post

Sends a POST request to the API.

DeskproClientInterface::post($endpoint, $body = null, array $params = []) : APIResponseInterface

<?php
use Deskpro\API\DeskproClient;
use Deskpro\API\Exception\APIException;
$client = new DeskproClient('http://deskpro.company.com');
$client->setAuthKey(1, 'dev-admin-code');
try {
$body = [
'title' => 'Mary Had a Little Lamb',
'content' => 'Whose fleece was white as snow.'
];
$resp = $client->post('/articles', $body);
print_r($resp->getData());
} catch (APIException $e) {
echo $e->getMessage();
}

Put

Sends a PUT request to the API.

DeskproClientInterface::put($endpoint, $body = null, array $params = []) : APIResponseInterface

<?php
use Deskpro\API\DeskproClient;
use Deskpro\API\Exception\APIException;
$client = new DeskproClient('http://deskpro.company.com');
$client->setAuthKey(1, 'dev-admin-code');
try {
$body = [
'title' => 'Mary Had a Little Lamb',
'content' => 'Whose fleece was white as snow.'
];
$params = [
'id' => 101
];
$resp = $client->put('/articles/{id}', $body, $params);
print_r($resp->getData());
} catch (APIException $e) {
echo $e->getMessage();
}

Delete

Sends a DELETE request to the API.

DeskproClientInterface::delete($endpoint, array $params = []) : APIResponseInterface

<?php
use Deskpro\API\DeskproClient;
use Deskpro\API\Exception\APIException;
$client = new DeskproClient('http://deskpro.company.com');
$client->setAuthKey(1, 'dev-admin-code');
try {
$params = [
'id' => 101
];
$resp = $client->delete('/articles/{id}', $params);
print_r($resp->getData());
} catch (APIException $e) {
echo $e->getMessage();
}

Batch

Sends a batch request to the API.

DeskproClientInterface::batch(array $requests) : APIResponseInterface[]

<?php
use Deskpro\API\DeskproClient;
use Deskpro\API\Exception\APIException;
$client = new DeskproClient('http://deskpro.company.com');
$client->setAuthKey(1, 'dev-admin-code');
try {
$resp = $client->batch([
'105' => [
'method' => 'GET',
'url' => '/articles/105'
],
'new' => [
'method' => 'POST',
'url' => '/articles',
'payload' => [
'title' => 'Mary Had a Little Lamb',
'content' => 'Whose fleece was white as snow.'
]
]
]);
print_r($resp['105']->getData());
print_r($resp['new']->getData());
} catch (APIException $e) {
echo $e->getMessage();
}

Request

Sends a custom request to the API.

DeskproClientInterface::request($method, $endpoint, $body = null, array $params = [], array $headers = []) : APIResponseInterface

<?php
use Deskpro\API\DeskproClient;
use Deskpro\API\Exception\APIException;
$client = new DeskproClient('http://deskpro.company.com');
$client->setAuthKey(1, 'dev-admin-code');
try {
$body = [
'title' => 'Mary Had a Little Lamb',
'content' => 'Whose fleece was white as snow.'
];
$params = [
'id' => 101
];
$headers = [
'X-Custom-Value' => 'some value'
];
$resp = $client->request('PUT', '/articles/{id}', $body, $params, $headers);
print_r($resp->getData());
} catch (APIException $e) {
echo $e->getMessage();
}

Asynchronous Requests

Each of the methods get, post, put, delete, batch, and request have asynchronous versions which return a promise.

<?php
use Deskpro\API\DeskproClient;
use Deskpro\API\APIResponseInterface;
use Deskpro\API\Exception\APIException;
$client = new DeskproClient('http://deskpro.company.com');
$client->setAuthKey(1, 'dev-admin-code');
$promise = $client->getAsync('/articles');
$promise->then(function(APIResponseInterface $resp) {
print_r($resp->getData());
}, function(APIException $err) {
echo $err->getMessage();
});
$promise->wait();
$body = [
'title' => 'Mary Had a Little Lamb',
'content' => 'Whose fleece was white as snow.'
];
$promise = $client->postAsync('/articles', $body);
$promise->then(function(APIResponseInterface $resp) {
print_r($resp->getData());
}, function(APIException $err) {
echo $err->getMessage();
});
$promise->wait();

Default Headers

Sets the headers sent with each request.

<?php
use Deskpro\API\DeskproClient;
use Deskpro\API\Exception\APIException;
$client = new DeskproClient('http://deskpro.company.com');
// Send these headers and values with each request made to the API.
$client->setDefaultHeaders([
'X-Custom-Value' => 'foo'
]);

Response

Each of the methods get, post, put, delete, batch, and request returns an instance of APIResponseInterface.

APIResponseInterface::getData() : array APIResponseInterface::getMeta() : array APIResponseInterface::getLinked() : array

<?php
use Deskpro\API\DeskproClient;
use Deskpro\API\Exception\APIException;
$client = new DeskproClient('http://deskpro.company.com');
$client->setAuthKey(1, 'dev-admin-code');
try {
$resp = $client->get('/articles');
print_r($resp->getData());
print_r($resp->getMeta());
print_r($resp->getLinked());
} catch (APIException $e) {
echo $e->getMessage();
}

For asynchronous requests, an instance of APIResponseInterface is passed to the resolver function.

<?php
use Deskpro\API\DeskproClient;
use Deskpro\API\APIResponseInterface;
$client = new DeskproClient('http://deskpro.company.com');
$client->setAuthKey(1, 'dev-admin-code');
$promise = $client->getAsync('/articles');
$promise->then(function(APIResponseInterface $resp) {
print_r($resp->getData());
});
$promise->wait();

The APIResponseInterface interface implements ArrayAccess, Iterator, and Countable.

<?php
use Deskpro\API\DeskproClient;
use Deskpro\API\Exception\APIException;
$client = new DeskproClient('http://deskpro.company.com');
$client->setAuthKey(1, 'dev-admin-code');
try {
$resp = $client->get('/articles');
echo "Found " . count($resp) . " articles\n";
foreach($resp as $article) {
echo $article['title'] . "\n";
}
} catch (APIException $e) {
echo $e->getMessage();
}