PHP and JIRA’s REST API

At my last job I needed generate release notes for each version of software that we shipped to customers. I created a PHP script to pull the status of issues in JIRA and generate HTML output which contained key fields such as key, summary, priority, and resolution. I could link that output to the release. Why not use the JIRA issues macro in Confluence? The JIRA issues macro in Confluence does a great job highlighting the current status of issues in JIRA. When software is in active development it’s a great way to keep everyone on the same page. This task required a solution that would freeze the status in time. If a bug was fixed in a release that later gets reopened, we didn’t want the release notes to show that bug having an open status. We believed that issue was fixed at the time of release. PHP code is easy for me to write as I’ve been using it to automate mundane tasks over the years. The problem was I’d not used it RESTfully before. I Googled “JIRA PHP” and didn’t find many examples of how to use JIRA with PHP. I wanted to create an article that summarizes how to do the basic issue operations using PHP and JIRA’s REST API.   Many JIRA users have come to rely on the JIRA Command Line interface (me included) to automate operations inside of JIRA. I needed a higher level of control where I could manipulate individual fields on a large scale. Using JIRA’s REST API was the right solution for the job. JIRA’s REST API is super flexible and allows many of the same operations a user could do programmatically. PHP uses the cURL object to access JIRA. How does it work? Let’s take a look using an example to search for a set of issues created in the last day.

Searching for issues

We can use the search API available at http://example.com/rest/api/2/search with the JQL “created > -1d”.

Let’s take a look at the get_from function to see how PHP is interacting with JIRA.

function get_from($resource, $data) {
	//convert array to JSON string
	$jdata = json_encode($data);
	$ch = curl_init();
	//configure CURL
	curl_setopt_array($ch, array(
		CURLOPT_URL => JIRA_URL . '/rest/api/latest/' . $resource,
		CURLOPT_USERPWD => USERNAME . ':' . PASSWORD,
		CURLOPT_POSTFIELDS => $jdata,
		CURLOPT_HTTPHEADER => array('Content-type: application/json'),
		CURLOPT_RETURNTRANSFER => true
	));
	$result = curl_exec($ch);
	curl_close($ch);
	//convert JSON data back to PHP array
	return json_decode($result);
}

Creating Issues

function post_to($resource, $data) {
	$jdata = json_encode($data);
	$ch = curl_init();
	curl_setopt_array($ch, array(
		CURLOPT_POST => 1,
		CURLOPT_URL => JIRA_URL . '/rest/api/latest/' . $resource,
		CURLOPT_USERPWD => USERNAME . ':' . PASSWORD,
		CURLOPT_POSTFIELDS => $jdata,
		CURLOPT_HTTPHEADER => array('Content-type: application/json'),
		CURLOPT_RETURNTRANSFER => true
	));
	$result = curl_exec($ch);
	curl_close($ch);
	return json_decode($result);
}

Editing issues

function put_to($resource, $data) {
	$jdata = json_encode($data);
	$ch = curl_init();
	curl_setopt_array($ch, array(
		CURLOPT_CUSTOMREQUEST=>"PUT",
		CURLOPT_URL => JIRA_URL . '/rest/api/latest/' . $resource,
		CURLOPT_USERPWD => USERNAME . ':' . PASSWORD,
		CURLOPT_POSTFIELDS => $jdata,
		CURLOPT_HTTPHEADER => array(
			'Accept: application/json',
			'Content-Type: application/json'
			),
		CURLOPT_RETURNTRANSFER => true
	));
	$result = curl_exec($ch);
	curl_close($ch);
	return json_decode($result);
}

Full source can be had here.