PHP YouTrack REST

Introduction

YouTrack REST API PHP Client uses PSR-7 (HTTP Message Interface) to connect with JetBrains YouTrack REST API.

Part of the PHP YouTrack SDK.

Usage

Initialize API client

Token authorization

Starting with YouTrack 2017.1 release authorization based on permanent tokens is recommended as the main approach for the authorization in your REST API calls.

// Instantiate PSR-7 HTTP Client
$psrHttpClient = new \GuzzleHttp\Client([
    'base_uri' => 'https://example.com',
]);

// Instantiate YouTrack API HTTP Client Adapter
$httpClient = new \Cog\YouTrack\Rest\HttpClient\GuzzleHttpClient($psrHttpClient);

// Instantiate YouTrack API Token Authorizer
$authorizer = new \Cog\YouTrack\Rest\Authorizer\TokenAuthorizer('YOUTRACK_API_TOKEN');

// Instantiate YouTrack API Client
$youtrack = new \Cog\YouTrack\Rest\Client\YouTrackClient($httpClient, $authorizer);

Cookie authorization

// Instantiate PSR-7 HTTP Client
$psrHttpClient = new \GuzzleHttp\Client([
    'base_uri' => 'https://example.com',
]);

// Instantiate YouTrack API HTTP Client Adapter
$httpClient = new \Cog\YouTrack\Rest\HttpClient\GuzzleHttpClient($psrHttpClient);

// Instantiate YouTrack API Cookie Authenticator
$authenticator = new \Cog\YouTrack\Rest\Authenticator\CookieAuthenticator('YOUTRACK_USERNAME', 'YOUTRACK_PASSWORD');

// Instantiate YouTrack API Cookie Authorizer
$authorizer = new \Cog\YouTrack\Rest\Authorizer\CookieAuthorizer($authenticator);

// Instantiate YouTrack API Client
$youtrack = new \Cog\YouTrack\Rest\Client\YouTrackClient($httpClient, $authorizer);

API requests

HTTP request

$method = 'POST'; // GET, POST, PUT, DELETE, PATCH or any custom ones
$response = $youtrack->request($method, '/issue', [
    'project' => 'TEST',
    'summary' => 'New test issue',
    'description' => 'Test description',
]);

You can customize requests created and transferred by a client using request options. Request options control various aspects of a request including, headers, query string parameters, timeout settings, the body of a request, and much more.

$options = [
    'debug' => true,
    'sink' => '/path/to/dump/file',
];
$response = $youtrack->request('POST', '/issue', [
    'project' => 'TEST',
    'summary' => 'New test issue',
    'description' => 'Test description',
], $options);

HTTP GET request

$response = $youtrack->get('/issue/TEST-1');

HTTP POST request

$response = $youtrack->post('/issue', [
    'project' => 'TEST',
    'summary' => 'New test issue',
    'description' => 'Test description',
]);

HTTP PUT request

$response = $youtrack->put('/issue/TEST-1', [
    'summary' => 'Updated summary',
    'description' => 'Updated description',
]);

HTTP DELETE request

$response = $youtrack->delete('/issue/TEST-1');

Make request with custom header

$youtrack->withHeader('Cookie', 'Overriden cookie');
$response = $youtrack->get('/issue/TEST-1');

Make request with multiple custom headers

$youtrack->withHeaders([
    'Cookie' => 'Overriden cookie',
    'foo' => 'bar',
]);
$response = $youtrack->get('/issue/TEST-1');

API responses

Each successful request to the API returns instance of \Cog\Contracts\YouTrack\Rest\Response\Response contract. By default it's \Cog\YouTrack\Rest\Response\YouTrackResponse class.

Get PSR HTTP response

PSR HTTP response could be accessed by calling httpResponse method on API Response.

$youtrackResponse = $youtrack->get('/issue/TEST-1');
$psrResponse = $youtrackResponse->httpResponse();

Get response headers

Returns headers as string from the HTTP response.

$apiResponse = $youtrack->get('/issue/TEST-1');
$headerString = $apiResponse->header('Any-Header-You-Want');

Get response Cookie

Returns Set-Cookie headers as string from the HTTP response.

$apiResponse = $youtrack->get('/issue/TEST-1');
$cookieString = $apiResponse->cookie();

Get response Location

Returns Location header from the HTTP response.

$apiResponse = $youtrack->get('/issue/TEST-1');
$location = $apiResponse->location();

Transform body of the response to array

$apiResponse = $youtrack->get('/issue/TEST-1');
$responseArray = $apiResponse->toArray();

Returns body of the response

$apiResponse = $youtrack->get('/issue/TEST-1');
$body = $apiResponse->body();

Assert HTTP response status code

$apiResponse = $youtrack->get('/issue/TEST-1');
$isSuccess = $apiResponse->isStatusCode(200);

Get HTTP response status code

$apiResponse = $youtrack->get('/issue/TEST-1');
$location = $apiResponse->statusCode();

Determine if HTTP response status is 2xx

$apiResponse = $youtrack->get('/issue/TEST-1');
$isSuccess = $apiResponse->isSuccess();

Determine if HTTP response status is 3xx

$apiResponse = $youtrack->get('/issue/TEST-1');
$isRedirect = $apiResponse->isRedirect();

Determine if HTTP response status is 4xx

$apiResponse = $youtrack->get('/issue/TEST-1');
$isRedirect = $apiResponse->isClientError();

Determine if HTTP response status is 5xx

$apiResponse = $youtrack->get('/issue/TEST-1');
$isRedirect = $apiResponse->isServerError();