Joomla Platform  13.1
Documentation des API du framework Joomla Platform
 Tout Classes Espaces de nommage Fichiers Fonctions Variables Pages
issues.php
Aller à la documentation de ce fichier.
1 <?php
2 /**
3  * @package Joomla.Platform
4  * @subpackage GitHub
5  *
6  * @copyright Copyright (C) 2005 - 2013 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  * @package Joomla.Platform
16  * @subpackage GitHub
17  * @since 11.3
18  */
19 class JGithubIssues extends JGithubObject
20 {
21  /**
22  * Method to create an issue.
23  *
24  * @param string $user The name of the owner of the GitHub repository.
25  * @param string $repo The name of the GitHub repository.
26  * @param string $title The title of the new issue.
27  * @param string $body The body text for the new issue.
28  * @param string $assignee The login for the GitHub user that this issue should be assigned to.
29  * @param integer $milestone The milestone to associate this issue with.
30  * @param array $labels The labels to associate with this issue.
31  *
32  * @return object
33  *
34  * @since 11.3
35  */
36  public function create($user, $repo, $title, $body = null, $assignee = null, $milestone = null, array $labels = null)
37  {
38  // Build the request path.
39  $path = '/repos/' . $user . '/' . $repo . '/issues';
40 
41  // Ensure that we have a non-associative array.
42  if (isset($labels))
43  {
44  $labels = array_values($labels);
45  }
46 
47  // Build the request data.
48  $data = json_encode(
49  array(
50  'title' => $title,
51  'assignee' => $assignee,
52  'milestone' => $milestone,
53  'labels' => $labels,
54  'body' => $body
55  )
56  );
57 
58  // Send the request.
59  $response = $this->client->post($this->fetchUrl($path), $data);
60 
61  // Validate the response code.
62  if ($response->code != 201)
63  {
64  // Decode the error response and throw an exception.
65  $error = json_decode($response->body);
66  throw new DomainException($error->message, $response->code);
67  }
68 
69  return json_decode($response->body);
70  }
71 
72  /**
73  * Method to create a comment on an issue.
74  *
75  * @param string $user The name of the owner of the GitHub repository.
76  * @param string $repo The name of the GitHub repository.
77  * @param integer $issueId The issue number.
78  * @param string $body The comment body text.
79  *
80  * @return object
81  *
82  * @since 11.3
83  */
84  public function createComment($user, $repo, $issueId, $body)
85  {
86  // Build the request path.
87  $path = '/repos/' . $user . '/' . $repo . '/issues/' . (int) $issueId . '/comments';
88 
89  // Build the request data.
90  $data = json_encode(
91  array(
92  'body' => $body,
93  )
94  );
95 
96  // Send the request.
97  $response = $this->client->post($this->fetchUrl($path), $data);
98 
99  // Validate the response code.
100  if ($response->code != 201)
101  {
102  // Decode the error response and throw an exception.
103  $error = json_decode($response->body);
104  throw new DomainException($error->message, $response->code);
105  }
106 
107  return json_decode($response->body);
108  }
109 
110  /**
111  * Method to create a label on a repo.
112  *
113  * @param string $user The name of the owner of the GitHub repository.
114  * @param string $repo The name of the GitHub repository.
115  * @param string $name The label name.
116  * @param string $color The label color.
117  *
118  * @return object
119  *
120  * @since 12.3
121  */
122  public function createLabel($user, $repo, $name, $color)
123  {
124  // Build the request path.
125  $path = '/repos/' . $user . '/' . $repo . '/labels';
126 
127  // Build the request data.
128  $data = json_encode(
129  array(
130  'name' => $name,
131  'color' => $color
132  )
133  );
134 
135  // Send the request.
136  $response = $this->client->post($this->fetchUrl($path), $data);
137 
138  // Validate the response code.
139  if ($response->code != 201)
140  {
141  // Decode the error response and throw an exception.
142  $error = json_decode($response->body);
143  throw new DomainException($error->message, $response->code);
144  }
145 
146  return json_decode($response->body);
147  }
148 
149  /**
150  * Method to delete a comment on an issue.
151  *
152  * @param string $user The name of the owner of the GitHub repository.
153  * @param string $repo The name of the GitHub repository.
154  * @param integer $commentId The id of the comment to delete.
155  *
156  * @return void
157  *
158  * @since 11.3
159  */
160  public function deleteComment($user, $repo, $commentId)
161  {
162  // Build the request path.
163  $path = '/repos/' . $user . '/' . $repo . '/issues/comments/' . (int) $commentId;
164 
165  // Send the request.
166  $response = $this->client->delete($this->fetchUrl($path));
167 
168  // Validate the response code.
169  if ($response->code != 204)
170  {
171  // Decode the error response and throw an exception.
172  $error = json_decode($response->body);
173  throw new DomainException($error->message, $response->code);
174  }
175  }
176 
177  /**
178  * Method to delete a label on a repo.
179  *
180  * @param string $user The name of the owner of the GitHub repository.
181  * @param string $repo The name of the GitHub repository.
182  * @param string $label The label name.
183  *
184  * @return object
185  *
186  * @since 12.3
187  */
188  public function deleteLabel($user, $repo, $label)
189  {
190  // Build the request path.
191  $path = '/repos/' . $user . '/' . $repo . '/labels/' . $label;
192 
193  // Send the request.
194  $response = $this->client->delete($this->fetchUrl($path));
195 
196  // Validate the response code.
197  if ($response->code != 204)
198  {
199  // Decode the error response and throw an exception.
200  $error = json_decode($response->body);
201  throw new DomainException($error->message, $response->code);
202  }
203  }
204 
205  /**
206  * Method to update an issue.
207  *
208  * @param string $user The name of the owner of the GitHub repository.
209  * @param string $repo The name of the GitHub repository.
210  * @param integer $issueId The issue number.
211  * @param string $state The optional new state for the issue. [open, closed]
212  * @param string $title The title of the new issue.
213  * @param string $body The body text for the new issue.
214  * @param string $assignee The login for the GitHub user that this issue should be assigned to.
215  * @param integer $milestone The milestone to associate this issue with.
216  * @param array $labels The labels to associate with this issue.
217  *
218  * @return object
219  *
220  * @since 11.3
221  */
222  public function edit($user, $repo, $issueId, $state = null, $title = null, $body = null, $assignee = null, $milestone = null, array $labels = null)
223  {
224  // Build the request path.
225  $path = '/repos/' . $user . '/' . $repo . '/issues/' . (int) $issueId;
226 
227  // Craete the data object.
228  $data = new stdClass;
229 
230  // If a title is set add it to the data object.
231  if (isset($title))
232  {
233  $data->title = $title;
234  }
235 
236  // If a body is set add it to the data object.
237  if (isset($body))
238  {
239  $data->body = $body;
240  }
241 
242  // If a state is set add it to the data object.
243  if (isset($state))
244  {
245  $data->state = $state;
246  }
247 
248  // If an assignee is set add it to the data object.
249  if (isset($assignee))
250  {
251  $data->assignee = $assignee;
252  }
253 
254  // If a milestone is set add it to the data object.
255  if (isset($milestone))
256  {
257  $data->milestone = $milestone;
258  }
259 
260  // If labels are set add them to the data object.
261  if (isset($labels))
262  {
263  // Ensure that we have a non-associative array.
264  if (isset($labels))
265  {
266  $labels = array_values($labels);
267  }
268 
269  $data->labels = $labels;
270  }
271 
272  // Encode the request data.
273  $data = json_encode($data);
274 
275  // Send the request.
276  $response = $this->client->patch($this->fetchUrl($path), $data);
277 
278  // Validate the response code.
279  if ($response->code != 200)
280  {
281  // Decode the error response and throw an exception.
282  $error = json_decode($response->body);
283  throw new DomainException($error->message, $response->code);
284  }
285 
286  return json_decode($response->body);
287  }
288 
289  /**
290  * Method to update a comment on an issue.
291  *
292  * @param string $user The name of the owner of the GitHub repository.
293  * @param string $repo The name of the GitHub repository.
294  * @param integer $commentId The id of the comment to update.
295  * @param string $body The new body text for the comment.
296  *
297  * @return object
298  *
299  * @since 11.3
300  */
301  public function editComment($user, $repo, $commentId, $body)
302  {
303  // Build the request path.
304  $path = '/repos/' . $user . '/' . $repo . '/issues/comments/' . (int) $commentId;
305 
306  // Build the request data.
307  $data = json_encode(
308  array(
309  'body' => $body
310  )
311  );
312 
313  // Send the request.
314  $response = $this->client->patch($this->fetchUrl($path), $data);
315 
316  // Validate the response code.
317  if ($response->code != 200)
318  {
319  // Decode the error response and throw an exception.
320  $error = json_decode($response->body);
321  throw new DomainException($error->message, $response->code);
322  }
323 
324  return json_decode($response->body);
325  }
326 
327  /**
328  * Method to update a label on a repo.
329  *
330  * @param string $user The name of the owner of the GitHub repository.
331  * @param string $repo The name of the GitHub repository.
332  * @param string $label The label name.
333  * @param string $name The label name.
334  * @param string $color The label color.
335  *
336  * @return object
337  *
338  * @since 12.3
339  */
340  public function editLabel($user, $repo, $label, $name, $color)
341  {
342  // Build the request path.
343  $path = '/repos/' . $user . '/' . $repo . '/labels/' . $label;
344 
345  // Build the request data.
346  $data = json_encode(
347  array(
348  'name' => $name,
349  'color' => $color
350  )
351  );
352 
353  // Send the request.
354  $response = $this->client->patch($this->fetchUrl($path), $data);
355 
356  // Validate the response code.
357  if ($response->code != 200)
358  {
359  // Decode the error response and throw an exception.
360  $error = json_decode($response->body);
361  throw new DomainException($error->message, $response->code);
362  }
363 
364  return json_decode($response->body);
365  }
366 
367  /**
368  * Method to get a single issue.
369  *
370  * @param string $user The name of the owner of the GitHub repository.
371  * @param string $repo The name of the GitHub repository.
372  * @param integer $issueId The issue number.
373  *
374  * @return object
375  *
376  * @since 11.3
377  */
378  public function get($user, $repo, $issueId)
379  {
380  // Build the request path.
381  $path = '/repos/' . $user . '/' . $repo . '/issues/' . (int) $issueId;
382 
383  // Send the request.
384  $response = $this->client->get($this->fetchUrl($path));
385 
386  // Validate the response code.
387  if ($response->code != 200)
388  {
389  // Decode the error response and throw an exception.
390  $error = json_decode($response->body);
391  throw new DomainException($error->message, $response->code);
392  }
393 
394  return json_decode($response->body);
395  }
396 
397  /**
398  * Method to get a specific comment on an issue.
399  *
400  * @param string $user The name of the owner of the GitHub repository.
401  * @param string $repo The name of the GitHub repository.
402  * @param integer $commentId The comment id to get.
403  *
404  * @return object
405  *
406  * @since 11.3
407  */
408  public function getComment($user, $repo, $commentId)
409  {
410  // Build the request path.
411  $path = '/repos/' . $user . '/' . $repo . '/issues/comments/' . (int) $commentId;
412 
413  // Send the request.
414  $response = $this->client->get($this->fetchUrl($path));
415 
416  // Validate the response code.
417  if ($response->code != 200)
418  {
419  // Decode the error response and throw an exception.
420  $error = json_decode($response->body);
421  throw new DomainException($error->message, $response->code);
422  }
423 
424  return json_decode($response->body);
425  }
426 
427  /**
428  * Method to get the list of comments on an issue.
429  *
430  * @param string $user The name of the owner of the GitHub repository.
431  * @param string $repo The name of the GitHub repository.
432  * @param integer $issueId The issue number.
433  * @param integer $page The page number from which to get items.
434  * @param integer $limit The number of items on a page.
435  *
436  * @return array
437  *
438  * @since 11.3
439  */
440  public function getComments($user, $repo, $issueId, $page = 0, $limit = 0)
441  {
442  // Build the request path.
443  $path = '/repos/' . $user . '/' . $repo . '/issues/' . (int) $issueId . '/comments';
444 
445  // Send the request.
446  $response = $this->client->get($this->fetchUrl($path, $page, $limit));
447 
448  // Validate the response code.
449  if ($response->code != 200)
450  {
451  // Decode the error response and throw an exception.
452  $error = json_decode($response->body);
453  throw new DomainException($error->message, $response->code);
454  }
455 
456  return json_decode($response->body);
457  }
458 
459  /**
460  * Method to get a specific label on a repo.
461  *
462  * @param string $user The name of the owner of the GitHub repository.
463  * @param string $repo The name of the GitHub repository.
464  * @param string $name The label name to get.
465  *
466  * @return object
467  *
468  * @since 12.3
469  */
470  public function getLabel($user, $repo, $name)
471  {
472  // Build the request path.
473  $path = '/repos/' . $user . '/' . $repo . '/labels/' . $name;
474 
475  // Send the request.
476  $response = $this->client->get($this->fetchUrl($path));
477 
478  // Validate the response code.
479  if ($response->code != 200)
480  {
481  // Decode the error response and throw an exception.
482  $error = json_decode($response->body);
483  throw new DomainException($error->message, $response->code);
484  }
485 
486  return json_decode($response->body);
487  }
488 
489  /**
490  * Method to get the list of labels on a repo.
491  *
492  * @param string $user The name of the owner of the GitHub repository.
493  * @param string $repo The name of the GitHub repository.
494  *
495  * @return array
496  *
497  * @since 12.3
498  */
499  public function getLabels($user, $repo)
500  {
501  // Build the request path.
502  $path = '/repos/' . $user . '/' . $repo . '/labels';
503 
504  // Send the request.
505  $response = $this->client->get($this->fetchUrl($path));
506 
507  // Validate the response code.
508  if ($response->code != 200)
509  {
510  // Decode the error response and throw an exception.
511  $error = json_decode($response->body);
512  throw new DomainException($error->message, $response->code);
513  }
514 
515  return json_decode($response->body);
516  }
517 
518  /**
519  * Method to list an authenticated user's issues.
520  *
521  * @param string $filter The filter type: assigned, created, mentioned, subscribed.
522  * @param string $state The optional state to filter requests by. [open, closed]
523  * @param string $labels The list of comma separated Label names. Example: bug,ui,@high.
524  * @param string $sort The sort order: created, updated, comments, default: created.
525  * @param string $direction The list direction: asc or desc, default: desc.
526  * @param JDate $since The date/time since when issues should be returned.
527  * @param integer $page The page number from which to get items.
528  * @param integer $limit The number of items on a page.
529  *
530  * @return array
531  *
532  * @since 11.3
533  */
534  public function getList($filter = null, $state = null, $labels = null, $sort = null, $direction = null, JDate $since = null, $page = 0, $limit = 0)
535  {
536  // Build the request path.
537  $path = '/issues';
538 
539  // TODO Implement the filtering options.
540 
541  // Send the request.
542  $response = $this->client->get($this->fetchUrl($path, $page, $limit));
543 
544  // Validate the response code.
545  if ($response->code != 200)
546  {
547  // Decode the error response and throw an exception.
548  $error = json_decode($response->body);
549  throw new DomainException($error->message, $response->code);
550  }
551 
552  return json_decode($response->body);
553  }
554 
555  /**
556  * Method to list issues.
557  *
558  * @param string $user The name of the owner of the GitHub repository.
559  * @param string $repo The name of the GitHub repository.
560  * @param string $milestone The milestone number, 'none', or *.
561  * @param string $state The optional state to filter requests by. [open, closed]
562  * @param string $assignee The assignee name, 'none', or *.
563  * @param string $mentioned The GitHub user name.
564  * @param string $labels The list of comma separated Label names. Example: bug,ui,@high.
565  * @param string $sort The sort order: created, updated, comments, default: created.
566  * @param string $direction The list direction: asc or desc, default: desc.
567  * @param JDate $since The date/time since when issues should be returned.
568  * @param integer $page The page number from which to get items.
569  * @param integer $limit The number of items on a page.
570  *
571  * @return array
572  *
573  * @since 11.3
574  */
575  public function getListByRepository($user, $repo, $milestone = null, $state = null, $assignee = null, $mentioned = null, $labels = null,
576  $sort = null, $direction = null, JDate $since = null, $page = 0, $limit = 0)
577  {
578  // Build the request path.
579  $path = '/repos/' . $user . '/' . $repo . '/issues';
580 
581  $uri = new JUri($this->fetchUrl($path, $page, $limit));
582 
583  if ($milestone)
584  {
585  $uri->setVar('milestone', $milestone);
586  }
587 
588  if ($state)
589  {
590  $uri->setVar('state', $state);
591  }
592 
593  if ($assignee)
594  {
595  $uri->setVar('assignee', $assignee);
596  }
597 
598  if ($mentioned)
599  {
600  $uri->setVar('mentioned', $mentioned);
601  }
602 
603  if ($labels)
604  {
605  $uri->setVar('labels', $labels);
606  }
607 
608  if ($sort)
609  {
610  $uri->setVar('sort', $sort);
611  }
612 
613  if ($direction)
614  {
615  $uri->setVar('direction', $direction);
616  }
617 
618  if ($since)
619  {
620  $uri->setVar('since', $since->toISO8601());
621  }
622 
623  // Send the request.
624  $response = $this->client->get((string) $uri);
625 
626  // Validate the response code.
627  if ($response->code != 200)
628  {
629  // Decode the error response and throw an exception.
630  $error = json_decode($response->body);
631  throw new DomainException($error->message, $response->code);
632  }
633 
634  return json_decode($response->body);
635  }
636 }