| <?php |
|
| namespace Redmine\Api; |
|
| /** |
| * Listing issues, searching, editing and closing your projects issues. |
| * |
| * @link http://www.redmine.org/projects/redmine/wiki/Rest_Issues |
| * @author Kevin Saliou <kevin at saliou dot name> |
| */ |
| class Issue extends AbstractApi |
| { |
| const PRIO_LOW = 1; |
| const PRIO_NORMAL = 2; |
| const PRIO_HIGH = 3; |
| const PRIO_URGENT = 4; |
| const PRIO_IMMEDIATE = 5; |
|
| /** |
| * List issues |
| * @link http://www.redmine.org/projects/redmine/wiki/Rest_Issues |
| * available $params : |
| * - offset: skip this number of issues in response (optional) |
| * - limit: number of issues per page (optional) |
| * - sort: column to sort with. Append :desc to invert the order. |
| * - project_id: get issues from the project with the given id, where id is either project id or project identifier |
| * - tracker_id: get issues from the tracker with the given id |
| * - status_id: get issues with the given status id only. Possible values: open, closed, * to get open and closed issues, status id |
| * - assigned_to_id: get issues which are assigned to the given user id |
| * - cf_x: get issues with the given value for custom field with an ID of x. (Custom field must have 'used as a filter' checked.) |
| * - query_id : id of the previously saved query |
| * |
| * @param array $params the additional parameters (cf avaiable $params above) |
| * @return array list of issues found |
| */ |
| public function all(array $params = array()) |
| { |
| return $this->retrieveAll('/issues.json', $params); |
| } |
|
| /** |
| * Get extended information about an issue gitven its id |
| * @link http://www.redmine.org/projects/redmine/wiki/Rest_Issues#Using-JSON |
| * available $params : |
| * include: fetch associated data (optional). Possible values: children, attachments, relations, changesets and journals |
| * |
| * @param string $id the issue id |
| * @param array $params extra associated data |
| * @return array information about the issue |
| */ |
| public function show($id, array $params = array()) |
| { |
| return $this->get('/issues/'.urlencode($id).'.json?'.http_build_query($params)); |
| } |
|
| /** |
| * Build the XML for an issue |
| * @param array $params for the new/updated issue data |
| * @return SimpleXMLElement |
| */ |
| private function buildXML(array $params = array()) |
| { |
| $xml = new SimpleXMLElement('<?xml version="1.0"?><issue></issue>'); |
|
| foreach ($params as $k => $v) { |
| if ('custom_fields' === $k && is_array($v)) { |
| $this->attachCustomFieldXML($xml, $v); |
| } elseif ('watcher_user_ids' === $k && is_array($v)) { |
| $watcher_user_ids = $xml->addChild('watcher_user_ids', ''); |
| $watcher_user_ids->addAttribute('type', 'array'); |
| foreach ($v as $watcher) { |
| $watcher_user_ids->addChild('watcher_user_id', (int) $watcher); |
| } |
| } elseif ('uploads' === $k && is_array($v)) { |
| $uploads_item = $xml->addChild('uploads', ''); |
| $uploads_item->addAttribute('type', 'array'); |
| foreach ($v as $upload) { |
| $upload_item = $uploads_item->addChild('upload', ''); |
| foreach ($upload as $upload_k => $upload_v) { |
| $upload_item->addChild($upload_k, $upload_v); |
| } |
| } |
| } else { |
| $xml->addChild($k, $v); |
| } |
| } |
|
| return $xml; |
| } |
|
| /** |
| * Create a new issue given an array of $params |
| * The issue is assigned to the authenticated user. |
| * @link http://www.redmine.org/projects/redmine/wiki/Rest_Issues#Creating-an-issue |
| * |
| * @param array $params the new issue data |
| * @return SimpleXMLElement |
| */ |
| public function create(array $params = array()) |
| { |
| $defaults = array( |
| 'subject' => null, |
| 'description' => null, |
|
| // 'project' => null, |
| // 'category' => null, |
| // 'status' => null, |
| // 'tracker' => null, |
| // 'assigned_to' => null, |
| // 'author' => null, |
|
| 'project_id' => null, |
| 'category_id' => null, |
| 'priority_id' => null, |
| 'status_id' => null, |
| 'tracker_id' => null, |
| 'assigned_to_id' => null, |
| 'author_id' => null, |
| 'due_date' => null, |
| 'start_date' => null, |
| 'watcher_user_ids' => null, |
| ); |
| $params = $this->cleanParams($params); |
| $params = array_filter(array_merge($defaults, $params)); |
|
| $xml = $this->buildXML($params); |
|
| return $this->post('/issues.xml', $xml->asXML()); |
| // $json = json_encode(array('issue' => $params)); |
| // return $this->post('/issues.json', $json); |
| } |
|
| /** |
| * Update issue information's by username, repo and issue number. Requires authentication. |
| * @link http://www.redmine.org/projects/redmine/wiki/Rest_Issues#Updating-an-issue |
| * |
| * @param string $id the issue number |
| * @param array $params |
| * @return SimpleXMLElement |
| */ |
| public function update($id, array $params) |
| { |
| $defaults = array( |
| 'id' => $id, |
| 'subject' => null, |
| 'notes' => null, |
|
| // 'project' => null, |
| // 'category' => null, |
| // 'status' => null, |
| // 'tracker' => null, |
| // 'assigned_to' => null, |
| // 'author' => null, |
|
| 'category_id' => null, |
| 'priority_id' => null, |
| 'status_id' => null, |
| 'tracker_id' => null, |
| 'assigned_to_id' => null, |
| 'due_date' => null, |
| ); |
| $params = $this->cleanParams($params); |
| $params = array_filter(array_merge($defaults, $params)); |
|
| $xml = $this->buildXML($params); |
|
| return $this->put('/issues/'.$id.'.xml', $xml->asXML()); |
| } |
|
| /** |
| * @param int $id |
| * @param string $watcher_user_id |
| * @return void |
| */ |
| public function addWatcher($id, $watcher_user_id) |
| { |
| return $this->post('/issues/'.$id.'/watchers.xml', '<user_id>'.$watcher_user_id.'</user_id>'); |
| } |
|
| /** |
| * @param int $id |
| * @param string $watcher_user_id |
| * @return void |
| */ |
| public function removeWatcher($id, $watcher_user_id) |
| { |
| return $this->delete('/issues/'.$id.'/watchers/'.$watcher_user_id.'.xml'); |
| } |
|
| /** |
| * @param int $id |
| * @param string $status |
| * @return void |
| */ |
| public function setIssueStatus($id, $status) |
| { |
| $statusId = $this->client->api('issue_status')->getIdByName($status); |
|
| return $this->update($id, array( |
| 'status_id' => $statusId |
| )); |
| } |
|
| /** |
| * @param int $id |
| * @param string $note |
| * @return void |
| */ |
| public function addNoteToIssue($id, $note) |
| { |
| return $this->update($id, array( |
| 'notes' => $note |
| )); |
| } |
|
| /** |
| * Transforms literal identifiers to integer ids |
| * @param array $params |
| * @return array |
| */ |
| private function cleanParams(array $params = array()) |
| { |
| if (isset($params['project'])) { |
| $params['project_id'] = $this->client->api('project')->getIdByName($params['project']); |
| unset($params['project']); |
|
| if (isset($params['category'])) { |
| $params['category_id'] = $this->client->api('issue_category')->getIdByName($params['project_id'], $params['category']); |
| unset($params['category']); |
| } |
| } |
| if (isset($params['status'])) { |
| $params['status_id'] = $this->client->api('issue_status')->getIdByName($params['status']); |
| unset($params['status']); |
| } |
| if (isset($params['tracker'])) { |
| $params['tracker_id'] = $this->client->api('tracker')->getIdByName($params['tracker']); |
| unset($params['tracker']); |
| } |
| if (isset($params['assigned_to'])) { |
| $params['assigned_to_id'] = $this->client->api('user')->getIdByUsername($params['assigned_to']); |
| unset($params['assigned_to']); |
| } |
| if (isset($params['author'])) { |
| $params['author_id'] = $this->client->api('user')->getIdByUsername($params['author']); |
| unset($params['author']); |
| } |
|
| return $params; |
| } |
|
| /** |
| * Attach a file to an issue issue number. Requires authentication. |
| * @link http://www.redmine.org/projects/redmine/wiki/Rest_Issues#Updating-an-issue |
| * |
| * @param string $id the issue number |
| * @param array $attachment |
| * @return bool|string |
| */ |
| public function attach($id, array $attachment) |
| { |
| $request['issue'] = array( |
| 'id' => $id, |
| 'uploads' => array( |
| 'upload' => $attachment |
| ) |
| ); |
|
| return $this->put('/issues/'.$id.'.json', json_encode($request)); |
| } |
|
| /** |
| * Remove a issue by issue number |
| * |
| * @param string $id the issue number |
| */ |
| public function remove($id) |
| { |
| return $this->delete('/issues/'.$id.'.xml'); |
| } |
| } |
