Source for file pulls.php

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

Documentation generated on Tue, 19 Nov 2013 15:11:24 +0100 by phpDocumentor 1.4.3