feat: overhauls exceptions with new classes and inheritence

fix:ecode to code

chore: first batch of errors migrated

fix: exception inheritence and locations

feat: import all exceptions

feat: convert remainder of errors

fix: tests relating to errors

fix: lint

feat: use remaining error types depending on status code

fix: throws docblock comments

fix: last minute things

Author: Justintime50

CHANGELOG.md

@@ -15,6 +15,7 @@
 - `validateWebhook`, `getLowestSmartRate`, and `receiveEvent` are now under `EasyPost\Util\Util` as they do not make any API calls
   - Internal only utilities have been moved to `EasyPost\Util\InternalUtil`
 - The beta `EndShipper` class has been removed, please use the generally available `EndShipper` class
+- The `ecode` property of an `Error` is now just `code`
 
 ## v5.8.0 (2022-12-01)
 

Makefile

@@ -9,7 +9,7 @@ clean:
 ## coverage - Runs the test suite and generates a coverage report
 coverage:
 	composer coverage
-	bin/coverage-check build/logs/clover.xml 82 --only-percentage
+	bin/coverage-check build/logs/clover.xml 78 --only-percentage
 
 ## docs - Generate documentation for the library
 docs:

lib/EasyPost/Constant/Constants.php

@@ -19,4 +19,20 @@ abstract class Constants
         'FedexAccount',
         'UpsAccount'
     ];
+
+    // Exception messages (many of these are intended to be used with `sprintf()`)
+    const ARRAY_REQUIRED_ERROR = 'You must pass an array as the first argument to EasyPost API method calls.';
+    const COMMUNICATION_ERROR = 'Unexpected error communicating with %s. If this problem persists please let us know at ' . self::SUPPORT_EMAIL . '. %s';
+    const DECODE_WEBHOOK_ERROR = 'There was a problem decoding the webhook.';
+    const INVALID_PARAMETER_ERROR_WITH_SUGGESTION = 'Invalid %s value, must be one of: %s';
+    const INVALID_PAYMENT_METHOD_ERROR = 'The chosen payment method is not valid. Please try again.';
+    const INVALID_SIGNATURE_ERROR = 'Webhook received does not contain an HMAC signature.';
+    const INVALID_WEBHOOK_VALIDATION_ERROR = 'Webhook received did not originate from EasyPost or had a webhook secret mismatch.';
+    const MISSING_PARAMETER_ERROR = '%s is required.';
+    const NO_BILLING_ERROR = 'Billing has not been setup for this user. Please add a payment method.';
+    const NO_ID_URL_ERROR = 'Could not determine which URL to request: %s instance has invalid ID: %s';
+    const NO_RATES_ERROR = 'No rates found.';
+    const NO_RESPONSE_ERROR = 'Did not receive a response from %s.';
+    const SEND_STRIPE_DETAILS_ERROR = 'Could not send card details to Stripe, please try again later.';
+    const UNDEFINED_PROPERTY_ERROR = 'EasyPost Notice: Undefined property of %s instance: %s';
 }

lib/EasyPost/EasyPostClient.php

@@ -3,7 +3,7 @@
 namespace EasyPost;
 
 use EasyPost\Constant\Constants;
-use EasyPost\Exception\Error;
+use EasyPost\Exception\General\MissingParameterException;
 use EasyPost\Service\AddressService;
 use EasyPost\Service\BaseService;
 use EasyPost\Service\BatchService;
@@ -122,7 +122,7 @@ public function __construct($apiKey, $timeout = Constants::TIMEOUT, $apiBase = C
         $this->webhook = new WebhookService($this);
 
         if (!$this->apiKey) {
-            throw new Error('No API key provided. See https://www.easypost.com/docs for details, or contact ' . Constants::SUPPORT_EMAIL . ' for assistance.');
+            throw new MissingParameterException('No API key provided. See https://www.easypost.com/docs for details, or contact ' . Constants::SUPPORT_EMAIL . ' for assistance.');
         }
     }
 

lib/EasyPost/EasyPostObject.php

@@ -2,6 +2,7 @@
 
 namespace EasyPost;
 
+use EasyPost\Constant\Constants;
 use EasyPost\Util\InternalUtil;
 use EasyPost\Util\Util;
 
@@ -111,7 +112,7 @@ public function __get($k)
             return $this->_values[$k];
         } else {
             $class = get_class($this);
-            error_log("EasyPost Notice: Undefined property of {$class} instance: {$k}");
+            error_log(sprintf(Constants::UNDEFINED_PROPERTY_ERROR, $class, $k));
 
             return null;
         }

lib/EasyPost/Exception/Error.php renamed to lib/EasyPost/Exception/Api/ApiException.php

@@ -1,25 +1,25 @@
 <?php
 
-namespace EasyPost\Exception;
+namespace EasyPost\Exception\Api;
+
+use EasyPost\Exception\General\EasyPostException;
 
 /**
  * @package EasyPost
  * @property string $code
- * @property string $message
  * @property FieldError[] $errors
  */
-class Error extends \Exception
+class ApiException extends EasyPostException
 {
-    private $httpBody;
-    private $httpStatus;
-    private $jsonBody;
+    protected $httpBody;
+    protected $httpStatus;
+    protected $jsonBody;
+    protected $message;
     public $code;
-    public $ecode;
     public $errors;
-    public $message;
 
     /**
-     * Constructor.
+     * EasyPostException constructor.
      *
      * @param string $message
      * @param int $httpStatus
@@ -33,16 +33,19 @@ public function __construct($message = null, $httpStatus = null, $httpBody = nul
 
         try {
             $this->jsonBody = json_decode($httpBody, true);
+
+            // Setup `errors` property
             if (isset($this->jsonBody) && !empty($this->jsonBody['error']['errors'])) {
                 $this->errors = $this->jsonBody['error']['errors'];
             } else {
                 $this->errors = null;
             }
 
+            // Setup `code` property
             if (isset($this->jsonBody) && !empty($this->jsonBody['error']['code'])) {
-                $this->ecode = $this->jsonBody['error']['code'];
+                $this->code = $this->jsonBody['error']['code'];
             } else {
-                $this->ecode = null;
+                $this->code = null;
             }
         } catch (\Exception $e) {
             $this->jsonBody = null;
@@ -76,7 +79,7 @@ public function getHttpBody()
      */
     public function prettyPrint()
     {
-        print($this->ecode . ' (' . $this->getHttpStatus() . '): ' .
+        print($this->code . ' (' . $this->getHttpStatus() . '): ' .
             $this->getMessage() . "\n");
         if (!empty($this->errors)) {
             print("Field errors:\n");

lib/EasyPost/Exception/Api/EncodingException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace EasyPost\Exception\Api;
+
+class EncodingException extends ApiException
+{
+}

lib/EasyPost/Exception/Api/ExternalApiException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace EasyPost\Exception\Api;
+
+class ExternalApiException extends ApiException
+{
+}

lib/EasyPost/Exception/Api/ForbiddenException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace EasyPost\Exception\Api;
+
+class ForbiddenException extends ApiException
+{
+}

lib/EasyPost/Exception/Api/GatewayTimeoutException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace EasyPost\Exception\Api;
+
+class GatewayTimeoutException extends ApiException
+{
+}

lib/EasyPost/Exception/Api/HttpException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace EasyPost\Exception\Api;
+
+class HttpException extends ApiException
+{
+}

lib/EasyPost/Exception/Api/InternalServerException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace EasyPost\Exception\Api;
+
+class InternalServerException extends ApiException
+{
+}

lib/EasyPost/Exception/Api/InvalidRequestException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace EasyPost\Exception\Api;
+
+class InvalidRequestException extends ApiException
+{
+}

lib/EasyPost/Exception/Api/JsonException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace EasyPost\Exception\Api;
+
+class JsonException extends ApiException
+{
+}

lib/EasyPost/Exception/Api/MethodNotAllowedException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace EasyPost\Exception\Api;
+
+class MethodNotAllowedException extends ApiException
+{
+}

lib/EasyPost/Exception/Api/NotFoundException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace EasyPost\Exception\Api;
+
+class NotFoundException extends ApiException
+{
+}

lib/EasyPost/Exception/Api/PaymentException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace EasyPost\Exception\Api;
+
+class PaymentException extends ApiException
+{
+}

lib/EasyPost/Exception/Api/RateLimitException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace EasyPost\Exception\Api;
+
+class RateLimitException extends ApiException
+{
+}

lib/EasyPost/Exception/Api/RedirectException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace EasyPost\Exception\Api;
+
+class RedirectException extends ApiException
+{
+}

lib/EasyPost/Exception/Api/ServiceUnavailableException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace EasyPost\Exception\Api;
+
+class ServiceUnavailableException extends ApiException
+{
+}

lib/EasyPost/Exception/Api/TimeoutException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace EasyPost\Exception\Api;
+
+class TimeoutException extends ApiException
+{
+}

lib/EasyPost/Exception/Api/UnauthorizedException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace EasyPost\Exception\Api;
+
+class UnauthorizedException extends ApiException
+{
+}

lib/EasyPost/Exception/Api/UnknownApiException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace EasyPost\Exception\Api;
+
+class UnknownApiException extends ApiException
+{
+}

lib/EasyPost/Exception/General/EasyPostException.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace EasyPost\Exception\General;
+
+class EasyPostException extends \Exception
+{
+    /**
+     * EasyPostException constructor.
+     *
+     * @param string $message
+     */
+    public function __construct($message = null)
+    {
+        parent::__construct($message);
+    }
+}

lib/EasyPost/Exception/General/FilteringException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace EasyPost\Exception\General;
+
+class FilteringException extends EasyPostException
+{
+}

lib/EasyPost/Exception/General/InvalidObjectException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace EasyPost\Exception\General;
+
+class InvalidObjectException extends EasyPostException
+{
+}

lib/EasyPost/Exception/General/InvalidParameterException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace EasyPost\Exception\General;
+
+class InvalidParameterException extends EasyPostException
+{
+}

lib/EasyPost/Exception/General/MissingParameterException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace EasyPost\Exception\General;
+
+class MissingParameterException extends EasyPostException
+{
+}

lib/EasyPost/Exception/General/SignatureVerificationException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace EasyPost\Exception\General;
+
+class SignatureVerificationException extends EasyPostException
+{
+}