Modernize exceptions

stripe · Aug 30, 2019 · 4699c5d · 4699c5d
1 parent 9621cb5
commit 4699c5d
Show file tree

Hide file tree

Showing 109 changed files with 1,096 additions and 635 deletions.
diff --git a/examples/oauth.php b/examples/oauth.php
@@ -15,7 +15,7 @@
             'grant_type' => 'authorization_code',
             'code' => $code,
         ]);
-    } catch (\Stripe\Error\OAuth\OAuthBase $e) {
+    } catch (\Stripe\Exception\OAuth\OAuthErrorException $e) {
         exit("Error: " . $e->getMessage());
     }
 
@@ -38,7 +38,7 @@
         \Stripe\OAuth::deauthorize([
             'stripe_user_id' => $accountId,
         ]);
-    } catch (\Stripe\Error\OAuth\OAuthBase $e) {
+    } catch (\Stripe\Exception\OAuth\OAuthErrorException $e) {
         exit("Error: " . $e->getMessage());
     }
 

diff --git a/init.php b/init.php
@@ -16,26 +16,32 @@
 require(dirname(__FILE__) . '/lib/HttpClient/ClientInterface.php');
 require(dirname(__FILE__) . '/lib/HttpClient/CurlClient.php');
 
-// Errors
-require(dirname(__FILE__) . '/lib/Error/Base.php');
-require(dirname(__FILE__) . '/lib/Error/Api.php');
-require(dirname(__FILE__) . '/lib/Error/ApiConnection.php');
-require(dirname(__FILE__) . '/lib/Error/Authentication.php');
-require(dirname(__FILE__) . '/lib/Error/Card.php');
-require(dirname(__FILE__) . '/lib/Error/Idempotency.php');
-require(dirname(__FILE__) . '/lib/Error/InvalidRequest.php');
-require(dirname(__FILE__) . '/lib/Error/Permission.php');
-require(dirname(__FILE__) . '/lib/Error/RateLimit.php');
-require(dirname(__FILE__) . '/lib/Error/SignatureVerification.php');
+// Exceptions
+require(dirname(__FILE__) . '/lib/Exception/ExceptionInterface.php');
+require(dirname(__FILE__) . '/lib/Exception/ApiErrorException.php');
+require(dirname(__FILE__) . '/lib/Exception/ApiConnectionException.php');
+require(dirname(__FILE__) . '/lib/Exception/AuthenticationException.php');
+require(dirname(__FILE__) . '/lib/Exception/BadMethodCallException.php');
+require(dirname(__FILE__) . '/lib/Exception/CardException.php');
+require(dirname(__FILE__) . '/lib/Exception/IdempotencyException.php');
+require(dirname(__FILE__) . '/lib/Exception/InvalidArgumentException.php');
+require(dirname(__FILE__) . '/lib/Exception/InvalidRequestException.php');
+require(dirname(__FILE__) . '/lib/Exception/PermissionException.php');
+require(dirname(__FILE__) . '/lib/Exception/RateLimitException.php');
+require(dirname(__FILE__) . '/lib/Exception/SignatureVerificationException.php');
+require(dirname(__FILE__) . '/lib/Exception/UnexpectedValueException.php');
+require(dirname(__FILE__) . '/lib/Exception/UnknownApiErrorException.php');
 
-// OAuth errors
-require(dirname(__FILE__) . '/lib/Error/OAuth/OAuthBase.php');
-require(dirname(__FILE__) . '/lib/Error/OAuth/InvalidClient.php');
-require(dirname(__FILE__) . '/lib/Error/OAuth/InvalidGrant.php');
-require(dirname(__FILE__) . '/lib/Error/OAuth/InvalidRequest.php');
-require(dirname(__FILE__) . '/lib/Error/OAuth/InvalidScope.php');
-require(dirname(__FILE__) . '/lib/Error/OAuth/UnsupportedGrantType.php');
-require(dirname(__FILE__) . '/lib/Error/OAuth/UnsupportedResponseType.php');
+// OAuth exceptions
+require(dirname(__FILE__) . '/lib/Exception/OAuth/ExceptionInterface.php');
+require(dirname(__FILE__) . '/lib/Exception/OAuth/OAuthErrorException.php');
+require(dirname(__FILE__) . '/lib/Exception/OAuth/InvalidClientException.php');
+require(dirname(__FILE__) . '/lib/Exception/OAuth/InvalidGrantException.php');
+require(dirname(__FILE__) . '/lib/Exception/OAuth/InvalidRequestException.php');
+require(dirname(__FILE__) . '/lib/Exception/OAuth/InvalidScopeException.php');
+require(dirname(__FILE__) . '/lib/Exception/OAuth/UnknownOAuthErrorException.php');
+require(dirname(__FILE__) . '/lib/Exception/OAuth/UnsupportedGrantTypeException.php');
+require(dirname(__FILE__) . '/lib/Exception/OAuth/UnsupportedResponseTypeException.php');
 
 // API operations
 require(dirname(__FILE__) . '/lib/ApiOperations/All.php');

diff --git a/lib/Account.php b/lib/Account.php
@@ -103,6 +103,8 @@ public function instanceUrl()
      *     options array containing an `id` key.
      * @param array|string|null $opts
      *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
      * @return Account
      */
     public static function retrieve($id = null, $opts = null)
@@ -118,6 +120,8 @@ public static function retrieve($id = null, $opts = null)
      * @param array|null $params
      * @param array|string|null $opts
      *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
      * @return Account The rejected account.
      */
     public function reject($params = null, $opts = null)
@@ -132,6 +136,8 @@ public function reject($params = null, $opts = null)
      * @param array|null $clientId
      * @param array|string|null $opts
      *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
      * @return StripeObject Object containing the response from the API.
      */
     public function deauthorize($clientId = null, $opts = null)
@@ -156,6 +162,8 @@ public function deauthorize($clientId = null, $opts = null)
      * @param array|null $params
      * @param array|string|null $opts
      *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
      * @return Capability
      */
     public static function retrieveCapability($id, $capabilityId, $params = null, $opts = null)
@@ -181,6 +189,8 @@ public static function updateCapability($id, $capabilityId, $params = null, $opt
      * @param array|null $params
      * @param array|string|null $opts
      *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
      * @return Collection The list of capabilities.
      */
     public static function allCapabilities($id, $params = null, $opts = null)
@@ -193,6 +203,8 @@ public static function allCapabilities($id, $params = null, $opts = null)
      * @param array|null $params
      * @param array|string|null $opts
      *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
      * @return BankAccount|Card
      */
     public static function createExternalAccount($id, $params = null, $opts = null)
@@ -206,6 +218,8 @@ public static function createExternalAccount($id, $params = null, $opts = null)
      * @param array|null $params
      * @param array|string|null $opts
      *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
      * @return BankAccount|Card
      */
     public static function retrieveExternalAccount($id, $externalAccountId, $params = null, $opts = null)
@@ -219,6 +233,8 @@ public static function retrieveExternalAccount($id, $externalAccountId, $params
      * @param array|null $params
      * @param array|string|null $opts
      *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
      * @return BankAccount|Card
      */
     public static function updateExternalAccount($id, $externalAccountId, $params = null, $opts = null)
@@ -232,6 +248,8 @@ public static function updateExternalAccount($id, $externalAccountId, $params =
      * @param array|null $params
      * @param array|string|null $opts
      *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
      * @return BankAccount|Card
      */
     public static function deleteExternalAccount($id, $externalAccountId, $params = null, $opts = null)
@@ -244,6 +262,8 @@ public static function deleteExternalAccount($id, $externalAccountId, $params =
      * @param array|null $params
      * @param array|string|null $opts
      *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
      * @return Collection The list of external accounts (BankAccount or Card).
      */
     public static function allExternalAccounts($id, $params = null, $opts = null)
@@ -256,6 +276,8 @@ public static function allExternalAccounts($id, $params = null, $opts = null)
      * @param array|null $params
      * @param array|string|null $opts
      *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
      * @return LoginLink
      */
     public static function createLoginLink($id, $params = null, $opts = null)
@@ -267,6 +289,8 @@ public static function createLoginLink($id, $params = null, $opts = null)
      * @param array|null $params
      * @param array|string|null $options
      *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
      * @return Collection The list of persons.
      */
     public function persons($params = null, $options = null)
@@ -283,6 +307,8 @@ public function persons($params = null, $options = null)
      * @param array|null $params
      * @param array|string|null $opts
      *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
      * @return Person
      */
     public static function createPerson($id, $params = null, $opts = null)
@@ -296,6 +322,8 @@ public static function createPerson($id, $params = null, $opts = null)
      * @param array|null $params
      * @param array|string|null $opts
      *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
      * @return Person
      */
     public static function retrievePerson($id, $personId, $params = null, $opts = null)
@@ -309,6 +337,8 @@ public static function retrievePerson($id, $personId, $params = null, $opts = nu
      * @param array|null $params
      * @param array|string|null $opts
      *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
      * @return Person
      */
     public static function updatePerson($id, $personId, $params = null, $opts = null)
@@ -322,6 +352,8 @@ public static function updatePerson($id, $personId, $params = null, $opts = null
      * @param array|null $params
      * @param array|string|null $opts
      *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
      * @return Person
      */
     public static function deletePerson($id, $personId, $params = null, $opts = null)
@@ -334,6 +366,8 @@ public static function deletePerson($id, $personId, $params = null, $opts = null
      * @param array|null $params
      * @param array|string|null $opts
      *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
      * @return Collection The list of persons.
      */
     public static function allPersons($id, $params = null, $opts = null)
@@ -370,7 +404,7 @@ private function serializeAdditionalOwners($legalEntity, $additionalOwners)
             $originalValue = [];
         }
         if (($originalValue) && (count($originalValue) > count($additionalOwners))) {
-            throw new \InvalidArgumentException(
+            throw new Exception\InvalidArgumentException(
                 "You cannot delete an item from an array, you must instead set a new array"
             );
         }

diff --git a/lib/AlipayAccount.php b/lib/AlipayAccount.php
@@ -29,7 +29,7 @@ public function instanceUrl()
             $path = 'sources';
         } else {
             $msg = "Alipay accounts cannot be accessed without a customer ID.";
-            throw new Error\InvalidRequest($msg, null);
+            throw new Exception\UnexpectedValueException($msg);
         }
         $parentExtn = urlencode(Util\Util::utf8($parent));
         $extn = urlencode(Util\Util::utf8($this['id']));
@@ -40,7 +40,7 @@ public function instanceUrl()
      * @param array|string $_id
      * @param array|string|null $_opts
      *
-     * @throws \Stripe\Error\InvalidRequest
+     * @throws \Stripe\Exception\BadMethodCallException
      *
      * @deprecated Alipay accounts are deprecated. Please use the sources API instead.
      * @link https://stripe.com/docs/sources/alipay
@@ -50,15 +50,15 @@ public static function retrieve($_id, $_opts = null)
         $msg = "Alipay accounts cannot be retrieved without a customer ID. " .
                "Retrieve an Alipay account using `Customer::retrieveSource(" .
                "'customer_id', 'alipay_account_id')`.";
-        throw new Error\InvalidRequest($msg, null);
+        throw new Exception\BadMethodCallException($msg);
     }
 
     /**
      * @param string $_id
      * @param array|null $_params
      * @param array|string|null $_options
      *
-     * @throws \Stripe\Error\InvalidRequest
+     * @throws \Stripe\Exception\BadMethodCallException
      *
      * @deprecated Alipay accounts are deprecated. Please use the sources API instead.
      * @link https://stripe.com/docs/sources/alipay
@@ -68,6 +68,6 @@ public static function update($_id, $_params = null, $_options = null)
         $msg = "Alipay accounts cannot be updated without a customer ID. " .
                "Update an Alipay account using `Customer::updateSource(" .
                "'customer_id', 'alipay_account_id', \$updateParams)`.";
-        throw new Error\InvalidRequest($msg, null);
+        throw new Exception\BadMethodCallException($msg);
     }
 }
diff --git a/lib/ApiOperations/All.php b/lib/ApiOperations/All.php
@@ -13,6 +13,8 @@ trait All
      * @param array|null $params
      * @param array|string|null $opts
      *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
      * @return \Stripe\Collection of ApiResources
      */
     public static function all($params = null, $opts = null)
@@ -23,7 +25,7 @@ public static function all($params = null, $opts = null)
         list($response, $opts) = static::_staticRequest('get', $url, $params, $opts);
         $obj = \Stripe\Util\Util::convertToStripeObject($response->json, $opts);
         if (!($obj instanceof \Stripe\Collection)) {
-            throw new \Stripe\Error\Api(
+            throw new \Stripe\Exception\UnexpectedValueException(
                 'Expected type ' . \Stripe\Collection::class . ', got "' . get_class($obj) . '" instead.'
             );
         }

diff --git a/lib/ApiOperations/Create.php b/lib/ApiOperations/Create.php
@@ -13,6 +13,8 @@ trait Create
      * @param array|null $params
      * @param array|string|null $options
      *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
      * @return static The created resource.
      */
     public static function create($params = null, $options = null)

diff --git a/lib/ApiOperations/Delete.php b/lib/ApiOperations/Delete.php
@@ -13,6 +13,8 @@ trait Delete
      * @param array|null $params
      * @param array|string|null $opts
      *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
      * @return static The deleted resource.
      */
     public function delete($params = null, $opts = null)

diff --git a/lib/ApiOperations/NestedResource.php b/lib/ApiOperations/NestedResource.php
@@ -49,6 +49,8 @@ protected static function _nestedResourceUrl($id, $nestedPath, $nestedId = null)
      * @param array|null $params
      * @param array|string|null $options
      *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
      * @return \Stripe\StripeObject
      */
     protected static function _createNestedResource($id, $nestedPath, $params = null, $options = null)
@@ -64,6 +66,8 @@ protected static function _createNestedResource($id, $nestedPath, $params = null
      * @param array|null $params
      * @param array|string|null $options
      *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
      * @return \Stripe\StripeObject
      */
     protected static function _retrieveNestedResource($id, $nestedPath, $nestedId, $params = null, $options = null)
@@ -79,6 +83,8 @@ protected static function _retrieveNestedResource($id, $nestedPath, $nestedId, $
      * @param array|null $params
      * @param array|string|null $options
      *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
      * @return \Stripe\StripeObject
      */
     protected static function _updateNestedResource($id, $nestedPath, $nestedId, $params = null, $options = null)
@@ -94,6 +100,8 @@ protected static function _updateNestedResource($id, $nestedPath, $nestedId, $pa
      * @param array|null $params
      * @param array|string|null $options
      *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
      * @return \Stripe\StripeObject
      */
     protected static function _deleteNestedResource($id, $nestedPath, $nestedId, $params = null, $options = null)
@@ -108,6 +116,8 @@ protected static function _deleteNestedResource($id, $nestedPath, $nestedId, $pa
      * @param array|null $params
      * @param array|string|null $options
      *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
      * @return \Stripe\StripeObject
      */
     protected static function _allNestedResources($id, $nestedPath, $params = null, $options = null)

diff --git a/lib/ApiOperations/Request.php b/lib/ApiOperations/Request.php
@@ -12,7 +12,7 @@ trait Request
     /**
      * @param array|null|mixed $params The list of parameters to validate
      *
-     * @throws \Stripe\Error\Api if $params exists and is not an array
+     * @throws \Stripe\Exception\InvalidArgumentException if $params exists and is not an array
      */
     protected static function _validateParams($params = null)
     {
@@ -21,7 +21,7 @@ protected static function _validateParams($params = null)
                . "method calls.  (HINT: an example call to create a charge "
                . "would be: \"Stripe\\Charge::create(['amount' => 100, "
                . "'currency' => 'usd', 'source' => 'tok_1234'])\")";
-            throw new \Stripe\Error\Api($message);
+            throw new \Stripe\Exception\InvalidArgumentException($message);
         }
     }
 
@@ -31,6 +31,8 @@ protected static function _validateParams($params = null)
      * @param array $params list of parameters for the request
      * @param array|string|null $options
      *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
      * @return array tuple containing (the JSON response, $options)
      */
     protected function _request($method, $url, $params = [], $options = null)
@@ -47,6 +49,8 @@ protected function _request($method, $url, $params = [], $options = null)
      * @param array $params list of parameters for the request
      * @param array|string|null $options
      *
+     * @throws \Stripe\Exception\ApiErrorException if the request fails
+     *
      * @return array tuple containing (the JSON response, $options)
      */
     protected static function _staticRequest($method, $url, $params, $options)