Source for file commits.php

Documentation is available at commits.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 Commits class for the Joomla Platform.
  14.  *
  15.  * @package     Joomla.Platform
  16.  * @subpackage  GitHub
  17.  * @since       12.1
  18.  */
  19. class JGithubCommits extends JGithubObject
  20. {
  21.     /**
  22.      * Method to create a commit.
  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  $message  The commit message.
  27.      * @param   string  $tree     SHA of the tree object this commit points to.
  28.      * @param   array   $parents  Array of the SHAs of the commits that were the parents of this commit.
  29.      *                             If omitted or empty, the commit will be written as a root commit.
  30.      *                             For a single parent, an array of one SHA should be provided.
  31.      *                             For a merge commit, an array of more than one should be provided.
  32.      *
  33.      * @return  object 
  34.      *
  35.      * @since   12.1
  36.      */
  37.     public function create($user, $repo, $message, $tree, array $parents = array())
  38.     {
  39.         // Build the request path.
  40.         $path = '/repos/' . $user . '/' . $repo . '/git/commits';
  41.  
  42.         $data = json_encode(
  43.             array('message' => $message, 'tree' => $tree, 'parents' => $parents)
  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 commit.
  62.      *
  63.      * @param   string   $user      The name of the owner of the GitHub repository.
  64.      * @param   string   $repo      The name of the GitHub repository.
  65.      * @param   string   $sha       The SHA of the commit to comment on.
  66.      * @param   string   $comment   The text of the comment.
  67.      * @param   integer  $line      The line number of the commit to comment on.
  68.      * @param   string   $filepath  A relative path to the file to comment on within the commit.
  69.      * @param   integer  $position  Line index in the diff to comment on.
  70.      *
  71.      * @return  object 
  72.      *
  73.      * @since   12.1
  74.      */
  75.     public function createCommitComment($user, $repo, $sha, $comment, $line, $filepath, $position)
  76.     {
  77.         // Build the request path.
  78.         $path = '/repos/' . $user . '/' . $repo . '/commits/' . $sha . '/comments';
  79.  
  80.         $data = json_encode(
  81.             array(
  82.                 'body' => $comment,
  83.                 'commit_id' => $sha,
  84.                 'line' => (int) $line,
  85.                 'path' => $filepath,
  86.                 'position' => (int) $position
  87.             )
  88.         );
  89.  
  90.         // Send the request.
  91.         $response = $this->client->post($this->fetchUrl($path), $data);
  92.  
  93.         // Validate the response code.
  94.         if ($response->code != 201)
  95.         {
  96.             // Decode the error response and throw an exception.
  97.             $error = json_decode($response->body);
  98.             throw new DomainException($error->message, $response->code);
  99.         }
  100.  
  101.         return json_decode($response->body);
  102.     }
  103.  
  104.     /**
  105.      * Method to delete a comment on a commit.
  106.      *
  107.      * @param   string  $user  The name of the owner of the GitHub repository.
  108.      * @param   string  $repo  The name of the GitHub repository.
  109.      * @param   string  $id    The ID of the comment to edit.
  110.      *
  111.      * @return  object 
  112.      *
  113.      * @since   12.1
  114.      */
  115.     public function deleteCommitComment($user, $repo, $id)
  116.     {
  117.         // Build the request path.
  118.         $path = '/repos/' . $user . '/' . $repo . '/comments/' . $id;
  119.  
  120.         // Send the request.
  121.         $response = $this->client->delete($this->fetchUrl($path));
  122.  
  123.         // Validate the response code.
  124.         if ($response->code != 204)
  125.         {
  126.             // Decode the error response and throw an exception.
  127.             $error = json_decode($response->body);
  128.             throw new DomainException($error->message, $response->code);
  129.         }
  130.  
  131.         return json_decode($response->body);
  132.     }
  133.  
  134.     /**
  135.      * Method to edit a comment on a commit.
  136.      *
  137.      * @param   string  $user     The name of the owner of the GitHub repository.
  138.      * @param   string  $repo     The name of the GitHub repository.
  139.      * @param   string  $id       The ID of the comment to edit.
  140.      * @param   string  $comment  The text of the comment.
  141.      *
  142.      * @return  object 
  143.      *
  144.      * @since   12.1
  145.      */
  146.     public function editCommitComment($user, $repo, $id, $comment)
  147.     {
  148.         // Build the request path.
  149.         $path = '/repos/' . $user . '/' . $repo . '/comments/' . $id;
  150.  
  151.         $data = json_encode(
  152.             array(
  153.                 'body' => $comment
  154.             )
  155.         );
  156.  
  157.         // Send the request.
  158.         $response = $this->client->patch($this->fetchUrl($path), $data);
  159.  
  160.         // Validate the response code.
  161.         if ($response->code != 200)
  162.         {
  163.             // Decode the error response and throw an exception.
  164.             $error = json_decode($response->body);
  165.             throw new DomainException($error->message, $response->code);
  166.         }
  167.  
  168.         return json_decode($response->body);
  169.     }
  170.  
  171.     /**
  172.      * Method to get a single commit for a repository.
  173.      *
  174.      * @param   string   $user   The name of the owner of the GitHub repository.
  175.      * @param   string   $repo   The name of the GitHub repository.
  176.      * @param   string   $sha    The SHA of the commit to retrieve.
  177.      * @param   integer  $page   Page to request
  178.      * @param   integer  $limit  Number of results to return per page
  179.      *
  180.      * @return  array 
  181.      *
  182.      * @since   12.1
  183.      */
  184.     public function getCommit($user, $repo, $sha, $page = 0, $limit = 0)
  185.     {
  186.         // Build the request path.
  187.         $path = '/repos/' . $user . '/' . $repo . '/commits/' . $sha;
  188.  
  189.         // Send the request.
  190.         $response = $this->client->get($this->fetchUrl($path, $page, $limit));
  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 get a single comment on a commit.
  205.      *
  206.      * @param   string   $user  The name of the owner of the GitHub repository.
  207.      * @param   string   $repo  The name of the GitHub repository.
  208.      * @param   integer  $id    ID of the comment to retrieve
  209.      *
  210.      * @return  array 
  211.      *
  212.      * @since   12.1
  213.      */
  214.     public function getCommitComment($user, $repo, $id)
  215.     {
  216.         // Build the request path.
  217.         $path = '/repos/' . $user . '/' . $repo . '/comments/' . $id;
  218.  
  219.         // Send the request.
  220.         $response = $this->client->get($this->fetchUrl($path));
  221.  
  222.         // Validate the response code.
  223.         if ($response->code != 200)
  224.         {
  225.             // Decode the error response and throw an exception.
  226.             $error = json_decode($response->body);
  227.             throw new DomainException($error->message, $response->code);
  228.         }
  229.  
  230.         return json_decode($response->body);
  231.     }
  232.  
  233.     /**
  234.      * Method to get a list of comments for a single commit for a repository.
  235.      *
  236.      * @param   string   $user   The name of the owner of the GitHub repository.
  237.      * @param   string   $repo   The name of the GitHub repository.
  238.      * @param   string   $sha    The SHA of the commit to retrieve.
  239.      * @param   integer  $page   Page to request
  240.      * @param   integer  $limit  Number of results to return per page
  241.      *
  242.      * @return  array 
  243.      *
  244.      * @since   12.1
  245.      */
  246.     public function getCommitComments($user, $repo, $sha, $page = 0, $limit = 0)
  247.     {
  248.         // Build the request path.
  249.         $path = '/repos/' . $user . '/' . $repo . '/commits/' . $sha . '/comments';
  250.  
  251.         // Send the request.
  252.         $response = $this->client->get($this->fetchUrl($path, $page, $limit));
  253.  
  254.         // Validate the response code.
  255.         if ($response->code != 200)
  256.         {
  257.             // Decode the error response and throw an exception.
  258.             $error = json_decode($response->body);
  259.             throw new DomainException($error->message, $response->code);
  260.         }
  261.  
  262.         return json_decode($response->body);
  263.     }
  264.  
  265.     /**
  266.      * Method to get a diff for two commits.
  267.      *
  268.      * @param   string  $user  The name of the owner of the GitHub repository.
  269.      * @param   string  $repo  The name of the GitHub repository.
  270.      * @param   string  $base  The base of the diff, either a commit SHA or branch.
  271.      * @param   string  $head  The head of the diff, either a commit SHA or branch.
  272.      *
  273.      * @return  array 
  274.      *
  275.      * @since   12.1
  276.      */
  277.     public function getDiff($user, $repo, $base, $head)
  278.     {
  279.         // Build the request path.
  280.         $path = '/repos/' . $user . '/' . $repo . '/compare/' . $base . '...' . $head;
  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 list commits for a repository.
  298.      *
  299.      * @param   string   $user   The name of the owner of the GitHub repository.
  300.      * @param   string   $repo   The name of the GitHub repository.
  301.      * @param   integer  $page   Page to request
  302.      * @param   integer  $limit  Number of results to return per page
  303.      *
  304.      * @return  array 
  305.      *
  306.      * @since   12.1
  307.      */
  308.     public function getList($user, $repo, $page = 0, $limit = 0)
  309.     {
  310.         // Build the request path.
  311.         $path = '/repos/' . $user . '/' . $repo . '/commits';
  312.  
  313.         // Send the request.
  314.         $response = $this->client->get($this->fetchUrl($path, $page, $limit));
  315.  
  316.         // Validate the response code.
  317.         if ($response->code != 200)
  318.         {
  319.             // Decode the error response and throw an exception.
  320.             $error = json_decode($response->body);
  321.             throw new DomainException($error->message, $response->code);
  322.         }
  323.  
  324.         return json_decode($response->body);
  325.     }
  326.  
  327.     /**
  328.      * Method to get a list of commit comments for a repository.
  329.      *
  330.      * @param   string   $user   The name of the owner of the GitHub repository.
  331.      * @param   string   $repo   The name of the GitHub repository.
  332.      * @param   integer  $page   Page to request
  333.      * @param   integer  $limit  Number of results to return per page
  334.      *
  335.      * @return  array 
  336.      *
  337.      * @since   12.1
  338.      */
  339.     public function getListComments($user, $repo, $page = 0, $limit = 0)
  340.     {
  341.         // Build the request path.
  342.         $path = '/repos/' . $user . '/' . $repo . '/comments';
  343.  
  344.         // Send the request.
  345.         $response = $this->client->get($this->fetchUrl($path, $page, $limit));
  346.  
  347.         // Validate the response code.
  348.         if ($response->code != 200)
  349.         {
  350.             // Decode the error response and throw an exception.
  351.             $error = json_decode($response->body);
  352.             throw new DomainException($error->message, $response->code);
  353.         }
  354.  
  355.         return json_decode($response->body);
  356.     }
  357. }

Documentation generated on Tue, 19 Nov 2013 14:56:07 +0100 by phpDocumentor 1.4.3