Add Error and Error source class, throw ResponseException on non 20x response

nohponex · nohponex · commit 7b614ddc535a · 2016-03-31T00:54:21.000+03:00
diff --git a/src/Client.php b/src/Client.php
@@ -16,8 +16,9 @@
  */
 namespace Phramework\JSONAPI\Client;
 
-use Phramework\JSONAPI\Client\Exceptions\Exception;
+use Phramework\JSONAPI\Client\Exceptions\ResponseException;
 use Phramework\JSONAPI\Client\Response\Collection;
+use Phramework\JSONAPI\Client\Response\Errors;
 use Phramework\JSONAPI\Client\Response\Resource;
 
 /**
@@ -120,8 +121,9 @@ protected function prepareHeaders(\stdClass $additional = null)
      * @param IncludeRelationship|null $include Include directive
      * @param \stdClass|null           $additionalHeaders Will override global
      *     headers
-     * @param \string[]                ...$additional Additional url
+     * @param \string[]                ...$additional Additional url parts
      * @return Collection
+     * @throws ResponseException When response code is not on of 200, 201, 202, 203 or 204
      * @example
      * ```php
      * $users = Users::get(
@@ -150,7 +152,11 @@ protected function prepareHeaders(\stdClass $additional = null)
      *    new Fields((object) [
      *        'user' => ['name', 'email']
      *    ]),
-     *    new IncludeRelationship('project', 'group')
+     *    new IncludeRelationship('project', 'group'),
+     *    (object) [
+     *        'Accept' => 'application/vnd.api+json'
+     *    ],
+     *    '&token=1234'
      * );
      * ```
      */
@@ -237,7 +243,7 @@ public static function get(
      *     headers
      * @param \string[]                ...$additional Additional url
      * @return Resource
-     * @throws Exception
+     * @throws ResponseException When response code is not on of 200, 201, 202, 203 or 204
      * @example
      * ```php
      * $user = User::getById(
@@ -302,33 +308,64 @@ public static function getById(
 
     public static function post(
         \stdClass $attributes = null,
-        \stdClass $relationships = null
+        \stdClass $relationships = null,
+        \stdClass $additionalHeaders = null,
+        string ...$additional
     ) {
 
     }
 
     public static function patch(
         string $id,
         \stdClass $attributes = null,
-        \stdClass $relationships = null
+        \stdClass $relationships = null,
+        \stdClass $additionalHeaders = null,
+        string ...$additional
     ) {
 
     }
 
     public static function delete(
-        string $id
+        string $id,
+        \stdClass $additionalHeaders = null,
+        string ...$additional
     ) {
 
     }
 
     /**
-     * Perform an cURL request
+     * Perform an cURL request to a JSON API web service over HTTP
+     * @param string         $url Request url
+     * @param string         $method Request HTTP method
+     * @param \stdClass|null $headers Request headers
+     * @param \stdClass|null $data Request body
+     * @return array which contains
+     * - $responseStatusCode
+     * - $responseHeaders
+     * - $responseBody (JSON encoded)
+     * @throws ResponseException When response code is not on of 200, 201, 202, 203 or 204
+     * @throws \Exception
+     * @example
+     * ```php
+     * list(
+     *     $responseStatusCode,
+     *     $responseHeaders,
+     *     $responseBody
+     * ) = Client::request(
+     *     'http://myapi.com/user/',
+     *     Client::METHOD_GET,
+     *     (object) [
+     *         'Content-Type' => 'application/vnd.api+json',
+     *         'Accept' => 'application/vnd.api+json'
+     *     ]
+     * );
+     * ```
      */
     public static function request(
         string $url,
         string $method = self::METHOD_GET,
         \stdClass $headers = null,
-        $data = null,
+        \stdClass $data = null,
         $flags = self::REQUEST_EMPTY_FLAG,
         //$accept = 'application/json',
         $encoding = null
@@ -417,7 +454,7 @@ public static function request(
                 curl_setopt($handle, CURLOPT_CUSTOMREQUEST, self::METHOD_DELETE);
                 break;
             default:
-                throw new Exception('Unsupported method');
+                throw new \Exception('Unsupported method');
         }
         
         //Get response
@@ -442,27 +479,23 @@ public static function request(
 
         curl_close($handle);
 
+        //Throw exception on response failure
+        if (!in_array($responseStatusCode, [200, 201, 202, 203, 204])) {
+            throw new ResponseException(
+                (new Errors())
+                    ->parse(json_decode($responseBody))
+                    ->setHeaders($responseHeaders)
+                    ->setStatusCode($responseStatusCode)
+            );
+        }
+
+        //Return the data of response
         return [
             $responseStatusCode,
             $responseHeaders,
             json_decode($responseBody)
         ];
 
-       /* if (!$response) {
-            throw new Exception('Error: ' . curl_error($handle));
-        }*/
-
-       /* //Throw exception on response failure
-        if (!in_array($code, array(200, 201, 202))) { // OK, Created, Accepted
-            $decoded = json_decode($response, true);
-            throw new Exception($decoded['error'], $code);
-        }*/
-
-        curl_close($handle);
-        //Return the data of response
-
-        return $response;
-
         /*return (
 
             $accept == 'application/json' ? json_decode($response, true) : $response );*/
diff --git a/src/Error.php b/src/Error.php
@@ -0,0 +1,79 @@
+<?php
+/**
+ * Copyright 2016 Xenofon Spafaridis
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+namespace Phramework\JSONAPI\Client;
+
+/**
+ * Error meta-class helpful for documentation and autocomplete
+ * @author Xenofon Spafaridis <nohponex@gmail.com>
+ * @since 0.0.0
+ * @link http://jsonapi.org/format/#error-objects
+ */
+class Error
+{
+    /**
+     * The HTTP status code applicable to this problem, expressed as a
+     * string value
+     * @var int
+     */
+    public $status;
+
+    /**
+     * A short, human-readable summary of the problem
+     * @var string
+     */
+    public $title;
+
+    /**
+     * A human-readable explanation specific to this occurrence of the problem
+     * @var string
+     */
+    public $detail;
+
+    /**
+     * A unique identifier for this particular occurrence of the problem
+     * @var string
+     */
+    public $id;
+
+    /**
+     * An object containing references to the source of the error
+     * **Note** usually it's not set
+     * @var ErrorSource
+     */
+    public $source;
+
+    /**
+     * A links object
+     * **Note** usually it's not set
+     * @var \stdClass
+     */
+    public $links;
+
+    /**
+     * A meta object containing non-standard meta-information about the error
+     * **Note** usually it's not set
+     * @var \stdClass
+     */
+    public $meta;
+
+    /**
+     * An application-specific error code, expressed as a string value.
+     * **Note** usually it's not set
+     * @var string
+     */
+    public $code;
+}
diff --git a/src/ErrorSource.php b/src/ErrorSource.php
@@ -0,0 +1,40 @@
+<?php
+/**
+ * Copyright 2016 Xenofon Spafaridis
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+namespace Phramework\JSONAPI\Client;
+
+/**
+ * Error source meta-class helpful for documentation and autocomplete
+ * @author Xenofon Spafaridis <nohponex@gmail.com>
+ * @since 0.0.0
+ * @link http://jsonapi.org/format/#error-objects
+ */
+class ErrorSource
+{
+    /**
+     * A a JSON Pointer [RFC6901] to the associated entity in the request
+     * document [e.g. "/data" for a primary data object, or
+     * "/data/attributes/title" for a specific attribute]
+     * @var string
+     */
+    public $pointer;
+
+    /**
+     * A string indicating which URI query parameter caused the error
+     * @var string
+     */
+    public $parameter;
+}
diff --git a/src/Exceptions/ResponseException.php b/src/Exceptions/ResponseException.php
@@ -0,0 +1,59 @@
+<?php
+/**
+ * Copyright 2016 Xenofon Spafaridis
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+namespace Phramework\JSONAPI\Client\Exceptions;
+
+use Phramework\JSONAPI\Client\Response\Errors;
+
+/**
+ * @author Xenofon Spafaridis <nohponex@gmail.com>
+ * @since 0.0.0
+ */
+class ResponseException extends \Exception
+{
+    /**
+     * @var Errors
+     */
+    private $response;
+
+    /**
+     * @param Errors $response
+     */
+    public function __construct(Errors $response)
+    {
+        $this->response = $response;
+    }
+
+
+    /**
+     * @return Errors
+     */
+    public function getResponse()
+    {
+        return $this->response;
+    }
+
+    /**
+     * @param Errors $response
+     * @return $this
+     */
+    public function setResponse($response)
+    {
+        $this->response = $response;
+
+        return $this;
+    }
+}
diff --git a/src/Response/Collection.php b/src/Response/Collection.php
@@ -25,12 +25,16 @@
 class Collection extends Response
 {
     /**
+     * An array of resource objects, an array of resource identifier objects,
+     * or an empty array
      * @var ResourceObject[]
      */
-    public $data;
+    public $data = [];
 
     /**
+     * Compound Documents
      * @var ResourceObject[]
+     * @link http://jsonapi.org/format/#document-compound-documents
      */
     public $included;
 }
diff --git a/src/Response/Errors.php b/src/Response/Errors.php
@@ -16,15 +16,17 @@
  */
 namespace Phramework\JSONAPI\Client\Response;
 
+use Phramework\JSONAPI\Client\Error;
+
 /**
  * @author Xenofon Spafaridis <nohponex@gmail.com>
  * @since 0.0.0
+ * @link http://jsonapi.org/format/#error-objects
  */
 class Errors extends Response
 {
     /**
-     * @var \stdClass[]
-     * @todo add errors object
+     * @var Error[]
      */
     public $errors;
 }
diff --git a/src/Response/Resource.php b/src/Response/Resource.php
diff --git a/tests/APP/NotFound.php b/tests/APP/NotFound.php
diff --git a/tests/src/ClientTest.php b/tests/src/ClientTest.php
