gogs-php-api-client/src/lib/curl.php

<?php namespace Lib;

/** 
 * Defines an unexpected response.
 *
 * @author Joachim M. Giaever (joachim[]giaever.org)
 * @package curl
 * @version 0.1
 */
class HTTPUnexpectedResponse extends \Exception {
    /**
     * Includes valid codes, as a valid code can also be unexpeted.
     *
     * @var array $ecode HTTP status codes
     * @static
     */
    static $ecode = array(
        0 => "Unknown error",
        100 => 'Continue',
        101 => 'Switching Protocols',
        102 => 'Processing', // WebDAV; RFC 2518
        200 => 'OK',
        201 => 'Created',
        202 => 'Accepted',
        203 => 'Non-Authoritative Information', // since HTTP/1.1
        204 => 'No Content',
        205 => 'Reset Content',
        206 => 'Partial Content',
        207 => 'Multi-Status', // WebDAV; RFC 4918
        208 => 'Already Reported', // WebDAV; RFC 5842
        226 => 'IM Used', // RFC 3229
        300 => 'Multiple Choices',
        301 => 'Moved Permanently',
        302 => 'Found',
        303 => 'See Other', // since HTTP/1.1
        304 => 'Not Modified',
        305 => 'Use Proxy', // since HTTP/1.1
        306 => 'Switch Proxy',
        307 => 'Temporary Redirect', // since HTTP/1.1
        308 => 'Permanent Redirect', // approved as experimental RFC
        400 => 'Bad Request',
        401 => 'Unauthorized',
        402 => 'Payment Required',
        403 => 'Forbidden',
        404 => 'Not Found',
        405 => 'Method Not Allowed',
        406 => 'Not Acceptable',
        407 => 'Proxy Authentication Required',
        408 => 'Request Timeout',
        409 => 'Conflict',
        410 => 'Gone',
        411 => 'Length Required',
        412 => 'Precondition Failed',
        413 => 'Request Entity Too Large',
        414 => 'Request-URI Too Long',
        415 => 'Unsupported Media Type',
        416 => 'Requested Range Not Satisfiable',
        417 => 'Expectation Failed',
        418 => 'I\'m a teapot', // RFC 2324
        419 => 'Authentication Timeout', // not in RFC 2616
        420 => 'Enhance Your Calm', // Twitter
        420 => 'Method Failure', // Spring Framework
        422 => 'Unprocessable Entity', // WebDAV; RFC 4918
        423 => 'Locked', // WebDAV; RFC 4918
        424 => 'Failed Dependency', // WebDAV; RFC 4918
        424 => 'Method Failure', // WebDAV)
        425 => 'Unordered Collection', // Internet draft
        426 => 'Upgrade Required', // RFC 2817
        428 => 'Precondition Required', // RFC 6585
        429 => 'Too Many Requests', // RFC 6585
        431 => 'Request Header Fields Too Large', // RFC 6585
        444 => 'No Response', // Nginx
        449 => 'Retry With', // Microsoft
        450 => 'Blocked by Windows Parental Controls', // Microsoft
        451 => 'Redirect', // Microsoft
        451 => 'Unavailable For Legal Reasons', // Internet draft
        494 => 'Request Header Too Large', // Nginx
        495 => 'Cert Error', // Nginx
        496 => 'No Cert', // Nginx
        497 => 'HTTP to HTTPS', // Nginx
        499 => 'Client Closed Request', // Nginx
        500 => 'Internal Server Error',
        501 => 'Not Implemented',
        502 => 'Bad Gateway',
        503 => 'Service Unavailable',
        504 => 'Gateway Timeout',
        505 => 'HTTP Version Not Supported',
        506 => 'Variant Also Negotiates', // RFC 2295
        507 => 'Insufficient Storage', // WebDAV; RFC 4918
        508 => 'Loop Detected', // WebDAV; RFC 5842
        509 => 'Bandwidth Limit Exceeded', // Apache bw/limited extension
        510 => 'Not Extended', // RFC 2774
        511 => 'Network Authentication Required', // RFC 6585
        598 => 'Network read timeout error', // Unknown
        599 => 'Network connect timeout error', // Unknown
    );

    /**
     * The response from server (body)
     * @access private
     */
    private $response;

    /**
     * Sets the exceptions.
     *
     * @string $message - the response from the server.
     * @string $code - the HTTP status code.
     * @exception $prev - Previous exceptions
     **/
    public function __construct(string $message, int $code = 0, Exception $previous = null) {
        $this->response = $message;
        parent::__construct(HTTPUnexpectedResponse::$ecode[$code], $code, $previous);
    }

    /** 
     * Visual representation of the exception.
     *
     * @return string
     */
    public function __toString() {
        return __CLASS__ . ": [{$this->code} | {$this->message}]: {$this->response}\n";
    }

    /** 
     * Get the actual response from the body or the request.
     *
     * @return string
     */
    public function getResponse() {
        return $this->response;
    }
}

/** 
 * When the request fails because of an unauthorized token,
 * this is thrown instead.
 *
 * @author Joachim M. Giaever (joachim[]giaever.org)
 * @package curl
 * @version 0.1
 */
class NotAuthorizedException extends HTTPUnexpectedResponse {

    /**
     * Sets the exceptions.
     *
     * @string $message - the response from the server.
     * @string $code - the HTTP status code, @default 401
     * @exception $prev - Previous exceptions
     **/
    public function __construct($message, $code = 401, Exception $previous = null) {
        parent::__construct($message, $code, $previous);
    }
}

/** 
 * A trait used for every class referencing the api-url and token.
 *
 * @author Joachim M. Giaever (joachim[]giaever.org)
 * @package curl
 * @version 0.1
 */
trait Curl {
    protected $url;
    protected $token;

    // TODO: Change this to something!
    protected $user_agent = "Gogs PHP Api Client/0.1 (compatible; LINUX)";
    protected $timeout = 30;
    protected $max_redirects = 4;

    /** 
     * array_2_params takes an array and converts it into a
     * query string (e.g param=val&param2=val2).
     *
     * @param array $params parameters to pass
     * @return string
     */
    private function array_2_params(array $params) {
        return join("&", array_map(function($k, $v) {
            return sprintf("%s=%s", $k, rawurlencode(is_bool($v) ? ($v ? "true" : "false") : $v ));
        }, array_keys($params), $params));
    }

    /** 
     * array_2_json takes an array and converts it into a
     * json-string (e.g {'name': 'This'}) which is typically
     * used in a request body.
     * 
     * @param array $params paramters to pass
     * @return string
     */
    private function array_2_json(array $params) {
        return count($params) == 0 ? null : json_encode($params);
    }

    /** 
     * Initializes a curl request of different kinds, depending
     * on the specified method. This can be
     *
     * DELETE, PATCH, POST or GET. An unidentified value will
     * become a GET-request.
     * 
     * @param string $method either DELETE, PATCH, POST, GET
     * @param string &$req variable to store request body in
     * @param string $scope scope within the API (e.g /user/repos)
     * @param array $params parameters to pass
     * @param bool $ret return transfer
     * @return int the status code
     */
    protected function method(string $method, string &$req, string $scope, array $params, bool $ret) {
        $c = curl_init();

        if (!$c) {
            return false;
        }

        $headers = array(
            sprintf("Authorization: token %s", $this->token),
        );

        $url = sprintf("%s%s", $this->url, $scope);

        echo sprintf("%s: %s, params: %s\n", $method, $url, $this->array_2_json($params));

        if (in_array($method, array("DELETE", "PATCH", "POST"))) {
            $json = $this->array_2_json($params);
            curl_setopt($c, CURLOPT_CUSTOMREQUEST, $method);
            curl_setopt($c, CURLOPT_POSTFIELDS, $json);
            array_unshift($headers, "Content-Type: application/json");
            array_push($headers, "Content-Length: " . strlen($json));
        } else {
            $url .= "?" . $this->array_2_params($params);
        }

        curl_setopt($c, CURLOPT_USERAGENT, $this->user_agent);
        curl_setopt($c, CURLOPT_URL, $url);
        curl_setopt($c, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($c, CURLOPT_RETURNTRANSFER, $ret);
        curl_setopt($c, CURLOPT_TIMEOUT, $this->timeout);
        curl_setopt($c, CURLOPT_MAXREDIRS, $this->max_redirects);
        curl_setopt($c, CURLOPT_FOLLOWLOCATION, true);

        $req = curl_exec($c);

        $status_code = curl_getinfo($c, CURLINFO_HTTP_CODE);

        curl_close($c);

        return $status_code;
    }

    /** 
     * Checks if the user is authorized for the scope. Shouldn't
     * be used frequently. One test for one scope should be enough,
     * but if you know for sure thats you're programming with the
     * use of an authorized user you should leave this and just
     * handle the NotAuthorizedExeption whenever thrown.
     *
     * @param $scope the scope, a relative uri.
     * @throws Not AuthorizedException if server responde with a 401
     * @return bool
     */
    protected function authorized(string $scope = "") {
        $ret = "";
        if ($this->method("GET", $ret, $scope, array(), false) == 401) {
            throw new NotAuthorizedException("Not authorized", 401);
        }
        return true;
    }

    /**
     * Post method.
     *
     * @param string $scope the scope, a relative uri.
     * @param array $params the parameters to post.
     * @throws NotAuthorizedException on 401, 403
     * @throws HTTPUnexpectedResponse when not 200,201,401,403
     * @return string the request content.
     */
    private function post(string $scope = "", array $params = array()) {
        $req = "";

        $code = $this->method("POST", $req, $scope, $params, true);

        switch ($code) {
        case 200:
        case 201:
            return $req;
        case 401:
        case 403:
            throw new NotAuthorizedException($req, $code);
        default:
            throw new HTTPUnexpectedResponse($req, $code);
        }
    }

    /**
     * Delete method.
     *
     * @param string $scope the scope, a relative uri.
     * @throws NotAuthorizedException on 401, 403
     * @throws HTTPUnexpectedResponse when not 200,204,401,403
     * @return string the request content.
     */
    private function delete(string $scope = "") {
        $req = "";

        $code = $this->method("DELETE", $req, $scope, array(), true);

        switch ($code) {
        case 200:
        case 204:
            return $req;
        case 401:
        case 403:
            throw new NotAuthorizedException($req, $code);
        default:
            throw new HTTPUnexpectedResponse($req, $code);
        }
    }

    /**
     * GET method.
     *
     * @param string $scope the scope, a relative uri.
     * @param array $params the parameters to post.
     * @throws NotAuthorizedException on 401, 403
     * @throws HTTPUnexpectedResponse when not 200,401,403
     * @return string the request content.
     */
    private function get($scope = "", $params = array()) {
        $req = "";

        $code = $this->method("GET", $req, $scope, $params, true);

        switch ($code) {
        case 200:
            return $req;
        case 401:
        case 403:
            throw new NotAuthorizedException($req, $code);
        default:
            throw new HTTPUnexpectedResponse($req, $code);

        }
    }

}