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