From 22d3727d750c3cd99fb63ab7710b037b7f592fc5 Mon Sep 17 00:00:00 2001 From: Olivier Bellone Date: Fri, 16 Nov 2018 10:47:58 +0100 Subject: [PATCH] Update constructors of Stripe exception classes --- lib/ApiRequestor.php | 17 +++---- lib/Error/Api.php | 7 +++ lib/Error/ApiConnection.php | 6 +++ lib/Error/Authentication.php | 5 +++ lib/Error/Base.php | 49 ++++++++++++--------- lib/Error/Card.php | 25 +++++------ lib/Error/Idempotency.php | 5 +++ lib/Error/InvalidRequest.php | 12 ++++- lib/Error/OAuth/InvalidClient.php | 6 ++- lib/Error/OAuth/InvalidGrant.php | 9 ++-- lib/Error/OAuth/InvalidRequest.php | 6 ++- lib/Error/OAuth/InvalidScope.php | 2 + lib/Error/OAuth/OAuthBase.php | 9 +++- lib/Error/OAuth/UnsupportedGrantType.php | 5 ++- lib/Error/OAuth/UnsupportedResponseType.php | 5 ++- lib/Error/Permission.php | 5 +++ lib/Error/RateLimit.php | 6 +++ lib/Error/SignatureVerification.php | 9 +++- 18 files changed, 132 insertions(+), 56 deletions(-) diff --git a/lib/ApiRequestor.php b/lib/ApiRequestor.php index 276dbf925..356e3500d 100644 --- a/lib/ApiRequestor.php +++ b/lib/ApiRequestor.php @@ -193,31 +193,32 @@ private static function _specificAPIError($rbody, $rcode, $rheaders, $resp, $err $param = isset($errorData['param']) ? $errorData['param'] : null; $code = isset($errorData['code']) ? $errorData['code'] : null; $type = isset($errorData['type']) ? $errorData['type'] : null; + $declineCode = isset($errorData['decline_code']) ? $errorData['decline_code'] : null; switch ($rcode) { case 400: // 'rate_limit' code is deprecated, but left here for backwards compatibility // for API versions earlier than 2015-09-08 if ($code == 'rate_limit') { - return new Error\RateLimit($msg, $param, $rcode, $rbody, $resp, $rheaders); + return new Error\RateLimit($msg, $param, $rcode, $rbody, $resp, $rheaders, $code); } if ($type == 'idempotency_error') { - return new Error\Idempotency($msg, $rcode, $rbody, $resp, $rheaders); + return new Error\Idempotency($msg, $rcode, $rbody, $resp, $rheaders, $code); } // no break case 404: - return new Error\InvalidRequest($msg, $param, $rcode, $rbody, $resp, $rheaders); + return new Error\InvalidRequest($msg, $param, $rcode, $rbody, $resp, $rheaders, $code); case 401: - return new Error\Authentication($msg, $rcode, $rbody, $resp, $rheaders); + return new Error\Authentication($msg, $rcode, $rbody, $resp, $rheaders, $code); case 402: - return new Error\Card($msg, $param, $code, $rcode, $rbody, $resp, $rheaders); + return new Error\Card($msg, $param, $code, $rcode, $rbody, $resp, $rheaders, $declineCode); case 403: - return new Error\Permission($msg, $rcode, $rbody, $resp, $rheaders); + return new Error\Permission($msg, $rcode, $rbody, $resp, $rheaders, $code); case 429: - return new Error\RateLimit($msg, $param, $rcode, $rbody, $resp, $rheaders); + return new Error\RateLimit($msg, $param, $rcode, $rbody, $resp, $rheaders, $code); default: - return new Error\Api($msg, $rcode, $rbody, $resp, $rheaders); + return new Error\Api($msg, $rcode, $rbody, $resp, $rheaders, $code); } } diff --git a/lib/Error/Api.php b/lib/Error/Api.php index dc7d069ef..df97730af 100644 --- a/lib/Error/Api.php +++ b/lib/Error/Api.php @@ -2,6 +2,13 @@ namespace Stripe\Error; +/** + * Api is a generic error that may be raised in cases where none of the other named errors cover + * the problem. It could also be raised in the case that a new error has been introduced in the API, + * but this version of the PHP SDK doesn't know how to handle it. + * + * @package Stripe\Error + */ class Api extends Base { } diff --git a/lib/Error/ApiConnection.php b/lib/Error/ApiConnection.php index 06d097eac..834e3d3c3 100644 --- a/lib/Error/ApiConnection.php +++ b/lib/Error/ApiConnection.php @@ -2,6 +2,12 @@ namespace Stripe\Error; +/** + * ApiConnection is raised in the event that the SDK can't connect to Stripe's servers. That can be + * for a variety of different reasons from a downed network to a bad TLS certificate. + * + * @package Stripe\Error + */ class ApiConnection extends Base { } diff --git a/lib/Error/Authentication.php b/lib/Error/Authentication.php index c50b4f095..2651f628b 100644 --- a/lib/Error/Authentication.php +++ b/lib/Error/Authentication.php @@ -2,6 +2,11 @@ namespace Stripe\Error; +/** + * Authentication is raised when invalid credentials are used to connect to Stripe's servers. + * + * @package Stripe\Error + */ class Authentication extends Base { } diff --git a/lib/Error/Base.php b/lib/Error/Base.php index c0051e6a4..204ca59d5 100644 --- a/lib/Error/Base.php +++ b/lib/Error/Base.php @@ -4,44 +4,54 @@ use Exception; +/** + * Base is the base error from which all other more specific Stripe errors derive. + * + * @package Stripe\Error + */ abstract class Base extends Exception { + protected $httpBody; + protected $httpHeaders; + protected $httpStatus; + protected $jsonBody; + protected $requestId; + protected $stripeCode; + public function __construct( $message, $httpStatus = null, $httpBody = null, $jsonBody = null, - $httpHeaders = null + $httpHeaders = null, + $stripeCode = null ) { parent::__construct($message); $this->httpStatus = $httpStatus; $this->httpBody = $httpBody; $this->jsonBody = $jsonBody; $this->httpHeaders = $httpHeaders; - $this->requestId = null; - - // TODO: make this a proper constructor argument in the next major - // release. - $this->stripeCode = isset($jsonBody["error"]["code"]) ? $jsonBody["error"]["code"] : null; + $this->stripeCode = $stripeCode; + $this->requestId = null; if ($httpHeaders && isset($httpHeaders['Request-Id'])) { $this->requestId = $httpHeaders['Request-Id']; } } - public function getStripeCode() + public function getHttpBody() { - return $this->stripeCode; + return $this->httpBody; } - public function getHttpStatus() + public function getHttpHeaders() { - return $this->httpStatus; + return $this->httpHeaders; } - public function getHttpBody() + public function getHttpStatus() { - return $this->httpBody; + return $this->httpStatus; } public function getJsonBody() @@ -49,21 +59,20 @@ public function getJsonBody() return $this->jsonBody; } - public function getHttpHeaders() + public function getRequestId() { - return $this->httpHeaders; + return $this->requestId; } - public function getRequestId() + public function getStripeCode() { - return $this->requestId; + return $this->stripeCode; } public function __toString() { - $id = $this->requestId ? " from API request '{$this->requestId}'": ""; - $message = explode("\n", parent::__toString()); - $message[0] .= $id; - return implode("\n", $message); + $statusStr = ($this->getHttpStatus() == null) ? "" : "(Status {$this->getHttpStatus()}) "; + $idStr = ($this->getRequestId() == null) ? "" : "(Request {$this->getRequestId()}) "; + return "{$statusStr}{$idStr}{$this->getMessage()}"; } } diff --git a/lib/Error/Card.php b/lib/Error/Card.php index f3ff343d8..205f238aa 100644 --- a/lib/Error/Card.php +++ b/lib/Error/Card.php @@ -2,8 +2,16 @@ namespace Stripe\Error; +/** + * Card is raised when a user enters a card that can't be charged for some reason. + * + * @package Stripe\Error + */ class Card extends Base { + protected $declineCode; + protected $stripeParam; + public function __construct( $message, $stripeParam, @@ -11,21 +19,12 @@ public function __construct( $httpStatus, $httpBody, $jsonBody, - $httpHeaders = null + $httpHeaders = null, + $declineCode = null ) { - parent::__construct($message, $httpStatus, $httpBody, $jsonBody, $httpHeaders); + parent::__construct($message, $httpStatus, $httpBody, $jsonBody, $httpHeaders, $stripeCode); + $this->declineCode = $declineCode; $this->stripeParam = $stripeParam; - - // TODO: once Error\Base accepts the error code as an argument, pass it - // in the call to parent::__construct() and stop setting it here. - $this->stripeCode = $stripeCode; - - // This one is not like the others because it was added later and we're - // trying to do our best not to change the public interface of this class' - // constructor. - // TODO: make this a proper constructor argument in the next major - // release. - $this->declineCode = isset($jsonBody["error"]["decline_code"]) ? $jsonBody["error"]["decline_code"] : null; } public function getDeclineCode() diff --git a/lib/Error/Idempotency.php b/lib/Error/Idempotency.php index ea44d12e4..2d7eca3d8 100644 --- a/lib/Error/Idempotency.php +++ b/lib/Error/Idempotency.php @@ -2,6 +2,11 @@ namespace Stripe\Error; +/** + * Idempotency is raised in cases where an idempotency key was used improperly. + * + * @package Stripe\Error + */ class Idempotency extends Base { } diff --git a/lib/Error/InvalidRequest.php b/lib/Error/InvalidRequest.php index 493bc184c..73223ffeb 100644 --- a/lib/Error/InvalidRequest.php +++ b/lib/Error/InvalidRequest.php @@ -2,17 +2,25 @@ namespace Stripe\Error; +/** + * InvalidRequest is raised when a request is initiated with invalid parameters. + * + * @package Stripe\Error + */ class InvalidRequest extends Base { + protected $stripeParam; + public function __construct( $message, $stripeParam, $httpStatus = null, $httpBody = null, $jsonBody = null, - $httpHeaders = null + $httpHeaders = null, + $stripeCode = null ) { - parent::__construct($message, $httpStatus, $httpBody, $jsonBody, $httpHeaders); + parent::__construct($message, $httpStatus, $httpBody, $jsonBody, $httpHeaders, $stripeCode); $this->stripeParam = $stripeParam; } diff --git a/lib/Error/OAuth/InvalidClient.php b/lib/Error/OAuth/InvalidClient.php index b47346cde..19fce5ae8 100644 --- a/lib/Error/OAuth/InvalidClient.php +++ b/lib/Error/OAuth/InvalidClient.php @@ -3,7 +3,11 @@ namespace Stripe\Error\OAuth; /** - * InvalidClient is raised when authentication fails. + * InvalidClient is raised when the client doesn't belong to you, or the API key mode (live or test) + * doesn't match the client mode. Or the stripe_user_id doesn't exist or isn't connected to your + * application. + * + * @package Stripe\Error\OAuth */ class InvalidClient extends OAuthBase { diff --git a/lib/Error/OAuth/InvalidGrant.php b/lib/Error/OAuth/InvalidGrant.php index 62df56c25..959aa4fa3 100644 --- a/lib/Error/OAuth/InvalidGrant.php +++ b/lib/Error/OAuth/InvalidGrant.php @@ -3,10 +3,11 @@ namespace Stripe\Error\OAuth; /** - * InvalidGrant is raised when a specified code doesn't exist, is - * expired, has been used, or doesn't belong to you; a refresh token doesn't - * exist, or doesn't belong to you; or if an API key's mode (live or test) - * doesn't match the mode of a code or refresh token. + * InvalidGrant is raised when a specified code doesn't exist, is expired, has been used, or doesn't + * belong to you; a refresh token doesn't exist, or doesn't belong to you; or if an API key's mode + * (live or test) doesn't match the mode of a code or refresh token. + * + * @package Stripe\Error\OAuth */ class InvalidGrant extends OAuthBase { diff --git a/lib/Error/OAuth/InvalidRequest.php b/lib/Error/OAuth/InvalidRequest.php index 7f0e8b4ee..230e84490 100644 --- a/lib/Error/OAuth/InvalidRequest.php +++ b/lib/Error/OAuth/InvalidRequest.php @@ -3,8 +3,10 @@ namespace Stripe\Error\OAuth; /** - * InvalidRequest is raised when a code, refresh token, or grant type - * parameter is not provided, but was required. + * InvalidRequest is raised when a code, refresh token, or grant type parameter is not provided, but + * was required. + * + * @package Stripe\Error\OAuth */ class InvalidRequest extends OAuthBase { diff --git a/lib/Error/OAuth/InvalidScope.php b/lib/Error/OAuth/InvalidScope.php index 03cc67e63..f2bb7032c 100644 --- a/lib/Error/OAuth/InvalidScope.php +++ b/lib/Error/OAuth/InvalidScope.php @@ -4,6 +4,8 @@ /** * InvalidScope is raised when an invalid scope parameter is provided. + * + * @package Stripe\Error\OAuth */ class InvalidScope extends OAuthBase { diff --git a/lib/Error/OAuth/OAuthBase.php b/lib/Error/OAuth/OAuthBase.php index 03ada1c7b..805646135 100644 --- a/lib/Error/OAuth/OAuthBase.php +++ b/lib/Error/OAuth/OAuthBase.php @@ -2,8 +2,15 @@ namespace Stripe\Error\OAuth; +/** + * OAuthBase is raised when the OAuth API returns an error. + * + * @package Stripe\Error\OAuth + */ class OAuthBase extends \Stripe\Error\Base { + protected $errorCode; + public function __construct( $code, $description, @@ -12,7 +19,7 @@ public function __construct( $jsonBody = null, $httpHeaders = null ) { - parent::__construct($description, $httpStatus, $httpBody, $jsonBody, $httpHeaders); + parent::__construct($description, $httpStatus, $httpBody, $jsonBody, $httpHeaders, null); $this->errorCode = $code; } diff --git a/lib/Error/OAuth/UnsupportedGrantType.php b/lib/Error/OAuth/UnsupportedGrantType.php index 421adc996..4a720b3f9 100644 --- a/lib/Error/OAuth/UnsupportedGrantType.php +++ b/lib/Error/OAuth/UnsupportedGrantType.php @@ -3,8 +3,9 @@ namespace Stripe\Error\OAuth; /** - * UnsupportedGrantType is raised when an unuspported grant type - * parameter is specified. + * UnsupportedGrantType is raised when an unuspported grant type parameter is specified. + * + * @package Stripe\Error\OAuth */ class UnsupportedGrantType extends OAuthBase { diff --git a/lib/Error/OAuth/UnsupportedResponseType.php b/lib/Error/OAuth/UnsupportedResponseType.php index ed1487894..7b7dcd518 100644 --- a/lib/Error/OAuth/UnsupportedResponseType.php +++ b/lib/Error/OAuth/UnsupportedResponseType.php @@ -3,8 +3,9 @@ namespace Stripe\Error\OAuth; /** - * UnsupportedResponseType is raised when an unsupported response type - * parameter is specified. + * UnsupportedResponseType is raised when an unsupported response type parameter is specified. + * + * @package Stripe\Error\OAuth */ class UnsupportedResponseType extends OAuthBase { diff --git a/lib/Error/Permission.php b/lib/Error/Permission.php index df2b78748..170871cc9 100644 --- a/lib/Error/Permission.php +++ b/lib/Error/Permission.php @@ -2,6 +2,11 @@ namespace Stripe\Error; +/** + * Permission is raised in cases where access was attempted on a resource that wasn't allowed. + * + * @package Stripe\Error + */ class Permission extends Base { } diff --git a/lib/Error/RateLimit.php b/lib/Error/RateLimit.php index 2fa3be4ec..30ef0e689 100644 --- a/lib/Error/RateLimit.php +++ b/lib/Error/RateLimit.php @@ -2,6 +2,12 @@ namespace Stripe\Error; +/** + * RateLimit is raised in cases where an account is putting too much load on Stripe's API servers + * (usually by performing too many requests). Please back off on request rate. + * + * @package Stripe\Error + */ class RateLimit extends InvalidRequest { } diff --git a/lib/Error/SignatureVerification.php b/lib/Error/SignatureVerification.php index 98ddd3b02..f6e6e8223 100644 --- a/lib/Error/SignatureVerification.php +++ b/lib/Error/SignatureVerification.php @@ -2,14 +2,21 @@ namespace Stripe\Error; +/** + * SignatureVerificationError is raised when the signature verification for a webhook fails. + * + * @package Stripe\Error + */ class SignatureVerification extends Base { + protected $sigHeader; + public function __construct( $message, $sigHeader, $httpBody = null ) { - parent::__construct($message, null, $httpBody, null, null); + parent::__construct($message, null, $httpBody, null, null, null); $this->sigHeader = $sigHeader; }