madmis/jira-api

Jira REST API php client

JIRA REST API PHP Client

![Build Status][testing-image] [][coverage-link] , _(*1)

JIRA provides REST APIs that you can use to interact with JIRA programmatically. This API client will help you interact with JIRA by REST API., _(*2)

License

MIT License, _(*3)

JIRA REST API Reference

https://docs.atlassian.com/jira/REST/latest/, _(*4)

Contributing

To create new endpoint - create issue or create pull request, _(*5)

Install

composer require madmis/jira-api 1.0.*

Usage

$api = new madmis\JiraApi\JiraApi('http://localhost:8080/', '/rest/api/2');

$auth = new madmis\JiraApi\Authentication\Basic('email@test.com', 'password');
$api->setAuthentication($auth);

$projectList = $api->project()->getProjects();

$project = $api->project()->getProject('MFTP');

$issue = $api->issue()->getIssue('MFTP-4');

// Issue result
array [
  'expand' => "renderedFields,names,schema,transitions,operations,editmeta,changelog"
  'id' => "10003"
  'self' => "http://localhost:8080/rest/api/2/issue/10003"
  'key' => "MFTP-4"
  'fields' => { ... }
]

Create Issue

$api = new madmis\JiraApi\JiraApi('http://localhost:8080/', '/rest/api/2');

$auth = new madmis\JiraApi\Authentication\Basic('email@test.com', 'password');
$api->setAuthentication($auth);

// without mapping
$result = $api->issue()->createIssue('PROJ', 'summary', 1, ['description' => 'description']);

// Issue result
array [
  'id' => "10105"
  'key' => "PROJ-9"
  'self' => "http://127.0.0.1:8080/rest/api/2/issue/10105"
]

// with mapping
$result = $api->issue()->createIssue('PROJ', 'summary', 1, ['description' => 'description'], true);

// Issue result
class madmis\JiraApi\Model\Issue {
  protected $self => "http://127.0.0.1:8080/rest/api/2/issue/10104"
  protected $id => 10104
  protected $key => "PROJ-8"
  protected $labels => []
  protected $description => NULL
  protected $summary => NULL
  protected $updated => NULL
  protected $created => NULL
  protected $issueType => NULL
  protected $project => NULL
  protected $creator => NULL
  protected $reporter => NULL
  protected $assignee => NULL
  protected $status => NULL
}

Tempo worklog (Tempo timesheets)

// This is default options, it is not required to set them.
// Set them only it Tempo REST API has another urn
$options = [
    'tempo_timesheets_urn' => '/rest/tempo-timesheets/3',
];
$api = new madmis\JiraApi\JiraApi('http://localhost:8080/', '/rest/api/2', $options);

$auth = new madmis\JiraApi\Authentication\Basic('email@test.com', 'password');
$api->setAuthentication($auth);

$issue = $api->issue()->getIssue('MFTP-4');

// Tempo worklog result
array [
  array [
    'timeSpentSeconds' => 28800
    'dateStarted' => "2015-08-29T00:00:00.000"
    'comment' => "2323"
    'self' => "http://127.0.0.1:8080/rest/tempo-timesheets/3/worklogs/10000"
    'id' => 10000
    'author' => [ ... ]
    'issue' => [ ... ]
    'worklogAttributes' => [ ... ]
  ]
]

Mapping

$issue = $api->issue()->getIssue('MFTP-4', '*all', '', true);

// Result
class madmis\JiraApi\Model\Issue {
    protected $self => "http://localhost:8080/rest/api/2/issue/10003"
    protected $id => 10003
    protected $key => "MFTP-4"
    protected $updated => class DateTime
    protected $issueType => class madmis\JiraApi\Model\IssueType
    protected $project => class madmis\JiraApi\Model\Project
    protected $creator => class madmis\JiraApi\Model\User
    protected $reporter => class madmis\JiraApi\Model\User
    protected $assignee => class madmis\JiraApi\Model\User
    protected $status => class madmis\JiraApi\Model\IssueStatus
  }

Error handling

Each client request errors wrapped to custom exception madmis\JiraApi\Exception\ClientException, _(*6)

class madmis\JiraApi\Exception\ClientException {
  private $request => class GuzzleHttp\Psr7\Request
  private $response => NULL
  protected $message => "cURL error 7: Failed to connect to 127.0.0.1 port 8080: Connection refused (see http://curl.haxx.se/libcurl/c/libcurl-errors.html)"
  ...
}

ClientException contains original request object and response object if response available, _(*7)

class madmis\JiraApi\Exception\ClientException {
  private $request => class GuzzleHttp\Psr7\Request 
  private $response => class GuzzleHttp\Psr7\Response {
    private $reasonPhrase => "Unauthorized"
    private $statusCode => 401
    ...
  }
  protected $message => "Client error: 401"
  ...  
}

So, to handle errors use try/catch, _(*8)

try {
    $issue = $api->issue()->getIssue('MFTP-4');
} catch (madmis\JiraApi\Exception\ClientException $ex) {
    // any actions (log error, send email, ...) 
}

Running the tests

To run the tests, you'll need to install phpunit and behat. Easiest way to do this is through composer., _(*9)

composer install

Running Unit tests

php vendor/bin/phpunit -c phpunit.xml.dist

Running Behat tests

To run Behat test you'll need to install Jira. Create config file from example behat.yml.dist, _(*10)

php vendor/bin/behat -c behat.yml