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 Gists class for the Joomla Platform.
14 *
15 * @documentation https://developer.github.com/v3/gists
16 *
17 * @since 11.3
18 * @deprecated 4.0 Use the `joomla/github` package via Composer instead
19 *
20 * @property-read JGithubPackageGistsComments $comments GitHub API object for gist comments.
21 */
22 class JGithubPackageGists extends JGithubPackage
23 {
24 protected $name = 'Gists';
25
26 protected $packages = array(
27 'comments',
28 );
29
30 /**
31 * Method to create a gist.
32 *
33 * @param mixed $files Either an array of file paths or a single file path as a string.
34 * @param boolean $public True if the gist should be public.
35 * @param string $description The optional description of the gist.
36 *
37 * @throws DomainException
38 * @since 11.3
39 *
40 * @return object
41 */
42 public function create($files, $public = false, $description = null)
43 {
44 // Build the request path.
45 $path = '/gists';
46
47 // Build the request data.
48 $data = json_encode(
49 array(
50 'files' => $this->buildFileData((array) $files),
51 'public' => (bool) $public,
52 'description' => $description,
53 )
54 );
55
56 // Send the request.
57 $response = $this->client->post($this->fetchUrl($path), $data);
58
59 // Validate the response code.
60 if ($response->code != 201)
61 {
62 // Decode the error response and throw an exception.
63 $error = json_decode($response->body);
64 throw new DomainException($error->message, $response->code);
65 }
66
67 return json_decode($response->body);
68 }
69
70 /**
71 * Method to delete a gist.
72 *
73 * @param integer $gistId The gist number.
74 *
75 * @throws DomainException
76 * @since 11.3
77 *
78 * @return void
79 */
80 public function delete($gistId)
81 {
82 // Build the request path.
83 $path = '/gists/' . (int) $gistId;
84
85 // Send the request.
86 $response = $this->client->delete($this->fetchUrl($path));
87
88 // Validate the response code.
89 if ($response->code != 204)
90 {
91 // Decode the error response and throw an exception.
92 $error = json_decode($response->body);
93 throw new DomainException($error->message, $response->code);
94 }
95 }
96
97 /**
98 * Method to update a gist.
99 *
100 * @param integer $gistId The gist number.
101 * @param mixed $files Either an array of file paths or a single file path as a string.
102 * @param boolean $public True if the gist should be public.
103 * @param string $description The description of the gist.
104 *
105 * @throws DomainException
106 * @since 11.3
107 *
108 * @return object
109 */
110 public function edit($gistId, $files = null, $public = null, $description = null)
111 {
112 // Build the request path.
113 $path = '/gists/' . (int) $gistId;
114
115 // Craete the data object.
116 $data = new stdClass;
117
118 // If a description is set add it to the data object.
119 if (isset($description))
120 {
121 $data->description = $description;
122 }
123
124 // If the public flag is set add it to the data object.
125 if (isset($public))
126 {
127 $data->public = $public;
128 }
129
130 // If a state is set add it to the data object.
131 if (isset($files))
132 {
133 $data->files = $this->buildFileData((array) $files);
134 }
135
136 // Encode the request data.
137 $data = json_encode($data);
138
139 // Send the request.
140 $response = $this->client->patch($this->fetchUrl($path), $data);
141
142 // Validate the response code.
143 if ($response->code != 200)
144 {
145 // Decode the error response and throw an exception.
146 $error = json_decode($response->body);
147 throw new DomainException($error->message, $response->code);
148 }
149
150 return json_decode($response->body);
151 }
152
153 /**
154 * Method to fork a gist.
155 *
156 * @param integer $gistId The gist number.
157 *
158 * @throws DomainException
159 * @since 11.3
160 *
161 * @return object
162 */
163 public function fork($gistId)
164 {
165 // Build the request path.
166 $path = '/gists/' . (int) $gistId . '/fork';
167
168 // Send the request.
169 // TODO: Verify change
170 $response = $this->client->post($this->fetchUrl($path), '');
171
172 // Validate the response code.
173 if ($response->code != 201)
174 {
175 // Decode the error response and throw an exception.
176 $error = json_decode($response->body);
177 throw new DomainException($error->message, $response->code);
178 }
179
180 return json_decode($response->body);
181 }
182
183 /**
184 * Method to get a single gist.
185 *
186 * @param integer $gistId The gist number.
187 *
188 * @throws DomainException
189 * @since 11.3
190 *
191 * @return object
192 */
193 public function get($gistId)
194 {
195 // Build the request path.
196 $path = '/gists/' . (int) $gistId;
197
198 // Send the request.
199 $response = $this->client->get($this->fetchUrl($path));
200
201 // Validate the response code.
202 if ($response->code != 200)
203 {
204 // Decode the error response and throw an exception.
205 $error = json_decode($response->body);
206 throw new DomainException($error->message, $response->code);
207 }
208
209 return json_decode($response->body);
210 }
211
212 /**
213 * Method to list gists. If a user is authenticated it will return the user's gists, otherwise
214 * it will return all public gists.
215 *
216 * @param integer $page The page number from which to get items.
217 * @param integer $limit The number of items on a page.
218 *
219 * @throws DomainException
220 * @since 11.3
221 *
222 * @return array
223 */
224 public function getList($page = 0, $limit = 0)
225 {
226 // Build the request path.
227 $path = '/gists';
228
229 // Send the request.
230 $response = $this->client->get($this->fetchUrl($path, $page, $limit));
231
232 // Validate the response code.
233 if ($response->code != 200)
234 {
235 // Decode the error response and throw an exception.
236 $error = json_decode($response->body);
237 throw new DomainException($error->message, $response->code);
238 }
239
240 return json_decode($response->body);
241 }
242
243 /**
244 * Method to get a list of gists belonging to a given user.
245 *
246 * @param string $user The name of the GitHub user from which to list gists.
247 * @param integer $page The page number from which to get items.
248 * @param integer $limit The number of items on a page.
249 *
250 * @throws DomainException
251 * @since 11.3
252 *
253 * @return array
254 */
255 public function getListByUser($user, $page = 0, $limit = 0)
256 {
257 // Build the request path.
258 $path = '/users/' . $user . '/gists';
259
260 // Send the request.
261 $response = $this->client->get($this->fetchUrl($path, $page, $limit));
262
263 // Validate the response code.
264 if ($response->code != 200)
265 {
266 // Decode the error response and throw an exception.
267 $error = json_decode($response->body);
268 throw new DomainException($error->message, $response->code);
269 }
270
271 return json_decode($response->body);
272 }
273
274 /**
275 * Method to get a list of all public gists.
276 *
277 * @param integer $page The page number from which to get items.
278 * @param integer $limit The number of items on a page.
279 *
280 * @throws DomainException
281 * @since 11.3
282 *
283 * @return array
284 */
285 public function getListPublic($page = 0, $limit = 0)
286 {
287 // Build the request path.
288 $path = '/gists/public';
289
290 // Send the request.
291 $response = $this->client->get($this->fetchUrl($path, $page, $limit));
292
293 // Validate the response code.
294 if ($response->code != 200)
295 {
296 // Decode the error response and throw an exception.
297 $error = json_decode($response->body);
298 throw new DomainException($error->message, $response->code);
299 }
300
301 return json_decode($response->body);
302 }
303
304 /**
305 * Method to get a list of the authenticated users' starred gists.
306 *
307 * @param integer $page The page number from which to get items.
308 * @param integer $limit The number of items on a page.
309 *
310 * @throws DomainException
311 * @since 11.3
312 *
313 * @return array
314 */
315 public function getListStarred($page = 0, $limit = 0)
316 {
317 // Build the request path.
318 $path = '/gists/starred';
319
320 // Send the request.
321 $response = $this->client->get($this->fetchUrl($path, $page, $limit));
322
323 // Validate the response code.
324 if ($response->code != 200)
325 {
326 // Decode the error response and throw an exception.
327 $error = json_decode($response->body);
328 throw new DomainException($error->message, $response->code);
329 }
330
331 return json_decode($response->body);
332 }
333
334 /**
335 * Method to check if a gist has been starred.
336 *
337 * @param integer $gistId The gist number.
338 *
339 * @throws DomainException
340 * @since 11.3
341 *
342 * @return boolean True if the gist is starred.
343 */
344 public function isStarred($gistId)
345 {
346 // Build the request path.
347 $path = '/gists/' . (int) $gistId . '/star';
348
349 // Send the request.
350 $response = $this->client->get($this->fetchUrl($path));
351
352 // Validate the response code.
353 if ($response->code == 204)
354 {
355 return true;
356 }
357 elseif ($response->code == 404)
358 {
359 return false;
360 }
361 else
362 {
363 // Decode the error response and throw an exception.
364 $error = json_decode($response->body);
365 throw new DomainException($error->message, $response->code);
366 }
367 }
368
369 /**
370 * Method to star a gist.
371 *
372 * @param integer $gistId The gist number.
373 *
374 * @throws DomainException
375 * @since 11.3
376 *
377 * @return void
378 */
379 public function star($gistId)
380 {
381 // Build the request path.
382 $path = '/gists/' . (int) $gistId . '/star';
383
384 // Send the request.
385 $response = $this->client->put($this->fetchUrl($path), '');
386
387 // Validate the response code.
388 if ($response->code != 204)
389 {
390 // Decode the error response and throw an exception.
391 $error = json_decode($response->body);
392 throw new DomainException($error->message, $response->code);
393 }
394 }
395
396 /**
397 * Method to star a gist.
398 *
399 * @param integer $gistId The gist number.
400 *
401 * @throws DomainException
402 * @since 11.3
403 *
404 * @return void
405 */
406 public function unstar($gistId)
407 {
408 // Build the request path.
409 $path = '/gists/' . (int) $gistId . '/star';
410
411 // Send the request.
412 $response = $this->client->delete($this->fetchUrl($path));
413
414 // Validate the response code.
415 if ($response->code != 204)
416 {
417 // Decode the error response and throw an exception.
418 $error = json_decode($response->body);
419 throw new DomainException($error->message, $response->code);
420 }
421 }
422
423 /**
424 * Method to fetch a data array for transmitting to the GitHub API for a list of files based on
425 * an input array of file paths or filename and content pairs.
426 *
427 * @param array $files The list of file paths or filenames and content.
428 *
429 * @throws InvalidArgumentException
430 * @since 11.3
431 *
432 * @return array
433 */
434 protected function buildFileData(array $files)
435 {
436 $data = array();
437
438 foreach ($files as $key => $file)
439 {
440 // If the key isn't numeric, then we are dealing with a file whose content has been supplied
441 if (!is_numeric($key))
442 {
443 $data[$key] = array('content' => $file);
444 }
445
446 // Otherwise, we have been given a path and we have to load the content
447 // Verify that the each file exists.
448 elseif (!file_exists($file))
449 {
450 throw new InvalidArgumentException('The file ' . $file . ' does not exist.');
451 }
452 else
453 {
454 $data[basename($file)] = array('content' => file_get_contents($file));
455 }
456 }
457
458 return $data;
459 }
460
461 /*
462 * Deprecated methods
463 */
464
465 /**
466 * Method to create a comment on a gist.
467 *
468 * @param integer $gistId The gist number.
469 * @param string $body The comment body text.
470 *
471 * @deprecated use gists->comments->create()
472 *
473 * @return object
474 *
475 * @since 11.3
476 */
477 public function createComment($gistId, $body)
478 {
479 return $this->comments->create($gistId, $body);
480 }
481
482 /**
483 * Method to delete a comment on a gist.
484 *
485 * @param integer $commentId The id of the comment to delete.
486 *
487 * @deprecated use gists->comments->delete()
488 *
489 * @return void
490 *
491 * @since 11.3
492 */
493 public function deleteComment($commentId)
494 {
495 $this->comments->delete($commentId);
496 }
497
498 /**
499 * Method to update a comment on a gist.
500 *
501 * @param integer $commentId The id of the comment to update.
502 * @param string $body The new body text for the comment.
503 *
504 * @deprecated use gists->comments->edit()
505 *
506 * @return object
507 *
508 * @since 11.3
509 */
510 public function editComment($commentId, $body)
511 {
512 return $this->comments->edit($commentId, $body);
513 }
514
515 /**
516 * Method to get a specific comment on a gist.
517 *
518 * @param integer $commentId The comment id to get.
519 *
520 * @deprecated use gists->comments->get()
521 *
522 * @return object
523 *
524 * @since 11.3
525 */
526 public function getComment($commentId)
527 {
528 return $this->comments->get($commentId);
529 }
530
531 /**
532 * Method to get the list of comments on a gist.
533 *
534 * @param integer $gistId The gist number.
535 * @param integer $page The page number from which to get items.
536 * @param integer $limit The number of items on a page.
537 *
538 * @deprecated use gists->comments->getList()
539 *
540 * @return array
541 *
542 * @since 11.3
543 */
544 public function getComments($gistId, $page = 0, $limit = 0)
545 {
546 return $this->comments->getList($gistId, $page, $limit);
547 }
548 }
549