Source for file issues.php

Documentation is available at issues.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 Issues class for the Joomla Platform.
  14.  *
  15.  * @package     Joomla.Platform
  16.  * @subpackage  GitHub
  17.  * @since       11.3
  18.  */
  19. class JGithubIssues extends JGithubObject
  20. {
  21.     /**
  22.      * Method to create an issue.
  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 issue.
  27.      * @param   string   $body       The body text for the new issue.
  28.      * @param   string   $assignee   The login for the GitHub user that this issue should be assigned to.
  29.      * @param   integer  $milestone  The milestone to associate this issue with.
  30.      * @param   array    $labels     The labels to associate with this issue.
  31.      *
  32.      * @return  object 
  33.      *
  34.      * @since   11.3
  35.      */
  36.     public function create($user, $repo, $title, $body = null, $assignee = null, $milestone = null, array $labels = null)
  37.     {
  38.         // Build the request path.
  39.         $path = '/repos/' . $user . '/' . $repo . '/issues';
  40.  
  41.         // Ensure that we have a non-associative array.
  42.         if (isset($labels))
  43.         {
  44.             $labels = array_values($labels);
  45.         }
  46.  
  47.         // Build the request data.
  48.         $data = json_encode(
  49.             array(
  50.                 'title' => $title,
  51.                 'assignee' => $assignee,
  52.                 'milestone' => $milestone,
  53.                 'labels' => $labels,
  54.                 'body' => $body
  55.             )
  56.         );
  57.  
  58.         // Send the request.
  59.         $response = $this->client->post($this->fetchUrl($path), $data);
  60.  
  61.         // Validate the response code.
  62.         if ($response->code != 201)
  63.         {
  64.             // Decode the error response and throw an exception.
  65.             $error = json_decode($response->body);
  66.             throw new DomainException($error->message, $response->code);
  67.         }
  68.  
  69.         return json_decode($response->body);
  70.     }
  71.  
  72.     /**
  73.      * Method to create a comment on an issue.
  74.      *
  75.      * @param   string   $user     The name of the owner of the GitHub repository.
  76.      * @param   string   $repo     The name of the GitHub repository.
  77.      * @param   integer  $issueId  The issue number.
  78.      * @param   string   $body     The comment body text.
  79.      *
  80.      * @return  object 
  81.      *
  82.      * @since   11.3
  83.      */
  84.     public function createComment($user, $repo, $issueId, $body)
  85.     {
  86.         // Build the request path.
  87.         $path = '/repos/' . $user . '/' . $repo . '/issues/' . (int) $issueId . '/comments';
  88.  
  89.         // Build the request data.
  90.         $data = json_encode(
  91.             array(
  92.                 'body' => $body,
  93.             )
  94.         );
  95.  
  96.         // Send the request.
  97.         $response = $this->client->post($this->fetchUrl($path), $data);
  98.  
  99.         // Validate the response code.
  100.         if ($response->code != 201)
  101.         {
  102.             // Decode the error response and throw an exception.
  103.             $error = json_decode($response->body);
  104.             throw new DomainException($error->message, $response->code);
  105.         }
  106.  
  107.         return json_decode($response->body);
  108.     }
  109.  
  110.     /**
  111.      * Method to create a label on a repo.
  112.      *
  113.      * @param   string  $user   The name of the owner of the GitHub repository.
  114.      * @param   string  $repo   The name of the GitHub repository.
  115.      * @param   string  $name   The label name.
  116.      * @param   string  $color  The label color.
  117.      *
  118.      * @return  object 
  119.      *
  120.      * @since   12.3
  121.      */
  122.     public function createLabel($user, $repo, $name, $color)
  123.     {
  124.         // Build the request path.
  125.         $path = '/repos/' . $user . '/' . $repo . '/labels';
  126.  
  127.         // Build the request data.
  128.         $data = json_encode(
  129.             array(
  130.                 'name' => $name,
  131.                 'color' => $color
  132.             )
  133.         );
  134.  
  135.         // Send the request.
  136.         $response = $this->client->post($this->fetchUrl($path), $data);
  137.  
  138.         // Validate the response code.
  139.         if ($response->code != 201)
  140.         {
  141.             // Decode the error response and throw an exception.
  142.             $error = json_decode($response->body);
  143.             throw new DomainException($error->message, $response->code);
  144.         }
  145.  
  146.         return json_decode($response->body);
  147.     }
  148.  
  149.     /**
  150.      * Method to delete a comment on an issue.
  151.      *
  152.      * @param   string   $user       The name of the owner of the GitHub repository.
  153.      * @param   string   $repo       The name of the GitHub repository.
  154.      * @param   integer  $commentId  The id of the comment to delete.
  155.      *
  156.      * @return  void 
  157.      *
  158.      * @since   11.3
  159.      */
  160.     public function deleteComment($user, $repo, $commentId)
  161.     {
  162.         // Build the request path.
  163.         $path = '/repos/' . $user . '/' . $repo . '/issues/comments/' . (int) $commentId;
  164.  
  165.         // Send the request.
  166.         $response = $this->client->delete($this->fetchUrl($path));
  167.  
  168.         // Validate the response code.
  169.         if ($response->code != 204)
  170.         {
  171.             // Decode the error response and throw an exception.
  172.             $error = json_decode($response->body);
  173.             throw new DomainException($error->message, $response->code);
  174.         }
  175.     }
  176.  
  177.     /**
  178.      * Method to delete a label on a repo.
  179.      *
  180.      * @param   string  $user   The name of the owner of the GitHub repository.
  181.      * @param   string  $repo   The name of the GitHub repository.
  182.      * @param   string  $label  The label name.
  183.      *
  184.      * @return  object 
  185.      *
  186.      * @since   12.3
  187.      */
  188.     public function deleteLabel($user, $repo, $label)
  189.     {
  190.         // Build the request path.
  191.         $path = '/repos/' . $user . '/' . $repo . '/labels/' . $label;
  192.  
  193.         // Send the request.
  194.         $response = $this->client->delete($this->fetchUrl($path));
  195.  
  196.         // Validate the response code.
  197.         if ($response->code != 204)
  198.         {
  199.             // Decode the error response and throw an exception.
  200.             $error = json_decode($response->body);
  201.             throw new DomainException($error->message, $response->code);
  202.         }
  203.     }
  204.  
  205.     /**
  206.      * Method to update an issue.
  207.      *
  208.      * @param   string   $user       The name of the owner of the GitHub repository.
  209.      * @param   string   $repo       The name of the GitHub repository.
  210.      * @param   integer  $issueId    The issue number.
  211.      * @param   string   $state      The optional new state for the issue. [open, closed]
  212.      * @param   string   $title      The title of the new issue.
  213.      * @param   string   $body       The body text for the new issue.
  214.      * @param   string   $assignee   The login for the GitHub user that this issue should be assigned to.
  215.      * @param   integer  $milestone  The milestone to associate this issue with.
  216.      * @param   array    $labels     The labels to associate with this issue.
  217.      *
  218.      * @return  object 
  219.      *
  220.      * @since   11.3
  221.      */
  222.     public function edit($user, $repo, $issueId, $state = null, $title = null, $body = null, $assignee = null, $milestone = null, array $labels = null)
  223.     {
  224.         // Build the request path.
  225.         $path = '/repos/' . $user . '/' . $repo . '/issues/' . (int) $issueId;
  226.  
  227.         // Craete the data object.
  228.         $data = new stdClass;
  229.  
  230.         // If a title is set add it to the data object.
  231.         if (isset($title))
  232.         {
  233.             $data->title = $title;
  234.         }
  235.  
  236.         // If a body is set add it to the data object.
  237.         if (isset($body))
  238.         {
  239.             $data->body = $body;
  240.         }
  241.  
  242.         // If a state is set add it to the data object.
  243.         if (isset($state))
  244.         {
  245.             $data->state = $state;
  246.         }
  247.  
  248.         // If an assignee is set add it to the data object.
  249.         if (isset($assignee))
  250.         {
  251.             $data->assignee = $assignee;
  252.         }
  253.  
  254.         // If a milestone is set add it to the data object.
  255.         if (isset($milestone))
  256.         {
  257.             $data->milestone = $milestone;
  258.         }
  259.  
  260.         // If labels are set add them to the data object.
  261.         if (isset($labels))
  262.         {
  263.             // Ensure that we have a non-associative array.
  264.             if (isset($labels))
  265.             {
  266.                 $labels = array_values($labels);
  267.             }
  268.  
  269.             $data->labels = $labels;
  270.         }
  271.  
  272.         // Encode the request data.
  273.         $data = json_encode($data);
  274.  
  275.         // Send the request.
  276.         $response = $this->client->patch($this->fetchUrl($path), $data);
  277.  
  278.         // Validate the response code.
  279.         if ($response->code != 200)
  280.         {
  281.             // Decode the error response and throw an exception.
  282.             $error = json_decode($response->body);
  283.             throw new DomainException($error->message, $response->code);
  284.         }
  285.  
  286.         return json_decode($response->body);
  287.     }
  288.  
  289.     /**
  290.      * Method to update a comment on an issue.
  291.      *
  292.      * @param   string   $user       The name of the owner of the GitHub repository.
  293.      * @param   string   $repo       The name of the GitHub repository.
  294.      * @param   integer  $commentId  The id of the comment to update.
  295.      * @param   string   $body       The new body text for the comment.
  296.      *
  297.      * @return  object 
  298.      *
  299.      * @since   11.3
  300.      */
  301.     public function editComment($user, $repo, $commentId, $body)
  302.     {
  303.         // Build the request path.
  304.         $path = '/repos/' . $user . '/' . $repo . '/issues/comments/' . (int) $commentId;
  305.  
  306.         // Build the request data.
  307.         $data = json_encode(
  308.             array(
  309.                 'body' => $body
  310.             )
  311.         );
  312.  
  313.         // Send the request.
  314.         $response = $this->client->patch($this->fetchUrl($path), $data);
  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 update a label on a repo.
  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   string  $label  The label name.
  333.      * @param   string  $name   The label name.
  334.      * @param   string  $color  The label color.
  335.      *
  336.      * @return  object 
  337.      *
  338.      * @since   12.3
  339.      */
  340.     public function editLabel($user, $repo, $label, $name, $color)
  341.     {
  342.         // Build the request path.
  343.         $path = '/repos/' . $user . '/' . $repo . '/labels/' . $label;
  344.  
  345.         // Build the request data.
  346.         $data = json_encode(
  347.             array(
  348.                 'name' => $name,
  349.                 'color' => $color
  350.             )
  351.         );
  352.  
  353.         // Send the request.
  354.         $response = $this->client->patch($this->fetchUrl($path), $data);
  355.  
  356.         // Validate the response code.
  357.         if ($response->code != 200)
  358.         {
  359.             // Decode the error response and throw an exception.
  360.             $error = json_decode($response->body);
  361.             throw new DomainException($error->message, $response->code);
  362.         }
  363.  
  364.         return json_decode($response->body);
  365.     }
  366.  
  367.     /**
  368.      * Method to get a single issue.
  369.      *
  370.      * @param   string   $user     The name of the owner of the GitHub repository.
  371.      * @param   string   $repo     The name of the GitHub repository.
  372.      * @param   integer  $issueId  The issue number.
  373.      *
  374.      * @return  object 
  375.      *
  376.      * @since   11.3
  377.      */
  378.     public function get($user, $repo, $issueId)
  379.     {
  380.         // Build the request path.
  381.         $path = '/repos/' . $user . '/' . $repo . '/issues/' . (int) $issueId;
  382.  
  383.         // Send the request.
  384.         $response = $this->client->get($this->fetchUrl($path));
  385.  
  386.         // Validate the response code.
  387.         if ($response->code != 200)
  388.         {
  389.             // Decode the error response and throw an exception.
  390.             $error = json_decode($response->body);
  391.             throw new DomainException($error->message, $response->code);
  392.         }
  393.  
  394.         return json_decode($response->body);
  395.     }
  396.  
  397.     /**
  398.      * Method to get a specific comment on an issue.
  399.      *
  400.      * @param   string   $user       The name of the owner of the GitHub repository.
  401.      * @param   string   $repo       The name of the GitHub repository.
  402.      * @param   integer  $commentId  The comment id to get.
  403.      *
  404.      * @return  object 
  405.      *
  406.      * @since   11.3
  407.      */
  408.     public function getComment($user, $repo, $commentId)
  409.     {
  410.         // Build the request path.
  411.         $path = '/repos/' . $user . '/' . $repo . '/issues/comments/' . (int) $commentId;
  412.  
  413.         // Send the request.
  414.         $response = $this->client->get($this->fetchUrl($path));
  415.  
  416.         // Validate the response code.
  417.         if ($response->code != 200)
  418.         {
  419.             // Decode the error response and throw an exception.
  420.             $error = json_decode($response->body);
  421.             throw new DomainException($error->message, $response->code);
  422.         }
  423.  
  424.         return json_decode($response->body);
  425.     }
  426.  
  427.     /**
  428.      * Method to get the list of comments on an issue.
  429.      *
  430.      * @param   string   $user     The name of the owner of the GitHub repository.
  431.      * @param   string   $repo     The name of the GitHub repository.
  432.      * @param   integer  $issueId  The issue number.
  433.      * @param   integer  $page     The page number from which to get items.
  434.      * @param   integer  $limit    The number of items on a page.
  435.      *
  436.      * @return  array 
  437.      *
  438.      * @since   11.3
  439.      */
  440.     public function getComments($user, $repo, $issueId, $page = 0, $limit = 0)
  441.     {
  442.         // Build the request path.
  443.         $path = '/repos/' . $user . '/' . $repo . '/issues/' . (int) $issueId . '/comments';
  444.  
  445.         // Send the request.
  446.         $response = $this->client->get($this->fetchUrl($path, $page, $limit));
  447.  
  448.         // Validate the response code.
  449.         if ($response->code != 200)
  450.         {
  451.             // Decode the error response and throw an exception.
  452.             $error = json_decode($response->body);
  453.             throw new DomainException($error->message, $response->code);
  454.         }
  455.  
  456.         return json_decode($response->body);
  457.     }
  458.  
  459.     /**
  460.      * Method to get a specific label on a repo.
  461.      *
  462.      * @param   string  $user  The name of the owner of the GitHub repository.
  463.      * @param   string  $repo  The name of the GitHub repository.
  464.      * @param   string  $name  The label name to get.
  465.      *
  466.      * @return  object 
  467.      *
  468.      * @since   12.3
  469.      */
  470.     public function getLabel($user, $repo, $name)
  471.     {
  472.         // Build the request path.
  473.         $path = '/repos/' . $user . '/' . $repo . '/labels/' . $name;
  474.  
  475.         // Send the request.
  476.         $response = $this->client->get($this->fetchUrl($path));
  477.  
  478.         // Validate the response code.
  479.         if ($response->code != 200)
  480.         {
  481.             // Decode the error response and throw an exception.
  482.             $error = json_decode($response->body);
  483.             throw new DomainException($error->message, $response->code);
  484.         }
  485.  
  486.         return json_decode($response->body);
  487.     }
  488.  
  489.     /**
  490.      * Method to get the list of labels on a repo.
  491.      *
  492.      * @param   string  $user  The name of the owner of the GitHub repository.
  493.      * @param   string  $repo  The name of the GitHub repository.
  494.      *
  495.      * @return  array 
  496.      *
  497.      * @since   12.3
  498.      */
  499.     public function getLabels($user, $repo)
  500.     {
  501.         // Build the request path.
  502.         $path = '/repos/' . $user . '/' . $repo . '/labels';
  503.  
  504.         // Send the request.
  505.         $response = $this->client->get($this->fetchUrl($path));
  506.  
  507.         // Validate the response code.
  508.         if ($response->code != 200)
  509.         {
  510.             // Decode the error response and throw an exception.
  511.             $error = json_decode($response->body);
  512.             throw new DomainException($error->message, $response->code);
  513.         }
  514.  
  515.         return json_decode($response->body);
  516.     }
  517.  
  518.     /**
  519.      * Method to list an authenticated user's issues.
  520.      *
  521.      * @param   string   $filter     The filter type: assigned, created, mentioned, subscribed.
  522.      * @param   string   $state      The optional state to filter requests by. [open, closed]
  523.      * @param   string   $labels     The list of comma separated Label names. Example: bug,ui,@high.
  524.      * @param   string   $sort       The sort order: created, updated, comments, default: created.
  525.      * @param   string   $direction  The list direction: asc or desc, default: desc.
  526.      * @param   JDate    $since      The date/time since when issues should be returned.
  527.      * @param   integer  $page       The page number from which to get items.
  528.      * @param   integer  $limit      The number of items on a page.
  529.      *
  530.      * @return  array 
  531.      *
  532.      * @since   11.3
  533.      */
  534.     public function getList($filter = null, $state = null, $labels = null, $sort = null, $direction = null, JDate $since = null, $page = 0, $limit = 0)
  535.     {
  536.         // Build the request path.
  537.         $path = '/issues';
  538.  
  539.         // TODO Implement the filtering options.
  540.  
  541.         // Send the request.
  542.         $response = $this->client->get($this->fetchUrl($path, $page, $limit));
  543.  
  544.         // Validate the response code.
  545.         if ($response->code != 200)
  546.         {
  547.             // Decode the error response and throw an exception.
  548.             $error = json_decode($response->body);
  549.             throw new DomainException($error->message, $response->code);
  550.         }
  551.  
  552.         return json_decode($response->body);
  553.     }
  554.  
  555.     /**
  556.      * Method to list issues.
  557.      *
  558.      * @param   string   $user       The name of the owner of the GitHub repository.
  559.      * @param   string   $repo       The name of the GitHub repository.
  560.      * @param   string   $milestone  The milestone number, 'none', or *.
  561.      * @param   string   $state      The optional state to filter requests by. [open, closed]
  562.      * @param   string   $assignee   The assignee name, 'none', or *.
  563.      * @param   string   $mentioned  The GitHub user name.
  564.      * @param   string   $labels     The list of comma separated Label names. Example: bug,ui,@high.
  565.      * @param   string   $sort       The sort order: created, updated, comments, default: created.
  566.      * @param   string   $direction  The list direction: asc or desc, default: desc.
  567.      * @param   JDate    $since      The date/time since when issues should be returned.
  568.      * @param   integer  $page       The page number from which to get items.
  569.      * @param   integer  $limit      The number of items on a page.
  570.      *
  571.      * @return  array 
  572.      *
  573.      * @since   11.3
  574.      */
  575.     public function getListByRepository($user, $repo, $milestone = null, $state = null, $assignee = null, $mentioned = null, $labels = null,
  576.         $sort = null, $direction = null, JDate $since = null, $page = 0, $limit = 0)
  577.     {
  578.         // Build the request path.
  579.         $path = '/repos/' . $user . '/' . $repo . '/issues';
  580.  
  581.         $uri = new JUri($this->fetchUrl($path, $page, $limit));
  582.  
  583.         if ($milestone)
  584.         {
  585.             $uri->setVar('milestone', $milestone);
  586.         }
  587.  
  588.         if ($state)
  589.         {
  590.             $uri->setVar('state', $state);
  591.         }
  592.  
  593.         if ($assignee)
  594.         {
  595.             $uri->setVar('assignee', $assignee);
  596.         }
  597.  
  598.         if ($mentioned)
  599.         {
  600.             $uri->setVar('mentioned', $mentioned);
  601.         }
  602.  
  603.         if ($labels)
  604.         {
  605.             $uri->setVar('labels', $labels);
  606.         }
  607.  
  608.         if ($sort)
  609.         {
  610.             $uri->setVar('sort', $sort);
  611.         }
  612.  
  613.         if ($direction)
  614.         {
  615.             $uri->setVar('direction', $direction);
  616.         }
  617.  
  618.         if ($since)
  619.         {
  620.             $uri->setVar('since', $since->toISO8601());
  621.         }
  622.  
  623.         // Send the request.
  624.         $response = $this->client->get((string) $uri);
  625.  
  626.         // Validate the response code.
  627.         if ($response->code != 200)
  628.         {
  629.             // Decode the error response and throw an exception.
  630.             $error = json_decode($response->body);
  631.             throw new DomainException($error->message, $response->code);
  632.         }
  633.  
  634.         return json_decode($response->body);
  635.     }
  636. }

Documentation generated on Tue, 19 Nov 2013 15:05:52 +0100 by phpDocumentor 1.4.3