Merge branch '2.x' into develop

Author: lindyhopchris

CHANGELOG.md

@@ -22,6 +22,16 @@ for the soft delete attribute now defaults to the camel-case version of the mode
 column `deleted_at` previously defaulted to the JSON API field `deleted-at`, whereas now it will
 default to `deletedAt`. To continue to use dash-case, set the `softDeleteField` property on your adapter.
 
+## [2.1.0] - 2020-09-04
+
+### 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,7 +11,7 @@ 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.
 
@@ -85,8 +85,8 @@ 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\Error;
+use CloudCreativity\LaravelJsonApi\Exceptions\JsonApiException;
 
 try {
     dispatchNow(new ChargeCard($token));
@@ -97,12 +97,24 @@ try {
         '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);

phpunit.xml

@@ -1,7 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<phpunit backupGlobals="false"
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         backupGlobals="false"
          backupStaticAttributes="false"
-         beStrictAboutTestsThatDoNotTestAnything="false"
+         beStrictAboutTestsThatDoNotTestAnything="true"
          bootstrap="vendor/autoload.php"
          colors="true"
          convertErrorsToExceptions="true"
@@ -11,24 +12,25 @@
          stopOnError="false"
          stopOnFailure="false"
          verbose="true"
+         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd"
 >
-    <testsuites>
-        <testsuite name="Unit">
-            <directory suffix="Test.php">./tests/lib/Unit/</directory>
-        </testsuite>
-        <testsuite name="Integration">
-            <directory suffix="Test.php">./tests/lib/Integration/</directory>
-        </testsuite>
-        <testsuite name="Acceptance">
-            <directory suffix="Test.php">./tests/dummy/tests/</directory>
-        </testsuite>
-    </testsuites>
-    <filter>
-        <whitelist>
-            <directory suffix=".php">src/</directory>
-        </whitelist>
-    </filter>
-    <php>
-        <env name="APP_KEY" value="base64:BMfTqJC1cFk6A/jTPsjQgC+cROx7TDaEeGIAat6CuqY="/>
-    </php>
+  <coverage>
+    <include>
+      <directory suffix=".php">src/</directory>
+    </include>
+  </coverage>
+  <testsuites>
+    <testsuite name="Unit">
+      <directory suffix="Test.php">./tests/lib/Unit/</directory>
+    </testsuite>
+    <testsuite name="Integration">
+      <directory suffix="Test.php">./tests/lib/Integration/</directory>
+    </testsuite>
+    <testsuite name="Acceptance">
+      <directory suffix="Test.php">./tests/dummy/tests/</directory>
+    </testsuite>
+  </testsuites>
+  <php>
+    <env name="APP_KEY" value="base64:BMfTqJC1cFk6A/jTPsjQgC+cROx7TDaEeGIAat6CuqY="/>
+  </php>
 </phpunit>

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.");