Feature/exception factory

README.md

@@ -233,3 +233,7 @@ Please do not forget to set the `_API_KEY` constant in
 
 Information regarding the test cases can be found in the [README.md](./tests/README.md)
 located in [test](/tests).
+
+## Exceptions
+The SDK can throw multiple exceptions. For an overview of these exceptions please
+take a look at [EXCEPTIONS.md](./src/Exception/EXCEPTION.md)

src/Exception/ApiException.php

@@ -1,8 +1,33 @@
 <?php
 namespace bunq\Exception;
 
+use Exception;
+
 /**
  */
-class ApiException extends BunqException
+class ApiException extends Exception
 {
+    /**
+     * @var int
+     */
+    private $responseCode;
+
+    /**
+     * @param string $message
+     * @param int $responseCode
+     */
+    public function __construct(string $message, int $responseCode)
+    {
+        $this->responseCode = $responseCode;
+
+        parent::__construct($message);
+    }
+
+    /**
+     * @return int
+     */
+    public function getResponseCode(): int
+    {
+        return $this->responseCode;
+    }
 }

src/Exception/BadRequestException.php

@@ -0,0 +1,9 @@
+<?php
+namespace bunq\Exception;
+
+/**
+ */
+class BadRequestException extends ApiException
+{
+
+}

src/Exception/BunqException.php

@@ -9,7 +9,7 @@ class BunqException extends \Exception
      * @param string $message
      * @param string[] $args
      */
-    public function __construct($message, $args = [])
+    public function __construct(string $message, array $args = [])
     {
         parent::__construct(vsprintf($message, $args));
     }

src/Exception/EXCEPTION.md

@@ -0,0 +1,82 @@
+## Exceptions
+When you make a request via the SDK, there is a chance of request failing
+due to various reasons. When such a failure happens, an exception
+corresponding to the error occurred is raised.
+
+
+----
+#### Possible Exceptions
+* `BadRequestException` If the request returns with status code `400`
+* `UnauthorizedException` If the request returns with status code `401`
+* `ForbiddenException` If the request returns with status code `403`
+* `NotFoundException` If the request returns with status code `404`
+* `MethodNotAllowedException` If the request returns with status code `405`
+* `TooManyRequestsException` If the request returns with status code `429`
+* `PleaseContactBunqException` If the request returns with status code `500`.
+If you get this exception, please contact us preferably via the support chat in the bunq app.
+* `UnknownApiErrorException` If none of the above mentioned exceptions are thrown,
+this exception will be thrown instead.
+
+For more information regarding these errors, please take a look on the documentation
+page here: https://doc.bunq.com/api/1/page/errors
+
+---
+#### Base exception
+All the exceptions have the same base exception which looks like this:
+```php
+<?php
+class ApiException extends Exception
+{
+    /**
+     * @var int
+     */
+    private $responseCode;
+
+    /**
+     * @param string $message
+     * @param int $responseCode
+     */
+    public function __construct(string $message, int $responseCode)
+    {}
+
+    /**
+     * @return int
+     */
+    public function getResponseCode(): int
+    {
+        return $this->responseCode;
+    }
+}
+```
+The `Exception` class which is being extended has an `getMessage()` method which is `final` and therefore cannot be
+overwritten.
+
+This means that each exception will have a response code and an error message
+related to the specific error returned by API.
+
+---
+#### Exception handling
+Since each API error has a distinct SDK exception type corresponding to it,
+you can catch the exact exceptions you expect 👏.
+
+```php
+<?php
+use bunq\Context\ApiContext;
+use bunq\Util\BunqEnumApiEnvironmentType;
+use bunq\Exception\BadRequestException;
+
+
+const API_KEY = 'Some invalid API key '; 
+const DEVICE_DESCRIPTION = 'This will cause BadRequestException to be thrown.';
+
+try{
+    //Make a call that might fail
+    $apiContext = ApiContext::create(BunqEnumApiEnvironmentType::SANDBOX(), API_KEY, DEVICE_DESCRIPTION);
+} catch (BadRequestException $error){
+    //Do something if exception is thrown.
+    echo $error->getResponseCode() . PHP_EOL;
+    echo $error->getMessage() . PHP_EOL;
+}
+
+
+```

src/Exception/ExceptionFactory.php

@@ -0,0 +1,83 @@
+<?php
+namespace bunq\Exception;
+
+/**
+ */
+class ExceptionFactory
+{
+    /**
+     * HTTP error response codes constants.
+     */
+    const HTTP_RESPONSE_CODE_BAD_REQUEST = 400;
+    const HTTP_RESPONSE_CODE_UNAUTHORIZED = 401;
+    const HTTP_RESPONSE_CODE_FORBIDDEN = 403;
+    const HTTP_RESPONSE_CODE_NOT_FOUND = 404;
+    const HTTP_RESPONSE_CODE_METHOD_NOT_ALLOWED = 405;
+    const HTTP_RESPONSE_CODE_TOO_MANY_REQUESTS = 429;
+    const HTTP_RESPONSE_CODE_INTERNAL_SERVER_ERROR = 500;
+
+    /**
+     * Formatting constants
+     */
+    const FORMAT_RESPONSE_CODE_LINE = 'HTTP Response Code: %s';
+    const GLUE_ERROR_MESSAGES = "\n";
+
+    /**
+     * The first item index in an array.
+     */
+    const INDEX_FIRST = 0;
+
+    /**
+     * @param string[] $messages
+     * @param int $responseCode
+     *
+     * @return ApiException
+     */
+    public static function createExceptionForResponse(array $messages, int $responseCode): ApiException
+    {
+        $errorMessage = static::generateErrorMessage($responseCode, $messages);
+
+        switch ($responseCode)
+        {
+            case self::HTTP_RESPONSE_CODE_BAD_REQUEST:
+                return new BadRequestException($errorMessage, $responseCode);
+            case self::HTTP_RESPONSE_CODE_UNAUTHORIZED:
+                return new UnauthorizedException($errorMessage, $responseCode);
+            case self::HTTP_RESPONSE_CODE_FORBIDDEN:
+                return new ForbiddenException($errorMessage, $responseCode);
+            case self::HTTP_RESPONSE_CODE_NOT_FOUND:
+                return new NotFoundException($errorMessage, $responseCode);
+            case self::HTTP_RESPONSE_CODE_METHOD_NOT_ALLOWED:
+                return new MethodNotAllowedException($errorMessage, $responseCode);
+            case self::HTTP_RESPONSE_CODE_TOO_MANY_REQUESTS:
+                return new TooManyRequestsException($errorMessage, $responseCode);
+            case self::HTTP_RESPONSE_CODE_INTERNAL_SERVER_ERROR:
+                return new PleaseContactBunqException($errorMessage, $responseCode);
+            default:
+                return new UnknownApiErrorException($errorMessage, $responseCode);
+        }
+    }
+
+    /**
+     * @param int $responseCode
+     * @param string[] $messages
+     *
+     * @return string
+     */
+    private static function generateErrorMessage(int $responseCode, array $messages): string
+    {
+        $lineResponseCode = sprintf(self::FORMAT_RESPONSE_CODE_LINE, $responseCode);
+
+        return static::glueMessages(array_merge([$lineResponseCode], $messages));
+    }
+
+    /**
+     * @param string[] $messages
+     *
+     * @return string
+     */
+    private static function glueMessages(array $messages): string
+    {
+        return implode(self::GLUE_ERROR_MESSAGES, $messages);
+    }
+}

src/Exception/ForbiddenException.php

@@ -0,0 +1,9 @@
+<?php
+namespace bunq\Exception;
+
+/**
+ */
+class ForbiddenException extends ApiException
+{
+
+}

src/Exception/MethodNotAllowedException.php

@@ -0,0 +1,9 @@
+<?php
+namespace bunq\Exception;
+
+/**
+ */
+class MethodNotAllowedException extends ApiException
+{
+
+}

src/Exception/NotFoundException.php

@@ -0,0 +1,9 @@
+<?php
+namespace bunq\Exception;
+
+/**
+ */
+class NotFoundException extends ApiException
+{
+
+}

src/Exception/PleaseContactBunqException.php

@@ -0,0 +1,9 @@
+<?php
+namespace bunq\Exception;
+
+/**
+ */
+class PleaseContactBunqException extends ApiException
+{
+
+}

src/Exception/TooManyRequestsException.php

@@ -0,0 +1,9 @@
+<?php
+namespace bunq\Exception;
+
+/**
+ */
+class TooManyRequestsException extends ApiException
+{
+
+}

src/Exception/UnauthorizedException.php

@@ -0,0 +1,9 @@
+<?php
+namespace bunq\Exception;
+
+/**
+ */
+class UnauthorizedException extends ApiException
+{
+
+}

src/Exception/UnknownApiErrorException.php

@@ -0,0 +1,9 @@
+<?php
+namespace bunq\Exception;
+
+/**
+ */
+class UnknownApiErrorException extends ApiException
+{
+
+}