Joomla Platform  13.1
Documentation des API du framework Joomla Platform
 Tout Classes Espaces de nommage Fichiers Fonctions Variables Pages
pulls.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 Pull Requests class for the Joomla Platform.
14  *
15  * @package Joomla.Platform
16  * @subpackage GitHub
17  * @since 11.3
18  */
19 class JGithubPulls extends JGithubObject
20 {
21  /**
22  * Method to create a pull request.
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 pull request.
27  * @param string $base The branch (or git ref) you want your changes pulled into. This
28  * should be an existing branch on the current repository. You cannot
29  * submit a pull request to one repo that requests a merge to a base
30  * of another repo.
31  * @param string $head The branch (or git ref) where your changes are implemented.
32  * @param string $body The body text for the new pull request.
33  *
34  * @return object
35  *
36  * @since 11.3
37  */
38  public function create($user, $repo, $title, $base, $head, $body = '')
39  {
40  // Build the request path.
41  $path = '/repos/' . $user . '/' . $repo . '/pulls';
42 
43  // Build the request data.
44  $data = json_encode(
45  array(
46  'title' => $title,
47  'base' => $base,
48  'head' => $head,
49  'body' => $body
50  )
51  );
52 
53  // Send the request.
54  $response = $this->client->post($this->fetchUrl($path), $data);
55 
56  // Validate the response code.
57  if ($response->code != 201)
58  {
59  // Decode the error response and throw an exception.
60  $error = json_decode($response->body);
61  throw new DomainException($error->message, $response->code);
62  }
63 
64  return json_decode($response->body);
65  }
66 
67  /**
68  * Method to create a comment on a pull request.
69  *
70  * @param string $user The name of the owner of the GitHub repository.
71  * @param string $repo The name of the GitHub repository.
72  * @param integer $pullId The pull request number.
73  * @param string $body The comment body text.
74  * @param string $commitId The SHA1 hash of the commit to comment on.
75  * @param string $filePath The Relative path of the file to comment on.
76  * @param string $position The line index in the diff to comment on.
77  *
78  * @return object
79  *
80  * @since 11.3
81  */
82  public function createComment($user, $repo, $pullId, $body, $commitId, $filePath, $position)
83  {
84  // Build the request path.
85  $path = '/repos/' . $user . '/' . $repo . '/pulls/' . (int) $pullId . '/comments';
86 
87  // Build the request data.
88  $data = json_encode(
89  array(
90  'body' => $body,
91  'commit_id' => $commitId,
92  'path' => $filePath,
93  'position' => $position
94  )
95  );
96 
97  // Send the request.
98  $response = $this->client->post($this->fetchUrl($path), $data);
99 
100  // Validate the response code.
101  if ($response->code != 201)
102  {
103  // Decode the error response and throw an exception.
104  $error = json_decode($response->body);
105  throw new DomainException($error->message, $response->code);
106  }
107 
108  return json_decode($response->body);
109  }
110 
111  /**
112  * Method to create a comment in reply to another comment.
113  *
114  * @param string $user The name of the owner of the GitHub repository.
115  * @param string $repo The name of the GitHub repository.
116  * @param integer $pullId The pull request number.
117  * @param string $body The comment body text.
118  * @param integer $inReplyTo The id of the comment to reply to.
119  *
120  * @return object
121  *
122  * @since 11.3
123  */
124  public function createCommentReply($user, $repo, $pullId, $body, $inReplyTo)
125  {
126  // Build the request path.
127  $path = '/repos/' . $user . '/' . $repo . '/pulls/' . (int) $pullId . '/comments';
128 
129  // Build the request data.
130  $data = json_encode(
131  array(
132  'body' => $body,
133  'in_reply_to' => (int) $inReplyTo
134  )
135  );
136 
137  // Send the request.
138  $response = $this->client->post($this->fetchUrl($path), $data);
139 
140  // Validate the response code.
141  if ($response->code != 201)
142  {
143  // Decode the error response and throw an exception.
144  $error = json_decode($response->body);
145  throw new DomainException($error->message, $response->code);
146  }
147 
148  return json_decode($response->body);
149  }
150 
151  /**
152  * Method to create a pull request from an existing issue.
153  *
154  * @param string $user The name of the owner of the GitHub repository.
155  * @param string $repo The name of the GitHub repository.
156  * @param integer $issueId The issue number for which to attach the new pull request.
157  * @param string $base The branch (or git ref) you want your changes pulled into. This
158  * should be an existing branch on the current repository. You cannot
159  * submit a pull request to one repo that requests a merge to a base
160  * of another repo.
161  * @param string $head The branch (or git ref) where your changes are implemented.
162  *
163  * @return object
164  *
165  * @since 11.3
166  */
167  public function createFromIssue($user, $repo, $issueId, $base, $head)
168  {
169  // Build the request path.
170  $path = '/repos/' . $user . '/' . $repo . '/pulls';
171 
172  // Build the request data.
173  $data = json_encode(
174  array(
175  'issue' => (int) $issueId,
176  'base' => $base,
177  'head' => $head
178  )
179  );
180 
181  // Send the request.
182  $response = $this->client->post($this->fetchUrl($path), $data);
183 
184  // Validate the response code.
185  if ($response->code != 201)
186  {
187  // Decode the error response and throw an exception.
188  $error = json_decode($response->body);
189  throw new DomainException($error->message, $response->code);
190  }
191 
192  return json_decode($response->body);
193  }
194 
195  /**
196  * Method to delete a comment on a pull request.
197  *
198  * @param string $user The name of the owner of the GitHub repository.
199  * @param string $repo The name of the GitHub repository.
200  * @param integer $commentId The id of the comment to delete.
201  *
202  * @return void
203  *
204  * @since 11.3
205  */
206  public function deleteComment($user, $repo, $commentId)
207  {
208  // Build the request path.
209  $path = '/repos/' . $user . '/' . $repo . '/pulls/comments/' . (int) $commentId;
210 
211  // Send the request.
212  $response = $this->client->delete($this->fetchUrl($path));
213 
214  // Validate the response code.
215  if ($response->code != 204)
216  {
217  // Decode the error response and throw an exception.
218  $error = json_decode($response->body);
219  throw new DomainException($error->message, $response->code);
220  }
221  }
222 
223  /**
224  * Method to update a pull request.
225  *
226  * @param string $user The name of the owner of the GitHub repository.
227  * @param string $repo The name of the GitHub repository.
228  * @param integer $pullId The pull request number.
229  * @param string $title The optional new title for the pull request.
230  * @param string $body The optional new body text for the pull request.
231  * @param string $state The optional new state for the pull request. [open, closed]
232  *
233  * @return object
234  *
235  * @since 11.3
236  */
237  public function edit($user, $repo, $pullId, $title = null, $body = null, $state = null)
238  {
239  // Build the request path.
240  $path = '/repos/' . $user . '/' . $repo . '/pulls/' . (int) $pullId;
241 
242  // Craete the data object.
243  $data = new stdClass;
244 
245  // If a title is set add it to the data object.
246  if (isset($title))
247  {
248  $data->title = $title;
249  }
250 
251  // If a body is set add it to the data object.
252  if (isset($body))
253  {
254  $data->body = $body;
255  }
256 
257  // If a state is set add it to the data object.
258  if (isset($state))
259  {
260  $data->state = $state;
261  }
262 
263  // Encode the request data.
264  $data = json_encode($data);
265 
266  // Send the request.
267  $response = $this->client->patch($this->fetchUrl($path), $data);
268 
269  // Validate the response code.
270  if ($response->code != 200)
271  {
272  // Decode the error response and throw an exception.
273  $error = json_decode($response->body);
274  throw new DomainException($error->message, $response->code);
275  }
276 
277  return json_decode($response->body);
278  }
279 
280  /**
281  * Method to update a comment on a pull request.
282  *
283  * @param string $user The name of the owner of the GitHub repository.
284  * @param string $repo The name of the GitHub repository.
285  * @param integer $commentId The id of the comment to update.
286  * @param string $body The new body text for the comment.
287  *
288  * @return object
289  *
290  * @since 11.3
291  */
292  public function editComment($user, $repo, $commentId, $body)
293  {
294  // Build the request path.
295  $path = '/repos/' . $user . '/' . $repo . '/pulls/comments/' . (int) $commentId;
296 
297  // Build the request data.
298  $data = json_encode(
299  array(
300  'body' => $body
301  )
302  );
303 
304  // Send the request.
305  $response = $this->client->patch($this->fetchUrl($path), $data);
306 
307  // Validate the response code.
308  if ($response->code != 200)
309  {
310  // Decode the error response and throw an exception.
311  $error = json_decode($response->body);
312  throw new DomainException($error->message, $response->code);
313  }
314 
315  return json_decode($response->body);
316  }
317 
318  /**
319  * Method to get a single pull request.
320  *
321  * @param string $user The name of the owner of the GitHub repository.
322  * @param string $repo The name of the GitHub repository.
323  * @param integer $pullId The pull request number.
324  *
325  * @return object
326  *
327  * @since 11.3
328  */
329  public function get($user, $repo, $pullId)
330  {
331  // Build the request path.
332  $path = '/repos/' . $user . '/' . $repo . '/pulls/' . (int) $pullId;
333 
334  // Send the request.
335  $response = $this->client->get($this->fetchUrl($path));
336 
337  // Validate the response code.
338  if ($response->code != 200)
339  {
340  // Decode the error response and throw an exception.
341  $error = json_decode($response->body);
342  throw new DomainException($error->message, $response->code);
343  }
344 
345  return json_decode($response->body);
346  }
347 
348  /**
349  * Method to get a specific comment on a pull request.
350  *
351  * @param string $user The name of the owner of the GitHub repository.
352  * @param string $repo The name of the GitHub repository.
353  * @param integer $commentId The comment id to get.
354  *
355  * @return object
356  *
357  * @since 11.3
358  */
359  public function getComment($user, $repo, $commentId)
360  {
361  // Build the request path.
362  $path = '/repos/' . $user . '/' . $repo . '/pulls/comments/' . (int) $commentId;
363 
364  // Send the request.
365  $response = $this->client->get($this->fetchUrl($path));
366 
367  // Validate the response code.
368  if ($response->code != 200)
369  {
370  // Decode the error response and throw an exception.
371  $error = json_decode($response->body);
372  throw new DomainException($error->message, $response->code);
373  }
374 
375  return json_decode($response->body);
376  }
377 
378  /**
379  * Method to get the list of comments on a pull request.
380  *
381  * @param string $user The name of the owner of the GitHub repository.
382  * @param string $repo The name of the GitHub repository.
383  * @param integer $pullId The pull request number.
384  * @param integer $page The page number from which to get items.
385  * @param integer $limit The number of items on a page.
386  *
387  * @return array
388  *
389  * @since 11.3
390  */
391  public function getComments($user, $repo, $pullId, $page = 0, $limit = 0)
392  {
393  // Build the request path.
394  $path = '/repos/' . $user . '/' . $repo . '/pulls/' . (int) $pullId . '/comments';
395 
396  // Send the request.
397  $response = $this->client->get($this->fetchUrl($path, $page, $limit));
398 
399  // Validate the response code.
400  if ($response->code != 200)
401  {
402  // Decode the error response and throw an exception.
403  $error = json_decode($response->body);
404  throw new DomainException($error->message, $response->code);
405  }
406 
407  return json_decode($response->body);
408  }
409 
410  /**
411  * Method to get a list of commits for a pull request.
412  *
413  * @param string $user The name of the owner of the GitHub repository.
414  * @param string $repo The name of the GitHub repository.
415  * @param integer $pullId The pull request number.
416  * @param integer $page The page number from which to get items.
417  * @param integer $limit The number of items on a page.
418  *
419  * @return array
420  *
421  * @since 11.3
422  */
423  public function getCommits($user, $repo, $pullId, $page = 0, $limit = 0)
424  {
425  // Build the request path.
426  $path = '/repos/' . $user . '/' . $repo . '/pulls/' . (int) $pullId . '/commits';
427 
428  // Send the request.
429  $response = $this->client->get($this->fetchUrl($path, $page, $limit));
430 
431  // Validate the response code.
432  if ($response->code != 200)
433  {
434  // Decode the error response and throw an exception.
435  $error = json_decode($response->body);
436  throw new DomainException($error->message, $response->code);
437  }
438 
439  return json_decode($response->body);
440  }
441 
442  /**
443  * Method to get a list of files for a pull request.
444  *
445  * @param string $user The name of the owner of the GitHub repository.
446  * @param string $repo The name of the GitHub repository.
447  * @param integer $pullId The pull request number.
448  * @param integer $page The page number from which to get items.
449  * @param integer $limit The number of items on a page.
450  *
451  * @return array
452  *
453  * @since 11.3
454  */
455  public function getFiles($user, $repo, $pullId, $page = 0, $limit = 0)
456  {
457  // Build the request path.
458  $path = '/repos/' . $user . '/' . $repo . '/pulls/' . (int) $pullId . '/files';
459 
460  // Send the request.
461  $response = $this->client->get($this->fetchUrl($path, $page, $limit));
462 
463  // Validate the response code.
464  if ($response->code != 200)
465  {
466  // Decode the error response and throw an exception.
467  $error = json_decode($response->body);
468  throw new DomainException($error->message, $response->code);
469  }
470 
471  return json_decode($response->body);
472  }
473 
474  /**
475  * Method to list pull requests.
476  *
477  * @param string $user The name of the owner of the GitHub repository.
478  * @param string $repo The name of the GitHub repository.
479  * @param string $state The optional state to filter requests by. [open, closed]
480  * @param integer $page The page number from which to get items.
481  * @param integer $limit The number of items on a page.
482  *
483  * @return array
484  *
485  * @since 11.3
486  */
487  public function getList($user, $repo, $state = 'open', $page = 0, $limit = 0)
488  {
489  // Build the request path.
490  $path = '/repos/' . $user . '/' . $repo . '/pulls';
491 
492  // If a state exists append it as an option.
493  if ($state != 'open')
494  {
495  $path .= '?state=' . $state;
496  }
497 
498  // Send the request.
499  $response = $this->client->get($this->fetchUrl($path, $page, $limit));
500 
501  // Validate the response code.
502  if ($response->code != 200)
503  {
504  // Decode the error response and throw an exception.
505  $error = json_decode($response->body);
506  throw new DomainException($error->message, $response->code);
507  }
508 
509  return json_decode($response->body);
510  }
511 
512  /**
513  * Method to check if a pull request has been merged.
514  *
515  * @param string $user The name of the owner of the GitHub repository.
516  * @param string $repo The name of the GitHub repository.
517  * @param integer $pullId The pull request number. The pull request number.
518  *
519  * @return boolean True if the pull request has been merged.
520  *
521  * @since 11.3
522  */
523  public function isMerged($user, $repo, $pullId)
524  {
525  // Build the request path.
526  $path = '/repos/' . $user . '/' . $repo . '/pulls/' . (int) $pullId . '/merge';
527 
528  // Send the request.
529  $response = $this->client->get($this->fetchUrl($path));
530 
531  // Validate the response code.
532  if ($response->code == 204)
533  {
534  return true;
535  }
536  elseif ($response->code == 404)
537  {
538  return false;
539  }
540  else
541  {
542  // Decode the error response and throw an exception.
543  $error = json_decode($response->body);
544  throw new DomainException($error->message, $response->code);
545  }
546  }
547 
548  /**
549  * Method to merge a pull request.
550  *
551  * @param string $user The name of the owner of the GitHub repository.
552  * @param string $repo The name of the GitHub repository.
553  * @param integer $pullId The pull request number.
554  * @param string $message The message that will be used for the merge commit.
555  *
556  * @return object
557  *
558  * @since 11.3
559  */
560  public function merge($user, $repo, $pullId, $message = '')
561  {
562  // Build the request path.
563  $path = '/repos/' . $user . '/' . $repo . '/pulls/' . (int) $pullId . '/merge';
564 
565  // Build the request data.
566  $data = json_encode(
567  array(
568  'commit_message' => $message
569  )
570  );
571 
572  // Send the request.
573  $response = $this->client->put($this->fetchUrl($path), $data);
574 
575  // Validate the response code.
576  if ($response->code != 200)
577  {
578  // Decode the error response and throw an exception.
579  $error = json_decode($response->body);
580  throw new DomainException($error->message, $response->code);
581  }
582 
583  return json_decode($response->body);
584  }
585 }