Skip to content

Commit

Permalink
Added phpDoc for ApiRequestor and others, especially regarding thrown…
Browse files Browse the repository at this point in the history 
… errors (#472)
  • Loading branch information
@rtm-ctrlz @brandur-stripe
rtm-ctrlz authored and brandur-stripe committed Jun 13, 2018
1 parent 09a282e commit 0a32b7c
Show file tree
Hide file tree
Showing 2 changed files with 136 additions and 5 deletions.
134 changes: 131 additions & 3 deletions lib/ApiRequestor.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,27 @@
*/
class ApiRequestor
{
/**
* @var string|null
*/
private $_apiKey;

/**
* @var string
*/
private $_apiBase;

/**
* @var HttpClient\ClientInterface
*/
private static $_httpClient;

/**
* ApiRequestor constructor.
*
* @param string|null $apiKey
* @param string|null $apiBase
*/
public function __construct($apiKey = null, $apiBase = null)
{
$this->_apiKey = $apiKey;
Expand All @@ -24,6 +39,13 @@ public function __construct($apiKey = null, $apiBase = null)
$this->_apiBase = $apiBase;
}

/**
* @static
*
* @param ApiResource|bool|array|mixed $d
*
* @return ApiResource|array|string|mixed
*/
private static function _encodeObjects($d)
{
if ($d instanceof ApiResource) {
Expand All @@ -44,13 +66,27 @@ private static function _encodeObjects($d)
}

/**
* @param string $method
* @param string $url
* @param string $method
* @param string $url
* @param array|null $params
* @param array|null $headers
*
* @return array An array whose first element is an API response and second
* element is the API key used to make the request.
* @throws Error\Api
* @throws Error\Authentication
* @throws Error\Card
* @throws Error\InvalidRequest
* @throws Error\OAuth\InvalidClient
* @throws Error\OAuth\InvalidGrant
* @throws Error\OAuth\InvalidRequest
* @throws Error\OAuth\InvalidScope
* @throws Error\OAuth\UnsupportedGrantType
* @throws Error\OAuth\UnsupportedResponseType
* @throws Error\Permission
* @throws Error\RateLimit
* @throws Error\Idempotency
* @throws Error\ApiConnection
*/
public function request($method, $url, $params = null, $headers = null)
{
Expand All @@ -70,13 +106,22 @@ public function request($method, $url, $params = null, $headers = null)
* @param array $resp
*
* @throws Error\InvalidRequest if the error is caused by the user.
* @throws Error\Idempotency if the error is caused by an idempotency key.
* @throws Error\Authentication if the error is caused by a lack of
* permissions.
* @throws Error\Permission if the error is caused by insufficient
* permissions.
* @throws Error\Card if the error is the error code is 402 (payment
* required)
* @throws Error\InvalidRequest if the error is caused by the user.
* @throws Error\Idempotency if the error is caused by an idempotency key.
* @throws Error\OAuth\InvalidClient
* @throws Error\OAuth\InvalidGrant
* @throws Error\OAuth\InvalidRequest
* @throws Error\OAuth\InvalidScope
* @throws Error\OAuth\UnsupportedGrantType
* @throws Error\OAuth\UnsupportedResponseType
* @throws Error\Permission if the error is caused by insufficient
* permissions.
* @throws Error\RateLimit if the error is caused by too many requests
* hitting the API.
* @throws Error\Api otherwise.
Expand All @@ -102,6 +147,17 @@ public function handleErrorResponse($rbody, $rcode, $rheaders, $resp)
throw $error;
}

/**
* @static
*
* @param string $rbody
* @param int $rcode
* @param array $rheaders
* @param array $resp
* @param array $errorData
*
* @return Error\RateLimit|Error\Idempotency|Error\InvalidRequest|Error\Authentication|Error\Card|Error\Permission|Error\Api
*/
private static function _specificAPIError($rbody, $rcode, $rheaders, $resp, $errorData)
{
$msg = isset($errorData['message']) ? $errorData['message'] : null;
Expand Down Expand Up @@ -136,6 +192,17 @@ private static function _specificAPIError($rbody, $rcode, $rheaders, $resp, $err
}
}

/**
* @static
*
* @param string|bool $rbody
* @param int $rcode
* @param array $rheaders
* @param array $resp
* @param string $errorCode
*
* @return null|Error\OAuth\InvalidClient|Error\OAuth\InvalidGrant|Error\OAuth\InvalidRequest|Error\OAuth\InvalidScope|Error\OAuth\UnsupportedGrantType|Error\OAuth\UnsupportedResponseType
*/
private static function _specificOAuthError($rbody, $rcode, $rheaders, $resp, $errorCode)
{
$description = isset($resp['error_description']) ? $resp['error_description'] : $errorCode;
Expand All @@ -158,6 +225,13 @@ private static function _specificOAuthError($rbody, $rcode, $rheaders, $resp, $e
return null;
}

/**
* @static
*
* @param null|array $appInfo
*
* @return null|string
*/
private static function _formatAppInfo($appInfo)
{
if ($appInfo !== null) {
Expand All @@ -174,6 +248,14 @@ private static function _formatAppInfo($appInfo)
}
}

/**
* @static
*
* @param string $apiKey
* @param null $clientInfo
*
* @return array
*/
private static function _defaultHeaders($apiKey, $clientInfo = null)
{
$uaString = 'Stripe/v1 PhpBindings/' . Stripe::VERSION;
Expand Down Expand Up @@ -205,6 +287,17 @@ private static function _defaultHeaders($apiKey, $clientInfo = null)
return $defaultHeaders;
}

/**
* @param string $method
* @param string $url
* @param array $params
* @param array $headers
*
* @return array
* @throws Error\Api
* @throws Error\ApiConnection
* @throws Error\Authentication
*/
private function _requestRaw($method, $url, $params, $headers)
{
$myApiKey = $this->_apiKey;
Expand Down Expand Up @@ -273,6 +366,13 @@ private function _requestRaw($method, $url, $params, $headers)
return [$rbody, $rcode, $rheaders, $myApiKey];
}

/**
* @param resource $resource
* @param bool $hasCurlFile
*
* @return \CURLFile|string
* @throws Error\Api
*/
private function _processResourceParam($resource, $hasCurlFile)
{
if (get_resource_type($resource) !== 'stream') {
Expand All @@ -296,6 +396,26 @@ private function _processResourceParam($resource, $hasCurlFile)
}
}

/**
* @param string $rbody
* @param int $rcode
* @param array $rheaders
*
* @return mixed
* @throws Error\Api
* @throws Error\Authentication
* @throws Error\Card
* @throws Error\InvalidRequest
* @throws Error\OAuth\InvalidClient
* @throws Error\OAuth\InvalidGrant
* @throws Error\OAuth\InvalidRequest
* @throws Error\OAuth\InvalidScope
* @throws Error\OAuth\UnsupportedGrantType
* @throws Error\OAuth\UnsupportedResponseType
* @throws Error\Permission
* @throws Error\RateLimit
* @throws Error\Idempotency
*/
private function _interpretResponse($rbody, $rcode, $rheaders)
{
$resp = json_decode($rbody, true);
Expand All @@ -312,11 +432,19 @@ private function _interpretResponse($rbody, $rcode, $rheaders)
return $resp;
}

/**
* @static
*
* @param HttpClient\ClientInterface $client
*/
public static function setHttpClient($client)
{
self::$_httpClient = $client;
}

/**
* @return HttpClient\ClientInterface
*/
private function httpClient()
{
if (!self::$_httpClient) {
Expand Down
7 changes: 5 additions & 2 deletions lib/HttpClient/ClientInterface.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,11 @@ interface ClientInterface
* @param array $params KV pairs for parameters. Can be nested for arrays and hashes
* @param boolean $hasFile Whether or not $params references a file (via an @ prefix or
* CurlFile)
* @throws \Stripe\Error\Api & \Stripe\Error\ApiConnection
* @return [$rawBody, $httpStatusCode, $httpHeader]
*
* @throws \Stripe\Error\Api
* @throws \Stripe\Error\ApiConnection
* @return array An array whose first element is raw request body, second
* element is HTTP status code and third array of HTTP headers.
*/
public function request($method, $absUrl, $headers, $params, $hasFile);
}

0 comments on commit 0a32b7c

Please sign in to comment.