Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added phpDoc for ApiRequestor, especially regarding thrown errors #472

Merged
merged 5 commits into from
Jun 13, 2018
Merged

Added phpDoc for ApiRequestor, especially regarding thrown errors #472

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6e741a6
[phpdoc] added phpDoc for ApiRequestor, especially regarding thrown e…
rtm-ctrlz May 14, 2018
0f8d43c
[phpdoc] ApiRequestor, small fixes
rtm-ctrlz May 28, 2018
04c1eab
[phpdoc] ApiRequestor - reverted load Error\Idempotency usage
rtm-ctrlz May 30, 2018
0578fe5
[phpdoc] ApiRequestor, rbody and errorCode typehint fix
rtm-ctrlz May 30, 2018
e29d6ab
[phpdoc] ApiRequestor and ClientInterface phpdoc fixes
rtm-ctrlz Jun 13, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
134 changes: 131 additions & 3 deletions lib/ApiRequestor.php
View file
Open in desktop
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
Open in desktop
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);
}