[Feature] Add support JSON Exception class

Closes #538

Author: lindyhopchris

CHANGELOG.md

@@ -2,6 +2,16 @@
 All notable changes to this project will be documented in this file. This project adheres to
 [Semantic Versioning](http://semver.org/) and [this changelog format](http://keepachangelog.com/).
 
+## Unreleased
+
+### Added
+- [#538](https://github.com/cloudcreativity/laravel-json-api/issues/538)
+New JSON API exception class that accepts the new error objects from this package.
+It is recommended that you use `CloudCreativity\LaravelJsonApi\Exceptions\JsonApiException`
+combined with the `CloudCreativity\LaravelJsonApi\Document\Error\Error`. It is not
+recommended to use the `Neomerx\JsonApi\Exceptions\JsonApiException` class as support
+for this exception class will be removed in a future version.
+
 ## [2.0.0] - 2020-06-17
 
 ### Added

docs/features/errors.md

@@ -11,16 +11,16 @@ how to return your own error responses.
 
 ## Creating Error Objects
 
-Error objects can be constructed from array key/value pairs using the static `create` method on
+Error objects can be constructed from array key/value pairs using the static `fromArray` method on
 the package's error class. All the keys described in the specification's
 [error objects](http://jsonapi.org/format/#error-objects) chapter are supported.
 
 For example:
 
 ```php
-use CloudCreativity\LaravelJsonApi\Document\Error;
+use CloudCreativity\LaravelJsonApi\Document\Error\Error;
 
-$error = Error::create([
+$error = Error::fromArray([
     'id' => '91053382-7c00-45eb-bdcc-8359d03debbb',
     'status' => '500',
     'code' => 'unexpected',
@@ -40,15 +40,15 @@ The `JsonApiController` has a responses factory that can create error responses.
 to return an error response in a controller hook, as demonstrated in the following example:
 
 ```php
-use CloudCreativity\LaravelJsonApi\Document\Error;
+use CloudCreativity\LaravelJsonApi\Document\Error\Error;
 
 class PaymentController extends JsonApiController
 {
 
     protected function creating()
     {
         if (/** some condition */) {
-            return $this->reply()->errors(Error::create([
+            return $this->reply()->errors(Error::fromArray([
                 'title' => 'Payment Required',
                 'detail' => 'Your card has expired.',
                 'status' => '402',
@@ -84,24 +84,36 @@ It is also possible to throw a `JsonApiException` from anywhere in your code. Th
 to a JSON API response. For example:
 
 ```php
-use Neomerx\JsonApi\Exceptions\JsonApiException;
-use CloudCreativity\LaravelJsonApi\Document\Error;
+use CloudCreativity\LaravelJsonApi\Document\Error\Error;
+use CloudCreativity\LaravelJsonApi\Exceptions\JsonApiException;
 
 try {
     dispatchNow(new ChargeCard($token));
 } catch (\App\PaymentException $ex) {
-    $error = Error::create([
+    $error = Error::fromArray([
         'title' => 'Payment Required',
         'detail' => $ex->getMessage(),
         'status' => '402',
     ]);
 
-    throw new JsonApiException($error, 402, $ex);
+    throw new JsonApiException($error, $ex);
 }
 ```
 
 The JSON API exception takes three arguments:
 
 - An error object or an array of error objects.
-- The HTTP status code.
-- The previous exception.
+- The previous exception (optional)
+- Additional headers for the response (optional).
+
+You can also fluently construct a JSON API exception with headers:
+
+```php
+use CloudCreativity\LaravelJsonApi\Document\Error\Error;
+use CloudCreativity\LaravelJsonApi\Exceptions\JsonApiException;
+
+throw JsonApiException::make(Error::fromArray([
+    'status' => '418',
+    'title' => "I'm a Teapot"
+]))->withHeaders(['X-Foo' => 'Bar']);
+```

docs/installation.md

@@ -78,9 +78,9 @@ modify your `render()` method as follows:
 namespace App\Exceptions;
 
 use CloudCreativity\LaravelJsonApi\Exceptions\HandlesErrors;
-use Exception;
 use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
 use Neomerx\JsonApi\Exceptions\JsonApiException;
+use Throwable;
 
 class Handler extends ExceptionHandler
 {
@@ -94,7 +94,7 @@ class Handler extends ExceptionHandler
 
 	// ...
 
-  public function render($request, Exception $e)
+  public function render($request, Throwable $e)
   {
     if ($this->isJsonApi($request, $e)) {
       return $this->renderJsonApi($request, $e);
@@ -103,7 +103,7 @@ class Handler extends ExceptionHandler
     // do standard exception rendering here...
   }
 
-  protected function prepareException(Exception $e)
+  protected function prepareException(Throwable $e)
   {
       if ($e instanceof JsonApiException) {
         return $this->prepareJsonApiException($e);

src/Document/Error/Errors.php

@@ -30,6 +30,28 @@ class Errors implements DocumentInterface, IteratorAggregate
      */
     private $errors;
 
+    /**
+     * @var array
+     */
+    private $headers = [];
+
+    /**
+     * @param Errors|Error $value
+     * @return static
+     */
+    public static function cast($value): self
+    {
+        if ($value instanceof self) {
+            return $value;
+        }
+
+        if ($value instanceof Error) {
+            return new self($value);
+        }
+
+        throw new \UnexpectedValueException('Expecting an errors collection or an error object.');
+    }
+
     /**
      * Errors constructor.
      *
@@ -69,6 +91,17 @@ public function getStatus(): ?int
         return $only4xx ? Response::HTTP_BAD_REQUEST : Response::HTTP_INTERNAL_SERVER_ERROR;
     }
 
+    /**
+     * @param array $headers
+     * @return $this
+     */
+    public function withHeaders(array $headers): self
+    {
+        $this->headers = $headers;
+
+        return $this;
+    }
+
     /**
      * @inheritDoc
      */
@@ -99,12 +132,13 @@ public function jsonSerialize()
 
     /**
      * @inheritDoc
-     * @todo pass through headers.
      */
     public function toResponse($request)
     {
         return json_api()->response()->errors(
-            $this->errors
+            $this->errors,
+            null,
+            $this->headers
         );
     }
 

src/Exceptions/JsonApiException.php

@@ -0,0 +1,105 @@
+<?php
+/**
+ * Copyright 2020 Cloud Creativity Limited
+ *
+ * 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.
+ */
+
+declare(strict_types=1);
+
+namespace CloudCreativity\LaravelJsonApi\Exceptions;
+
+use CloudCreativity\LaravelJsonApi\Document\Error\Error;
+use CloudCreativity\LaravelJsonApi\Document\Error\Errors;
+use Exception;
+use Illuminate\Contracts\Support\Responsable;
+use Symfony\Component\HttpKernel\Exception\HttpExceptionInterface;
+use Throwable;
+
+class JsonApiException extends Exception implements HttpExceptionInterface, Responsable
+{
+
+    /**
+     * @var Errors
+     */
+    private $errors;
+
+    /**
+     * @var array
+     */
+    private $headers;
+
+    /**
+     * Fluent constructor.
+     *
+     * @param Errors|Error $errors
+     * @param Throwable|null $previous
+     * @return static
+     */
+    public static function make($errors, Throwable $previous = null): self
+    {
+        return new self($errors, $previous);
+    }
+
+    /**
+     * JsonApiException constructor.
+     *
+     * @param Errors|Error $errors
+     * @param Throwable|null $previous
+     * @param array $headers
+     */
+    public function __construct($errors, Throwable $previous = null, array $headers = [])
+    {
+        parent::__construct('JSON API error', 0, $previous);
+        $this->errors = Errors::cast($errors);
+        $this->headers = $headers;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getStatusCode()
+    {
+        return $this->errors->getStatus();
+    }
+
+    /**
+     * @param array $headers
+     * @return $this
+     */
+    public function withHeaders(array $headers): self
+    {
+        $this->headers = $headers;
+
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getHeaders()
+    {
+        return $this->headers;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function toResponse($request)
+    {
+        return $this->errors
+            ->withHeaders($this->headers)
+            ->toResponse($request);
+    }
+
+}

tests/lib/Integration/ErrorsTest.php

@@ -18,8 +18,10 @@
 namespace CloudCreativity\LaravelJsonApi\Tests\Integration;
 
 use Carbon\Carbon;
+use CloudCreativity\LaravelJsonApi\Document\Error\Error;
 use CloudCreativity\LaravelJsonApi\Exceptions\DocumentRequiredException;
 use CloudCreativity\LaravelJsonApi\Exceptions\InvalidJsonException;
+use CloudCreativity\LaravelJsonApi\Exceptions\JsonApiException;
 use CloudCreativity\LaravelJsonApi\Exceptions\ResourceNotFoundException;
 use DummyApp\Post;
 use Illuminate\Contracts\Validation\Validator;
@@ -28,8 +30,8 @@
 use Illuminate\Support\Facades\Route;
 use Illuminate\Support\MessageBag;
 use Illuminate\Validation\ValidationException;
-use Neomerx\JsonApi\Document\Error;
-use Neomerx\JsonApi\Exceptions\JsonApiException;
+use Neomerx\JsonApi\Document\Error as NeomerxError;
+use Neomerx\JsonApi\Exceptions\JsonApiException as NeomerxException;
 use Symfony\Component\HttpKernel\Exception\HttpException;
 
 class ErrorsTest extends TestCase
@@ -239,19 +241,51 @@ public function testAcceptAny()
      *
      * @see https://github.com/cloudcreativity/laravel-json-api/issues/329
      */
-    public function testUnexpectedJsonApiException()
+    public function testNeomerxJsonApiException()
     {
         config()->set('app.debug', true);
 
         Route::get('/test', function () {
-            throw new JsonApiException(new Error(null, null, 422, null, null, 'My foobar error message.'), 418);
+            throw new NeomerxException(new NeomerxError(
+                null,
+                null,
+                422,
+                null,
+                null,
+                'My foobar error message.'
+            ), 418);
         });
 
         $this->get('/test', ['Accept' => '*/*'])
             ->assertStatus(418)
             ->assertSee('My foobar error message.');
     }
 
+    public function testJsonApiException(): void
+    {
+        Route::get('/test', function () {
+            throw JsonApiException::make(Error::fromArray([
+                'status' => '418',
+                'detail' => "Hello, I'm a teapot.",
+            ]))->withHeaders(['X-Foo' => 'Bar']);
+        });
+
+        $expected = [
+            'errors' => [
+                [
+                    'status' => '418',
+                    'detail' => "Hello, I'm a teapot.",
+                ],
+            ],
+        ];
+
+        $this->get('/test')
+            ->assertStatus(418)
+            ->assertHeader('Content-Type', 'application/vnd.api+json')
+            ->assertHeader('X-Foo', 'Bar')
+            ->assertExactJson($expected);
+    }
+
     public function testMaintenanceMode()
     {
         $ex = new MaintenanceModeException(Carbon::now()->getTimestamp(), 60, "We'll be back soon.");