Update constructors of Stripe exception classes

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);
         }
     }
 

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
 {
 }

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
 {
 }

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
 {
 }

lib/Error/Base.php

@@ -4,66 +4,75 @@
 
 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()
     {
         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()}";
     }
 }

lib/Error/Card.php

@@ -2,30 +2,29 @@
 
 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,
         $stripeCode,
         $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()

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
 {
 }

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;
     }
 

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_id does not belong to you, the stripe_user_id does not
+ * exist or is not connected to your application, or the API key mode (live or test mode) does not
+ * match the client_id mode.
+ *
+ * @package Stripe\Error\OAuth
  */
 class InvalidClient extends OAuthBase
 {

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
 {

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
 {

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
 {

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;
     }
 

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
 {

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
 {

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
 {
 }

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
 {
 }