README

This package provides a very basic, convenient, and unified wrapper for Jira.

Table of Contents

• Installation
• Usage
• Examples
• Tests
• Changelog
• Contributing
• Credits
• License

Installation

To install the client you need to require the package using composer:

$ composer require testmonitor/jira-client

Use composer's autoload:

require __DIR__.'/../vendor/autoload.php';

You're all set up now!

Usage

This client only supports oAuth authentication. You'll need an Atlassian Jira application to proceed. If you haven't done so, please read up with the Jira authentication docs on how to create an application.

When your Jira application is up and running, start with the oAuth authorization:

$oauth = [
    'clientId' => '12345',
    'clientSecret' => 'abcdef',
    'redirectUrl' => 'https://redirect.myapp.com/',
];

$jira = new \TestMonitor\Jira\Client($oauth);

header('Location: ' . $jira->authorizationUrl());
exit();

This will redirect the user to a page asking confirmation for your app getting access to Jira. Make sure your redirectUrl points back to your app. This URL should point to the following code:

$oauth = [
    'clientId' => '12345',
    'clientSecret' => 'abcdef',
    'redirectUrl' => 'https://redirect.myapp.com/',
];

$jira = new \TestMonitor\Jira\Client($oauth);

$token = $jira->fetchToken($_REQUEST['code']);

When everything went ok, you should have an access token (available through Token object).

For any subsequent action, you'll need to retrieve your cloud ID to proceed:

$oauth = [
    'clientId' => '12345',
    'clientSecret' => 'abcdef',
    'redirectUrl' => 'https://redirect.myapp.com/',
];

$token = new \TestMonitor\Jira\AccessToken('eyJ0...', '0/34ccc...', 1574601877); // the token you got last time
$jira = new \TestMonitor\Jira\Client($oauth, null, $token);

$account = $jira->account();

Use the cloud ID as a parameter when instantiating the client:

$oauth = [
    'clientId' => '12345',
    'clientSecret' => 'abcdef',
    'redirectUrl' => 'https://redirect.myapp.com/',
];

$token = new \TestMonitor\Jira\AccessToken('eyJ0...', '0/34ccc...', 1574601877);
$jira = new \TestMonitor\Jira\Client($oauth, $account->id, $token);

That's it!

Please note that the access token will be valid for one hour. When it expires, you'll need to refresh it:

if ($token->expired()) {
    $newToken = $jira->refreshToken();
}

The new token will be valid again for the next hour.

Examples

Retrieve the details for a project using its key:

$project = $jira->project('KEY');

Or create a new issue using the first available issue type:

$issueTypes = $jira->issueTypes('KEY');

$issue = $jira->createIssue(new \TestMonitor\Jira\Resources\Issue([
    'summary' => 'It is time Marty!',
    'description' => 'Great Scot!',
    'project' => $project,
    'type' => $issueType[0],
]));

The package also includes a JQL builder to help construct issue search queries. Use it to filter issues by project, status, assignee, and more:

$query = (new \TestMonitor\Jira\Builders\JQL\JQL)
    ->where(\TestMonitor\Jira\Builders\JQL\Field::PROJECT, 'KEY')
    ->where(\TestMonitor\Jira\Builders\JQL\Field::STATUS, \TestMonitor\Jira\Builders\JQL\Operator::NOT_IN, ['Done', 'Cancelled'])
    ->orderBy(\TestMonitor\Jira\Builders\JQL\Field::CREATED, 'DESC');

$issues = $jira->issues($query);

The when method allows you to conditionally add clauses, which is useful when building queries from user input:

$query = (new \TestMonitor\Jira\Builders\JQL\JQL)
    ->where(\TestMonitor\Jira\Builders\JQL\Field::PROJECT, 'KEY')
    ->when($assignee, function ($jql, $value) {
        $jql->where(\TestMonitor\Jira\Builders\JQL\Field::ASSIGNEE, $value);
    });

$issues = $jira->issues($query);

Tests

The package contains integration tests. You can run them using PHPUnit.

$ vendor/bin/phpunit

Changelog

Refer to CHANGELOG for more information.

Contributing

Refer to CONTRIBUTING for contributing details.

Credits

• Thijs Kok - Lead developer - ThijsKok
• Stephan Grootveld - Developer - Stefanius
• Frank Keulen - Developer - FrankIsGek

License

The MIT License (MIT). Refer to the License for more information.