githubapi_class.inc

<?php
/**
 * @file
 * GitHub API wrapper class definition.
 */

use \Curl\Curl;

require_once './libraries/php-curl-class/src/Curl/CaseInsensitiveArray.php';
require_once './libraries/php-curl-class/src/Curl/Curl.php';

/**
 * GitHub API wrapper class.
 */
class GitHubAPI {

  /**
   * Curl class object.
   *
   * @var \Curl\Curl
   */
  protected $curl;

  /**
   * Token required to interact with GitHub API.
   *
   * @var string
   */
  protected $token;

  /**
   * URI of the directory where GET requests to API will be cached.
   *
   * Each token is given its own cache folder so that requests between different
   * tokens do not collide.
   *
   * @var string
   */
  protected $current_cache_folder;

  /**
   * Debug mode. If enabled, data will be printed via backdrop_set_message().
   *
   * @var bool
   */
  protected $debug = FALSE;

  /**
   * Timestamp if request has been served from cache. FALSE if not cached.
   *
   * @var boolean|int
   */
  protected $cache_expiration = FALSE;

  /**
   * Set to TRUE to disable cache and request directly to GitHub API.
   *
   * @var bool
   */
  protected $disable_cache = FALSE;

  /**
   * GitHub organization or user name that will be used to authorize requests.
   *
   * @var string
   */
  protected $owner_name;

  /**
   * GitHub Repository name on which requests will be made.
   *
   * @var string
   */
  protected $repo_name;

  /**
   * How long API requests will be cached in seconds.
   *
   * @var int
   */
  protected $age = 0;

  /**
   * How many results to list per page.
   */
  public $per_page = 100;

  /**
   * Constructor.
   */
  public function __construct() {
    $this->reInitCurl();
    $this->setDebug();
  }

  /**
   * Initializate $this->curl with Curl class and preset headers and user agent.
   */
  public function reInitCurl() {
    $this->curl = new Curl();
    $this->curl->setHeader('Content-Type', 'application/json');
    $this->curl->setUserAgent('Backdrop CMS GitHub API module');
    $this->curl->setHeader('Accept', '*/*');
    $this->curl->setHeader('Authorization', 'token ' . $this->getToken());
  }

  /**
   * Set owner name for requests.
   */
  public function setOwnerName($owner_name) {
    $this->owner_name = $owner_name;
  }

  /**
   * Set repository name for requests.
   */
  public function setRepoName($repo_name) {
    $this->repo_name = $repo_name;
  }

  /**
   * Set debug value. False by default.
   *
   * @param $debug boolean
   *   TRUE or FALSE
   */
  public function setDebug($debug = FALSE) {
    $this->debug = $debug;
  }

  /**
   * Set token for GitHub API and prepare caching folder.
   *
   * @param $token
   *   Token to access GitHub API.
   */
  public function setToken($token = '') {
    $this->token = $token;
    $this->prepareCacheFolder();
  }

  /**
   * Get the stored token.
   *
   * @return
   *   A string value. Stored token for GitHub API access.
   */
  public function getToken() {
    return $this->token;
  }

  /**
   * Determine if curl request has been falen with error.
   *
   * @return boolean
   *   TRUE or FALSE based on answer from GitHub API.
   */
  public function isError() {
    return $this->curl->curlError;
  }

  /**
   * Get Curl details after request.
   *
   * @return array
   *   An array of request information:
   *     - code: the last error number. @see curl_errno.
   *     - message: A clear text error message for the last cURL operation. @see curl_error.
   *     - request_headers: an array of request headers.
   *     - response_headers: an array of response headers.
   */
  public function testingGetHeaders() {
    return array(
      'code' => $this->curl->curlErrorCode,
      'message' => $this->curl->curlErrorMessage,
      'request_headers' => $this->curl->requestHeaders,
      'response_headers' => $this->curl->responseHeaders
    );
  }

  /**
   * Get Curl details if error happen.
   *
   * @return array|FALSE
   *   An array of errors if any has occurred. FALSE if there are no errors.
   *
   * @see GitHubAPI::testingGetHeaders().
   */
  public function getErrors() {
    if ($this->isError()) {
      return $this->testingGetHeaders();
    }
    return FALSE;
  }

  /**
   * Disable Get request caching to GitHub API.
   */
  public function disableCache() {
    $this->disable_cache = TRUE;
  }

  /**
   * Prepare directory to cache requests.
   *
   * @access protected
   */
  protected function prepareCacheFolder() {
    $root_folder = 'private://github_cache/';

    if (!$client_folder = $this->getToken()) {
      $client_folder = 'uid-0';
    }

    $this->current_cache_folder = $root_folder . $client_folder;
    file_prepare_directory($this->current_cache_folder, FILE_CREATE_DIRECTORY);

  }

  /**
   * Set debug value. False by default.
   *
   * @param $age int
   *   Time in seconds. We will cache result based on request time + $age.
   */
  public function setAge($age) {
    $this->age = $age;
  }

  /**
   * Get current caching age.
   *
   * @access private
   * @return int
   *   Time in seconds @see setAge.
   */
  private function getResponseAge() {
    global $user;
    if ($this->age) {
      return $this->age;
    }

    $age = 0;
    if ($age_header = $this->curl->responseHeaders['Cache-Control']) {
      $age_header_array = explode(',', $age_header);
      foreach ($age_header_array as $age_header_part) {
        $age_header_part = trim($age_header_part);
        if (strpos($age_header_part, 'max-age') === 0) {
          list(, $age) = explode('=', $age_header_part);
          break;
        }
      }
      if ($user->uid == 0) {
        // Default max age is 60. Let's cache for anonymous users for 5 min.
        $age = $age * 5;
      }
    }
    return $age;
  }

  /**
   * Save cache for future requests.
   *
   * @access private
   * @param string $command
   *   GitHub API url with already placed owner and repo if required.
   * @param array $params
   *   Values for request. We create a hash file based on params and command to
   *   make sure that cache is unique for request.
   *
   * @return bool
   *   TRUE if the request was cached and FALSE if not.
   */
  private function cacheRequest($command, $params) {
    if ($this->disable_cache) {
      return FALSE;
    }
    $serialize_object = serialize(array(
      'command' => $command,
      'params' => $params
    ));
    $file_name = hash('sha256', $serialize_object);

    $contents['response'] = $this->curl->response;
    $contents['age'] = $this->getResponseAge();
    $contents = json_encode($contents);

    $uri = $this->current_cache_folder . '/' . $file_name;
    file_unmanaged_save_data($contents, $uri, FILE_EXISTS_REPLACE);
    return TRUE;
  }

  /**
   * Return cache if exists.
   *
   * @access private
   * @param $command
   *   String value. GitHub API url with already placed owner and repo if required.
   * @param $params array
   *   Values for request. We create a hash file based on params and command to make sure that cache is unique for request.
   * @return
   *   FALSE if there is no cache. Object if cache exists and didnot expire yet.
   */
  private function getCacheRequest($command, $params) {
    if ($this->disable_cache) {
      return FALSE;
    }
    $serialize_object = serialize(array(
      'command' => $command,
      'params' => $params
    ));
    $file_name = hash('sha256', $serialize_object);

    $uri = $this->current_cache_folder . '/' . $file_name;

    $filename = backdrop_realpath($uri);

    if (file_exists($filename)) {
      $timestamp = filemtime($filename);
      if ($contents = @json_decode(file_get_contents($filename))) {
        if (($timestamp + $contents->age) > REQUEST_TIME) {

          $this->cache_expiration = $timestamp + $contents->age;

          if ($this->debug) {
            backdrop_set_message('Cache returned!');
          }
          return $contents->response;
        }
        else {
          if ($this->debug) {
            backdrop_set_message('No cache returned!' . ($timestamp + $contents->age) . '>' . REQUEST_TIME);
          }
        }
      }
    }
    return FALSE;
  }

  /**
   * Determine if request has been cached.
   *
   * @return
   *   FALSE if not and time when cache get expired in TIMESTAMP.
   */
  public function isCached() {
    return $this->cache_expiration;
  }

  /**
   * Determine if request has been cached.
   *
   * @access protected
   * @return stdClass|FALSE
   *   FALSE if error. Object with answer if request success.
   */
  protected function getResponse() {
    if ($this->debug) {
      backdrop_set_message('<pre>' . print_r($this->testingGetHeaders(), TRUE) . '</pre>');
    }
    if ($this->isError()) {
      return FALSE;
    }

    return $this->curl->response;
  }

  /**
   * Perform GET request to GitHub API and return answer.
   *
   * @access public
   * @param string $command
   *   String value. GitHub API url with tokens like :owner, :repo and ect.
   * @param array $params
   *   Values for request and tokens for request url. LIke :owner, :repo, :id and etc.
   * @param array $headers
   *   Additional headers to be sent in the request.
   * @return stdClass|FALSE
   *   FALSE if request failed. Object if success.
   */
  public function getRequest($command, $params = array(), $headers = array()) {
    $this->prepareCommand($command, $params);

    // Add default 1000 per page.
    $params['per_page'] = $this->per_page;

    if ($response = $this->getCacheRequest($command, $params)) {
      return $response;
    }

    // Always start with a fresh cURL object before each request.
    $this->reInitCurl();
    foreach ($headers as $header_key => $header_value) {
      $this->curl->setHeader($header_key, $header_value);
    }

    $this->curl->get(GITHUB_API_URI . '/' . $command, $params);
    $response = $this->getResponse();
    $this->cacheRequest($command, $params);
    return $response;
  }

  /**
   * Perform PUT request to GitHub API and return answer.
   *
   * @access public
   * @param $command
   *   String value. GitHub API url with tokens like :owner, :repo and etc.
   * @param $params array
   *   Values for request and tokens for request url. LIke :owner, :repo, :id and etc.
   * @return stdClass|FALSE
   *   FALSE if request failed. Object if success.
   */
  public function putRequest($command, $params = array()) {
    // @todo: Add committer method and set this value.
    //$params['committer'] = $this->getCommittrer();
    $this->prepareCommand($command, $params);

    $this->reInitCurl();
    $this->curl->put(GITHUB_API_URI . '/' . $command, $params);
    $response = $this->getResponse();
    return $response;
  }

  /**
   * Perform POST request to GitHub API and return answer.
   *
   * @access public
   * @param $command
   *   String value. GitHub API url with tokens like :owner, :repo and ect.
   * @param $params array
   *   Values for request and tokens for request url. LIke :owner, :repo, :id and etc.
   * @return
   *   FALSE if request failed. Object if success.
   */
  public function postRequest($command, $params = array()) {

    $this->prepareCommand($command, $params);
    $this->reInitCurl();
    $this->curl->post(GITHUB_API_URI . '/' . $command, $params);
    $response = $this->getResponse();
    return $response;
  }

  /**
   * Perform DELETE request to GitHub API and return answer.
   *
   * @access public
   * @param $command
   *   String value. GitHub API url with tokens like :owner, :repo and ect.
   * @param $params array
   *   Values for request and tokens for request url. LIke :owner, :repo, :id and etc.
   * @return
   *   FALSE if request failed. Object if success.
   */
  public function deleteRequest($command, $params = array()) {
    $this->prepareCommand($command, $params);
    $this->reInitCurl();
    $this->curl->delete(GITHUB_API_URI . '/' . $command, $params);
    $response = $this->getResponse();

    return $response;
  }


  /**
   * Replace tokens with values in request url.
   *
   * @access private
   * @param $command
   *   String value. GitHub API url with tokens like :owner, :repo and etc.
   * @param $params array
   *   Values for request and tokens for request url. LIke :owner, :repo, :id and etc.
   */
  private function prepareCommand(&$command, &$params) {
    foreach ($params as $key => $val) {
      if (strpos($key, ':') === 0) {
        $command = str_replace($key, $val, $command);
        unset($params[$key]);
      }
    }
  }

  /**
   * Get user organisations.
   * https://developer.github.com/v3/orgs/#list-your-organizations
   *
   * @return
   *   Return user organisations or FALSE if there is no user or no access.
   */
  public function getOrgs() {
    return $this->getRequest('user/orgs');
  }

  /**
   * Get user information.
   * https://developer.github.com/v3/users/#get-a-single-user
   *
   * @param $username
   *   String value. Username.
   * @return
   *   Return user information or FALSE if there is no user or no access.
   */
  public function getUser($username) {
    return $this->getRequest('users/:username', array(':username' => $username));
  }

  /**
   * Get user repositories.
   * https://developer.github.com/v3/repos/#list-your-repositories
   *
   * @param $username
   *   String value. Username.
   * @return
   *   Return user repositories or FALSE if there is no user or no access.
   */
  public function getUserRepos($username) {
    return $this->getRequest('users/:username/repos', array(':username' => $username));
  }

  /**
   * Get organisation information.
   * https://developer.github.com/v3/orgs/#get-an-organization
   *
   * @param $orgname
   *   String value. Organisation name.
   * @return
   *   Return organisation information or FALSE if there is no organisation or no access.
   */
  public function getOrg($orgname) {
    return $this->getRequest('orgs/:org', array(':org' => $orgname));
  }

  /**
   * Get organisation repositories.
   * https://developer.github.com/v3/repos/#list-organization-repositories
   *
   * @param $orgname
   *   String value. Organisation name.
   * @return
   *   Return organisation repositories or FALSE if there is no organisation or no access.
   */
  public function getOrgsRepos($orgname) {
    return $this->getRequest('orgs/:org/repos', array(':org' => $orgname));
  }

  /**
   * Get repository information.
   * https://developer.github.com/v3/repos/#get
   *
   * @return
   *   Return repository information or FALSE if there is no repository or no access.
   *
   * @see SetRepoName
   * @see SetOwnerName
   */
  public function getRepo() {
    return $this->getRequest(
      'repos/:owner/:repo', array(
        ':owner' => $this->owner_name,
        ':repo' => $this->repo_name,
      )
    );
  }

  /**
   * Create hook for repository.
   * https://developer.github.com/v3/repos/hooks/#create-a-hook
   *
   * @param $settings array
   *   An array of settings for hook
   *     - name: Must be passed as "web".
   *     - config: Key/Value:
   *        - url: The URL to which the payloads will be delivered.
   *        - content_type: The media type used to serialize the payloads. Supported values include json and form. The default is form.
   *        - secret: If provided, payloads will be delivered with an X-Hub-Signature header.
   *        - insecure_ssl: Determines whether the SSL certificate of the host for url will be verified when delivering payloads.
   *     - events: Determines what events the hook is triggered for. Default: ["push"].
   *     - active: Determines whether the hook is actually triggered on pushes.
   * @return
   *   Return hook information or  FALSE if there is no access.
   *
   * @see SetRepoName
   * @see SetOwnerName
   */
  public function createHook($settings) {
    $settings[':owner'] = $this->owner_name;
    $settings[':repo'] = $this->repo_name;
    return $this->postRequest('repos/:owner/:repo/hooks', $settings);
  }

  /**
   * Delete hook for repository.
   * https://developer.github.com/v3/repos/hooks/#delete-a-hook
   *
   * @param $id integer
   *   Hook id to delete
   * @return
   *   Return empty value if success or FALSE if error.
   *
   * @see SetRepoName
   * @see SetOwnerName
   */
  public function deleteHook($id) {
    return $this->deleteRequest(
      'repos/:owner/:repo/hooks/:id', array(
        ':owner' => $this->owner_name,
        ':repo' => $this->repo_name,
        ':id' => $id,
      )
    );
  }

  /**
   * Create hook for organisation.
   * https://developer.github.com/v3/orgs/hooks/#create-a-hook
   *
   * @param $settings array
   *   An array of settings for hook
   *     - name: Must be passed as "web".
   *     - config: Key/Value:
   *        - url: The URL to which the payloads will be delivered.
   *        - content_type: The media type used to serialize the payloads. Supported values include json and form. The default is form.
   *        - secret: If provided, payloads will be delivered with an X-Hub-Signature header.
   *        - insecure_ssl: Determines whether the SSL certificate of the host for url will be verified when delivering payloads.
   *     - events: Determines what events the hook is triggered for. Default: ["push"].
   *     - active: Determines whether the hook is actually triggered on pushes.
   * @return
   *   Return hook information or FALSE if there is no access.
   *
   * @see SetOwnerName
   */
  public function createOrgHook($settings) {
    $settings[':org'] = $this->owner_name;
    return $this->postRequest('orgs/:org/hooks', $settings);
  }

  /**
   * Delete hook for organisation.
   * https://developer.github.com/v3/orgs/hooks/#delete-a-hook
   *
   * @param $id integer
   *   Hook id to delete
   * @return
   *   Return empty value if success or FALSE if error.
   *
   * @see SetOwnerName
   */
  public function deleteOrgHook($id) {
    return $this->deleteRequest(
      'orgs/:org/hooks/:id', array(
        ':org' => $this->owner_name,
        ':id' => $id,
      )
    );
  }

  /**
   * Get a single commit.
   * https://developer.github.com/v3/repos/commits/#get-a-single-commit
   *
   * @param $sha
   *   hash for commit
   * @return
   *   Return commit information or FALSE if there is no access.
   *
   * @see SetRepoName
   * @see SetOwnerName
   */
  public function getCommit($sha) {
    return $this->getRequest(
      'repos/:owner/:repo/commits/:sha', array(
        ':owner' => $this->owner_name,
        ':repo' => $this->repo_name,
        ':sha' => $sha,
      )
    );
  }

  /**
   * Create a commit comment.
   * https://developer.github.com/v3/repos/comments/#create-a-commit-comment
   *
   * @param $settings array
   *   An array of settings for new comment
   *     - body: The contents of the comment.
   *     - path: Relative path of the file to comment on.
   *     - position: Line index in the diff to comment on.
   *
   * @return
   *   Return comment information or FALSE if there is no access.
   *
   * @see SetRepoName
   * @see SetOwnerName
   */
  public function createComment($settings) {
    $settings[':owner'] = $this->owner_name;
    $settings[':repo'] = $this->repo_name;
    return $this->postRequest('repos/:owner/:repo/commits/:sha/comments', $settings);
  }

  /**
   * Create an issue comment.
   * https://developer.github.com/v3/issues/comments/#create-a-comment
   *
   * @param $settings array
   *   An array of settings for new comment
   *     - body: The contents of the comment.
   *     - :number : Issue number.
   *
   * @return
   *   Return comment information or FALSE if there is no access.
   *
   * @see SetRepoName
   * @see SetOwnerName
   */
  public function createIssueComment($settings) {
    $settings[':owner'] = $this->owner_name;
    $settings[':repo'] = $this->repo_name;
    return $this->postRequest('repos/:owner/:repo/issues/:number/comments', $settings);
  }

  /**
   * Get README.md file content from repository as HTML.
   *
   * https://developer.github.com/v3/repos/contents/#get-the-readme
   *
   * @return
   *   Return HTML content of the file already decoded.
   *
   * @see SetRepoName
   * @see SetOwnerName
   */
  public function getReadme() {
    $readme = $this->getRequest('repos/:owner/:repo/readme', array(
      ':owner' => $this->owner_name,
      ':repo' => $this->repo_name,
    ), array(
      'Accept' => 'application/vnd.github.v3.html',
    ));
    if (is_string($readme)) {
      return $readme;
    }
    return FALSE;
  }

  /**
   * Get Archive file content by :ref from repository.
   * https://developer.github.com/v3/repos/contents/#get-archive-link
   *
   * @return
   *   Return content of the archive.
   *
   * @see SetRepoName
   * @see SetOwnerName
   */
  public function getArchive($settings) {
    $settings[':owner'] = $this->owner_name;
    $settings[':repo'] = $this->repo_name;

    if (!isset($settings[':archive_format']) || in_array($settings[':archive_format'], array(
        'tarball',
        'zipball'
      ))
    ) {
      $settings[':archive_format'] = 'zipball';
    }

    if (!isset($settings[':ref'])) {
      $url = 'repos/:owner/:repo/:archive_format';
    }
    else {
      $url = 'repos/:owner/:repo/:archive_format/:ref';
    }

    // First request returns a 302 with link to download;
    $this->getRequest($url, $settings);

    if (isset($this->curl->responseHeaders['Location'])) {
      $url = $this->curl->responseHeaders['Location'];
      $this->curl->get($url);
      $content = $this->curl->response;
      return $content;
    }

    return FALSE;
  }

  /**
   * Get Releases list for repo.
   * https://developer.github.com/v3/repos/releases/#list-releases-for-a-repository
   *
   * @return array
   *   List of releases.
   *
   * @see SetRepoName
   * @see SetOwnerName
   */
  public function getReleases() {
    $settings[':owner'] = $this->owner_name;
    $settings[':repo'] = $this->repo_name;

    return $this->getRequest('repos/:owner/:repo/releases', $settings);
  }

  /**
   * Get Release by Tag name.
   * https://developer.github.com/v3/repos/releases/#get-a-release-by-tag-name
   *
   * @param $settings array
   *   An array of settings for new comment
   *     - :tag: Tag name for release.
   *
   * @return stdClass|FALSE
   *   The newly added asset information response from GitHub. Or FALSE if the
   *   asset upload failed.
   *
   * @see SetRepoName
   * @see SetOwnerName
   */
  public function getRelease($settings) {
    $settings[':owner'] = $this->owner_name;
    $settings[':repo'] = $this->repo_name;

    return $this->getRequest('repos/:owner/:repo/releases/tags/:tag', $settings);
  }

  /**
   * Add Asset to release.
   * https://developer.github.com/v3/repos/releases/#upload-a-release-asset
   *
   * @param $settings array
   *   An array of settings for new comment
   *     - filename: THe file name, include extension.
   *     - label: Label to display instead of file.
   *     - content: The contents of the comment.
   *     - :tag: Tag name for release.
   *
   * @return stdClass|FALSE
   *   The newly added asset information response from GitHub. Or FALSE if the
   *   asset upload failed.
   *
   * @see SetRepoName
   * @see SetOwnerName
   */
  public function addAsset($settings) {
    $get_release_settings = array(
      ':tag' => $settings[':tag'],
    );

    $release = $this->getRelease($get_release_settings);

    $upload_url = $release->upload_url;
    $upload_url = preg_replace('/{.*}/', '', $upload_url);

    $query = array();
    $query['name'] = $settings['filename'];
    if (isset($settings['label'])) {
      $query['label'] = $settings['label'];
    }

    $upload_url = $upload_url . "?" . backdrop_http_build_query($query);

    $this->reInitCurl();
    $this->curl->setHeader('Content-Type', $this->getMimeType($settings['filename']));
    $response = $this->curl->post($upload_url, $settings['content']);

    if ($this->curl->error) {
      return FALSE;
    }
    return $response;
  }

  /**
   * Return content type based on file name.
   * @param $filename string
   * @return string
   *   Content type.
   */
  private function getMimeType($filename) {
    $mime_types = array(

      'txt' => 'text/plain',
      'htm' => 'text/html',
      'html' => 'text/html',
      'php' => 'text/html',
      'css' => 'text/css',
      'js' => 'application/javascript',
      'json' => 'application/json',
      'xml' => 'application/xml',
      'swf' => 'application/x-shockwave-flash',
      'flv' => 'video/x-flv',

      // images
      'png' => 'image/png',
      'jpe' => 'image/jpeg',
      'jpeg' => 'image/jpeg',
      'jpg' => 'image/jpeg',
      'gif' => 'image/gif',
      'bmp' => 'image/bmp',
      'ico' => 'image/vnd.microsoft.icon',
      'tiff' => 'image/tiff',
      'tif' => 'image/tiff',
      'svg' => 'image/svg+xml',
      'svgz' => 'image/svg+xml',

      // archives
      'zip' => 'application/zip',
      'rar' => 'application/x-rar-compressed',
      'exe' => 'application/x-msdownload',
      'msi' => 'application/x-msdownload',
      'cab' => 'application/vnd.ms-cab-compressed',

      // audio/video
      'mp3' => 'audio/mpeg',
      'qt' => 'video/quicktime',
      'mov' => 'video/quicktime',

      // adobe
      'pdf' => 'application/pdf',
      'psd' => 'image/vnd.adobe.photoshop',
      'ai' => 'application/postscript',
      'eps' => 'application/postscript',
      'ps' => 'application/postscript',

      // ms office
      'doc' => 'application/msword',
      'rtf' => 'application/rtf',
      'xls' => 'application/vnd.ms-excel',
      'ppt' => 'application/vnd.ms-powerpoint',

      // open office
      'odt' => 'application/vnd.oasis.opendocument.text',
      'ods' => 'application/vnd.oasis.opendocument.spreadsheet',
    );

    $pathinfo = pathinfo($filename);
    $ext = $pathinfo['extension'];
    backdrop_set_message(print_r($pathinfo, TRUE));

    if (isset($mime_types[$ext])) {
      return $mime_types[$ext];
    }
    return 'application/octet-stream';
  }

}