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