Merge pull request #3 from Stackla/SPS-1

SPS-1 Created ApiException to handle API errors

Author: VariLilley

README.md

@@ -3,7 +3,7 @@ Welcome to the Stackla PHP SDK GitHub repository!
 
 This SDK is intended for PHP developers to enable them to integrate Stackla RESTful APIs into their applications with greater ease. You can find more information on working with Stackla APIs on the [Stackla Developer Portal](http://developer.stackla.com/).
 
-We are continously working on improving both the SDK and the documentation around it, so please feel free to give us feedback and any reports of issues to [[email protected]](mailto:[email protected]).
+We are continuously working on improving both the SDK and the documentation around it, so please feel free to give us feedback and any reports of issues to [[email protected]](mailto:[email protected]).
 
 ## System requirements ##
 * PHP >=5.3.3
@@ -488,3 +488,5 @@ delete*** | - | - | - | widget object / self or false
 * _delete_ will not work if the widget has child widget.
 
 ----------------
+
+[Error Handling](doc/error_handling.md)

doc/error_handling.md

@@ -0,0 +1,33 @@
+## Error Handling ##
+
+An `Stackla\Exception\ApiException` is thrown when there are errors.
+
+```
+try {
+    // do something with SDK that could cause errors
+} catch (\Stackla\Exception\ApiException $exception) {
+    $httpStatusCode = $exception->getHttpStatusCode();
+    $httpResponseBody = $exception->getHttpResponseBody();
+
+    // an array of Stackla\Exception\ApiError instances
+    $errors = $exception->getErrors();
+    foreach ($errors as $error) {
+        $message = $error->getMessage(); // human readable message
+        $errorCode = $error->getErrorCode(); // unique error code
+        $messageId = $error->getMessageId(); // unique error message ID
+    }
+
+    // some helper functions
+    // check if a certain error exists by error code
+    if ($exception->containsErrorByErrorCode(1070409)) {
+        // tag name conflict error
+        echo 'Tag name must be unique';
+    }
+
+    // check if a certain error exists by message ID
+    if ($exception->containsErrorByMessageId('term:not_found')) {
+        // the given term cannot be found
+        echo 'Term cannot be found';
+    }
+}
+```

src/Stackla/Core/Request.php

@@ -2,11 +2,11 @@
 
 namespace Stackla\Core;
 
-use \Stackla\Core\Credentials;
-use \Guzzle\Http\Client;
-use \Guzzle\Http\Exception\ClientErrorResponseException;
-use \Guzzle\Http\Exception\BadResponseException;
-use \Guzzle\Http\Exception\CurlException;
+use Guzzle\Http\EntityBodyInterface;
+use Guzzle\Http\Client;
+use Guzzle\Http\Exception\ClientErrorResponseException;
+use Guzzle\Http\Exception\BadResponseException;
+use Stackla\Exception\ApiException;
 
 class Request implements RequestInterface
 {
@@ -30,13 +30,13 @@ class Request implements RequestInterface
 
     /**
      * Response result placeholder
-     * @var \Guzzle\Message\Response
+     * @var \Guzzle\Http\Message\Response
      */
     protected $response;
 
     /**
      * Request placeholder
-     * @var \Guzzle\Message\Request
+     * @var \Guzzle\Http\Message\Request
      */
     protected $request;
 
@@ -48,9 +48,11 @@ class Request implements RequestInterface
 
     private $querySeparator = '&';
 
+    protected $apiKey;
+
     /**
      *
-     * @var Guzzle\Http\Message\Response
+     * @var \Guzzle\Http\Message\Response
      */
     private $client;
 
@@ -60,7 +62,7 @@ public function __construct(\Stackla\Core\Credentials $credentials, $host, $stac
         $this->stack = $stack;
         $this->credentials = $credentials;
         $this->client = new Client();
-        if (class_exists("\Monolog\Logger")) {
+        if (class_exists("\\Monolog\\Logger")) {
             $this->logger = new \Monolog\Logger(get_class($this));
             $this->logger->pushHandler(new \Monolog\Handler\StreamHandler(sys_get_temp_dir() . DIRECTORY_SEPARATOR . 'stackla-request.log', \Monolog\Logger::INFO));
         }
@@ -169,13 +171,12 @@ private function buildOptions(array $data = array())
     /**
      * Making request using Guzzle
      *
-     * @param string    $method     Type of request, iether POST, GET, PUT or DELETE
-     * @param string    $endpoint   The operation / task for API
-     * @param array     $data       The parameter need to be passed
-     * @param array     $options    The options like header, body, etc
-     *
-     * @return \Guzzle\Http\Message\Response     This will return FALSE if something wrong happened
-     *                                          or return json object
+     * @param string $method   Type of request, either POST, GET, PUT or DELETE
+     * @param string $endpoint The operation / task for API
+     * @param array  $data     The parameter need to be passed
+     * @param array  $options  The options like header, body, etc
+     * @return EntityBodyInterface|string
+     * @throws \Exception
      */
     private function sendRequest($method, $endpoint, array $data = array(), array $options = array())
     {
@@ -242,30 +243,40 @@ private function sendRequest($method, $endpoint, array $data = array(), array $o
             }
         }
 
-        switch ($this->response->getStatusCode()) {
+        $statusCode = $this->response->getStatusCode();
+        switch ($statusCode) {
             case 200:
                 return $this->response->getBody(true);
-                break;
             case 400:
-                throw new \Exception(sprintf("Server return %s error code. Bad request: The request could not be understood. %s", $this->response->getStatusCode(), $this->response->getBody(true)));
-                return false;
-                break;
+                throw ApiException::create(
+                    sprintf("Server return %s error code. Bad request: The request could not be understood. %s", $this->response->getStatusCode(), $this->response->getBody(true)),
+                    $statusCode,
+                    $this->response->getBody(true)
+                );
             case 401:
-                throw new \Exception(sprintf("Server return %s error code. Unauthorized: Authentication credentials invalid or not authorised to access resource", $this->response->getStatusCode()));
-                return false;
-                break;
+                throw ApiException::create(
+                    sprintf("Server return %s error code. Unauthorized: Authentication credentials invalid or not authorised to access resource", $this->response->getStatusCode()),
+                    $statusCode,
+                    $this->response->getBody(true)
+                );
             case 403:
-                throw new \Exception(sprintf("Server return %s error code. Rate limit exceeded: Too many requests in the current time window", $this->response->getStatusCode()));
-                return false;
-                break;
+                throw ApiException::create(
+                    sprintf("Server return %s error code. Rate limit exceeded: Too many requests in the current time window", $this->response->getStatusCode()),
+                    $statusCode,
+                    $this->response->getBody(true)
+                );
             case 404:
-                throw new \Exception(sprintf("Server return %s error code. Invalid resource: Invalid resource specified or resource not found", $this->response->getStatusCode()));
-                return false;
-                break;
+                throw ApiException::create(
+                    sprintf("Server return %s error code. Invalid resource: Invalid resource specified or resource not found", $this->response->getStatusCode()),
+                    $statusCode,
+                    $this->response->getBody(true)
+                );
             default:
-                throw new \Exception(sprintf("Server return %s error code.Server error: An error on the server prohibited a successful response; please contact support. %s", $this->response->getStatusCode(), $this->response->getBody(true)));
-                return false;
-                break;
+                throw ApiException::create(
+                    sprintf("Server return %s error code.Server error: An error on the server prohibited a successful response; please contact support. %s", $this->response->getStatusCode(), $this->response->getBody(true)),
+                    $statusCode,
+                    $this->response->getBody(true)
+                );
         }
 
     }

src/Stackla/Exception/ApiError.php

@@ -0,0 +1,75 @@
+<?php
+
+namespace Stackla\Exception;
+
+class ApiError
+{
+    /**
+     * @var string
+     */
+    protected $message;
+
+    /**
+     * @var int
+     */
+    protected $code;
+
+    /**
+     * @var string
+     */
+    protected $messageId;
+
+    /**
+     * @var int
+     */
+    protected $errorCode;
+
+    /**
+     * @param string $message
+     * @param int $code
+     * @param string $messageId
+     * @param int $errorCode
+     */
+    public function __construct($message, $code, $messageId, $errorCode)
+    {
+        $this->message = $message;
+        $this->code = $code;
+        $this->messageId = $messageId;
+        $this->errorCode = $errorCode;
+    }
+
+    /**
+     * @return string
+     */
+    public function getMessage()
+    {
+        return $this->message;
+    }
+
+    /**
+     * @deprecated Please use getErrorCode() instead
+     * @see getErrorCode()
+     * @return int
+     */
+    public function getCode()
+    {
+        return $this->code;
+    }
+
+    /**
+     * @return string
+     */
+    public function getMessageId()
+    {
+        return $this->messageId;
+    }
+
+    /**
+     * @return int
+     */
+    public function getErrorCode()
+    {
+        return $this->errorCode;
+    }
+
+}

src/Stackla/Exception/ApiException.php

@@ -0,0 +1,118 @@
+<?php
+
+namespace Stackla\Exception;
+
+use Exception;
+
+class ApiException extends Exception
+{
+
+    /**
+     * @var int
+     */
+    protected $httpStatusCode;
+
+    /**
+     * @var string
+     */
+    protected $httpResponseBody;
+
+    /**
+     * @var ApiError[]
+     */
+    protected $_errors;
+
+    public static function create($message, $httpStatusCode, $httpResponseBody, Exception $previous = null)
+    {
+        $exception = new static($message, 0, $previous);
+        $exception->httpStatusCode = $httpStatusCode;
+        $exception->httpResponseBody = $httpResponseBody;
+        return $exception;
+    }
+
+    /**
+     * @return int
+     */
+    public function getHttpStatusCode()
+    {
+        return $this->httpStatusCode;
+    }
+
+    /**
+     * @return string
+     */
+    public function getHttpResponseBody()
+    {
+        return $this->httpResponseBody;
+    }
+
+    /**
+     * @return ApiError[]
+     */
+    public function getErrors()
+    {
+        if (!is_array($this->_errors)) {
+            $errors = array();
+            $json = $this->getHttpResponseBody();
+            $response = json_decode($json, true);
+            if (json_last_error() === JSON_ERROR_NONE) {
+                $errors = $this->ifx($response, 'errors');
+                if (is_array($errors)) {
+                    foreach ($errors as $error) {
+                        if (is_array($error)) {
+                            $errors[] = new ApiError(
+                                (string)$this->ifx($error, 'message'),
+                                (string)$this->ifx($error, 'code'),
+                                (string)$this->ifx($error, 'message_id'),
+                                (int)$this->ifx($error, 'error_code')
+                            );
+                        }
+                    }
+                }
+            }
+            $this->_errors = $errors;
+        }
+        return $this->_errors;
+    }
+
+    /**
+     * @param int $errorCode
+     * @return bool
+     */
+    public function containsErrorByErrorCode($errorCode)
+    {
+        $errors = $this->getErrors();
+        foreach ($errors as $error) {
+            if ($error->getErrorCode() === $errorCode) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * @param string $messageId
+     * @return bool
+     */
+    public function containsErrorByMessageId($messageId)
+    {
+        $errors = $this->getErrors();
+        foreach ($errors as $error) {
+            if ($error->getMessageId() === $messageId) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    final protected function ifx($arr, $key, $default = null)
+    {
+        if (!is_array($arr)) {
+            return $default;
+        } elseif (array_key_exists($key, $arr)) {
+            return $arr[$key];
+        } else {
+            return $default;
+        }
+    }
+}