Source for file gists.php

Documentation is available at gists.php

  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. }

Documentation generated on Tue, 19 Nov 2013 15:03:59 +0100 by phpDocumentor 1.4.3