1 <?php
2 /**
3 * @package Joomla.Platform
4 * @subpackage GitHub
5 *
6 * @copyright Copyright (C) 2005 - 2017 Open Source Matters, Inc. All rights reserved.
7 * @license GNU General Public License version 2 or later; see LICENSE
8 */
9
10 defined('JPATH_PLATFORM') or die;
11
12 /**
13 * GitHub API Issues class for the Joomla Platform.
14 *
15 * @documentation https://developer.github.com/v3/issues
16 *
17 * @since 11.3
18 * @deprecated 4.0 Use the `joomla/github` package via Composer instead
19 *
20 * @property-read JGithubPackageIssuesAssignees $assignees GitHub API object for assignees.
21 * @property-read JGithubPackageIssuesComments $comments GitHub API object for comments.
22 * @property-read JGithubPackageIssuesEvents $events GitHub API object for events.
23 * @property-read JGithubPackageIssuesLabels $labels GitHub API object for labels.
24 * @property-read JGithubPackageIssuesMilestones $milestones GitHub API object for milestones.
25 */
26 class JGithubPackageIssues extends JGithubPackage
27 {
28 protected $name = 'Issues';
29
30 protected $packages = array('assignees', 'comments', 'events', 'labels', 'milestones');
31
32 /**
33 * Method to create an issue.
34 *
35 * @param string $user The name of the owner of the GitHub repository.
36 * @param string $repo The name of the GitHub repository.
37 * @param string $title The title of the new issue.
38 * @param string $body The body text for the new issue.
39 * @param string $assignee The login for the GitHub user that this issue should be assigned to.
40 * @param integer $milestone The milestone to associate this issue with.
41 * @param array $labels The labels to associate with this issue.
42 *
43 * @throws DomainException
44 * @since 11.3
45 *
46 * @return object
47 */
48 public function create($user, $repo, $title, $body = null, $assignee = null, $milestone = null, array $labels = null)
49 {
50 // Build the request path.
51 $path = '/repos/' . $user . '/' . $repo . '/issues';
52
53 // Ensure that we have a non-associative array.
54 if (isset($labels))
55 {
56 $labels = array_values($labels);
57 }
58
59 // Build the request data.
60 $data = json_encode(
61 array(
62 'title' => $title,
63 'assignee' => $assignee,
64 'milestone' => $milestone,
65 'labels' => $labels,
66 'body' => $body,
67 )
68 );
69
70 // Send the request.
71 $response = $this->client->post($this->fetchUrl($path), $data);
72
73 // Validate the response code.
74 if ($response->code != 201)
75 {
76 // Decode the error response and throw an exception.
77 $error = json_decode($response->body);
78 throw new DomainException($error->message, $response->code);
79 }
80
81 return json_decode($response->body);
82 }
83
84 /**
85 * Method to update an issue.
86 *
87 * @param string $user The name of the owner of the GitHub repository.
88 * @param string $repo The name of the GitHub repository.
89 * @param integer $issueId The issue number.
90 * @param string $state The optional new state for the issue. [open, closed]
91 * @param string $title The title of the new issue.
92 * @param string $body The body text for the new issue.
93 * @param string $assignee The login for the GitHub user that this issue should be assigned to.
94 * @param integer $milestone The milestone to associate this issue with.
95 * @param array $labels The labels to associate with this issue.
96 *
97 * @throws DomainException
98 * @since 11.3
99 *
100 * @return object
101 */
102 public function edit($user, $repo, $issueId, $state = null, $title = null, $body = null, $assignee = null, $milestone = null, array $labels = null)
103 {
104 // Build the request path.
105 $path = '/repos/' . $user . '/' . $repo . '/issues/' . (int) $issueId;
106
107 // Craete the data object.
108 $data = new stdClass;
109
110 // If a title is set add it to the data object.
111 if (isset($title))
112 {
113 $data->title = $title;
114 }
115
116 // If a body is set add it to the data object.
117 if (isset($body))
118 {
119 $data->body = $body;
120 }
121
122 // If a state is set add it to the data object.
123 if (isset($state))
124 {
125 $data->state = $state;
126 }
127
128 // If an assignee is set add it to the data object.
129 if (isset($assignee))
130 {
131 $data->assignee = $assignee;
132 }
133
134 // If a milestone is set add it to the data object.
135 if (isset($milestone))
136 {
137 $data->milestone = $milestone;
138 }
139
140 // If labels are set add them to the data object.
141 if (isset($labels))
142 {
143 // Ensure that we have a non-associative array.
144 if (isset($labels))
145 {
146 $labels = array_values($labels);
147 }
148
149 $data->labels = $labels;
150 }
151
152 // Encode the request data.
153 $data = json_encode($data);
154
155 // Send the request.
156 $response = $this->client->patch($this->fetchUrl($path), $data);
157
158 // Validate the response code.
159 if ($response->code != 200)
160 {
161 // Decode the error response and throw an exception.
162 $error = json_decode($response->body);
163 throw new DomainException($error->message, $response->code);
164 }
165
166 return json_decode($response->body);
167 }
168
169 /**
170 * Method to get a single issue.
171 *
172 * @param string $user The name of the owner of the GitHub repository.
173 * @param string $repo The name of the GitHub repository.
174 * @param integer $issueId The issue number.
175 *
176 * @throws DomainException
177 * @since 11.3
178 *
179 * @return object
180 */
181 public function get($user, $repo, $issueId)
182 {
183 // Build the request path.
184 $path = '/repos/' . $user . '/' . $repo . '/issues/' . (int) $issueId;
185
186 // Send the request.
187 $response = $this->client->get($this->fetchUrl($path));
188
189 // Validate the response code.
190 if ($response->code != 200)
191 {
192 // Decode the error response and throw an exception.
193 $error = json_decode($response->body);
194 throw new DomainException($error->message, $response->code);
195 }
196
197 return json_decode($response->body);
198 }
199
200 /**
201 * Method to list an authenticated user's issues.
202 *
203 * @param string $filter The filter type: assigned, created, mentioned, subscribed.
204 * @param string $state The optional state to filter requests by. [open, closed]
205 * @param string $labels The list of comma separated Label names. Example: bug,ui,@high.
206 * @param string $sort The sort order: created, updated, comments, default: created.
207 * @param string $direction The list direction: asc or desc, default: desc.
208 * @param JDate $since The date/time since when issues should be returned.
209 * @param integer $page The page number from which to get items.
210 * @param integer $limit The number of items on a page.
211 *
212 * @throws DomainException
213 * @since 11.3
214 *
215 * @return array
216 */
217 public function getList($filter = null, $state = null, $labels = null, $sort = null,
218 $direction = null, JDate $since = null, $page = 0, $limit = 0)
219 {
220 // Build the request path.
221 $path = '/issues';
222
223 // TODO Implement the filtering options.
224
225 // Send the request.
226 $response = $this->client->get($this->fetchUrl($path, $page, $limit));
227
228 // Validate the response code.
229 if ($response->code != 200)
230 {
231 // Decode the error response and throw an exception.
232 $error = json_decode($response->body);
233 throw new DomainException($error->message, $response->code);
234 }
235
236 return json_decode($response->body);
237 }
238
239 /**
240 * Method to list issues.
241 *
242 * @param string $user The name of the owner of the GitHub repository.
243 * @param string $repo The name of the GitHub repository.
244 * @param string $milestone The milestone number, 'none', or *.
245 * @param string $state The optional state to filter requests by. [open, closed]
246 * @param string $assignee The assignee name, 'none', or *.
247 * @param string $mentioned The GitHub user name.
248 * @param string $labels The list of comma separated Label names. Example: bug,ui,@high.
249 * @param string $sort The sort order: created, updated, comments, default: created.
250 * @param string $direction The list direction: asc or desc, default: desc.
251 * @param JDate $since The date/time since when issues should be returned.
252 * @param integer $page The page number from which to get items.
253 * @param integer $limit The number of items on a page.
254 *
255 * @throws DomainException
256 * @since 11.3
257 *
258 * @return array
259 */
260 public function getListByRepository($user, $repo, $milestone = null, $state = null, $assignee = null, $mentioned = null, $labels = null,
261 $sort = null, $direction = null, JDate $since = null, $page = 0, $limit = 0)
262 {
263 // Build the request path.
264 $path = '/repos/' . $user . '/' . $repo . '/issues';
265
266 $uri = new JUri($this->fetchUrl($path, $page, $limit));
267
268 if ($milestone)
269 {
270 $uri->setVar('milestone', $milestone);
271 }
272
273 if ($state)
274 {
275 $uri->setVar('state', $state);
276 }
277
278 if ($assignee)
279 {
280 $uri->setVar('assignee', $assignee);
281 }
282
283 if ($mentioned)
284 {
285 $uri->setVar('mentioned', $mentioned);
286 }
287
288 if ($labels)
289 {
290 $uri->setVar('labels', $labels);
291 }
292
293 if ($sort)
294 {
295 $uri->setVar('sort', $sort);
296 }
297
298 if ($direction)
299 {
300 $uri->setVar('direction', $direction);
301 }
302
303 if ($since)
304 {
305 $uri->setVar('since', $since->toISO8601());
306 }
307
308 // Send the request.
309 $response = $this->client->get((string) $uri);
310
311 // Validate the response code.
312 if ($response->code != 200)
313 {
314 // Decode the error response and throw an exception.
315 $error = json_decode($response->body);
316 throw new DomainException($error->message, $response->code);
317 }
318
319 return json_decode($response->body);
320 }
321
322 /*
323 * Deprecated methods
324 */
325
326 /**
327 * Method to create a comment on an issue.
328 *
329 * @param string $user The name of the owner of the GitHub repository.
330 * @param string $repo The name of the GitHub repository.
331 * @param integer $issueId The issue number.
332 * @param string $body The comment body text.
333 *
334 * @deprecated use issues->comments->create()
335 *
336 * @return object
337 *
338 * @since 11.3
339 */
340 public function createComment($user, $repo, $issueId, $body)
341 {
342 return $this->comments->create($user, $repo, $issueId, $body);
343 }
344
345 /**
346 * Method to create a label on a repo.
347 *
348 * @param string $user The name of the owner of the GitHub repository.
349 * @param string $repo The name of the GitHub repository.
350 * @param string $name The label name.
351 * @param string $color The label color.
352 *
353 * @deprecated use issues->labels->create()
354 *
355 * @return object
356 *
357 * @since 12.3
358 */
359 public function createLabel($user, $repo, $name, $color)
360 {
361 return $this->labels->create($user, $repo, $name, $color);
362 }
363
364 /**
365 * Method to delete a comment on an issue.
366 *
367 * @param string $user The name of the owner of the GitHub repository.
368 * @param string $repo The name of the GitHub repository.
369 * @param integer $commentId The id of the comment to delete.
370 *
371 * @deprecated use issues->comments->delete()
372 *
373 * @return void
374 *
375 * @since 11.3
376 */
377 public function deleteComment($user, $repo, $commentId)
378 {
379 $this->comments->delete($user, $repo, $commentId);
380 }
381
382 /**
383 * Method to delete a label on a repo.
384 *
385 * @param string $user The name of the owner of the GitHub repository.
386 * @param string $repo The name of the GitHub repository.
387 * @param string $label The label name.
388 *
389 * @deprecated use issues->labels->delete()
390 *
391 * @return object
392 *
393 * @since 12.3
394 */
395 public function deleteLabel($user, $repo, $label)
396 {
397 return $this->labels->delete($user, $repo, $label);
398 }
399
400 /**
401 * Method to update a comment on an issue.
402 *
403 * @param string $user The name of the owner of the GitHub repository.
404 * @param string $repo The name of the GitHub repository.
405 * @param integer $commentId The id of the comment to update.
406 * @param string $body The new body text for the comment.
407 *
408 * @deprecated use issues->comments->edit()
409 *
410 * @return object
411 *
412 * @since 11.3
413 */
414 public function editComment($user, $repo, $commentId, $body)
415 {
416 return $this->comments->edit($user, $repo, $commentId, $body);
417 }
418
419 /**
420 * Method to update a label on a repo.
421 *
422 * @param string $user The name of the owner of the GitHub repository.
423 * @param string $repo The name of the GitHub repository.
424 * @param string $label The label name.
425 * @param string $name The label name.
426 * @param string $color The label color.
427 *
428 * @deprecated use issues->labels->update()
429 *
430 * @return object
431 *
432 * @since 12.3
433 */
434 public function editLabel($user, $repo, $label, $name, $color)
435 {
436 return $this->labels->update($user, $repo, $label, $name, $color);
437 }
438
439 /**
440 * Method to get a specific comment on an issue.
441 *
442 * @param string $user The name of the owner of the GitHub repository.
443 * @param string $repo The name of the GitHub repository.
444 * @param integer $commentId The comment id to get.
445 *
446 * @deprecated use issues->comments->get()
447 *
448 * @return object
449 *
450 * @since 11.3
451 */
452 public function getComment($user, $repo, $commentId)
453 {
454 return $this->comments->get($user, $repo, $commentId);
455 }
456
457 /**
458 * Method to get the list of comments on an issue.
459 *
460 * @param string $user The name of the owner of the GitHub repository.
461 * @param string $repo The name of the GitHub repository.
462 * @param integer $issueId The issue number.
463 * @param integer $page The page number from which to get items.
464 * @param integer $limit The number of items on a page.
465 *
466 * @deprecated use issues->comments->getList()
467 *
468 * @return array
469 *
470 * @since 11.3
471 */
472 public function getComments($user, $repo, $issueId, $page = 0, $limit = 0)
473 {
474 return $this->comments->getList($user, $repo, $issueId, $page, $limit);
475 }
476
477 /**
478 * Method to get a specific label on a repo.
479 *
480 * @param string $user The name of the owner of the GitHub repository.
481 * @param string $repo The name of the GitHub repository.
482 * @param string $name The label name to get.
483 *
484 * @deprecated use issues->labels->get()
485 *
486 * @return object
487 *
488 * @since 12.3
489 */
490 public function getLabel($user, $repo, $name)
491 {
492 return $this->labels->get($user, $repo, $name);
493 }
494
495 /**
496 * Method to get the list of labels on a repo.
497 *
498 * @param string $user The name of the owner of the GitHub repository.
499 * @param string $repo The name of the GitHub repository.
500 *
501 * @deprecated use issues->labels->getList()
502 *
503 * @return array
504 *
505 * @since 12.3
506 */
507 public function getLabels($user, $repo)
508 {
509 return $this->labels->getList($user, $repo);
510 }
511 }
512