Merge branch 'release/1.1.0'

Author: lindyhopchris

CHANGELOG.md

@@ -2,6 +2,26 @@
 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/).
 
+## [1.1.0] - 2019-04-12
+
+### Added
+- [#315](https://github.com/cloudcreativity/laravel-json-api/issues/315)
+Allow developers to use the exact JSON API field name as the relationship method name on their
+adapters, plus for default conversion of names in include paths. Although we recommend following
+the PSR1 standard of using camel case for method names, this does allow a developer to use snake
+case field names with snake case method names.
+- Exception handlers can now use the `parseJsonApiException()` helper method if they need to
+convert JSON API exceptions to HTTP exceptions. Refer to the [installation instructions](./docs/installation.md)
+for an example of how to do this on an exception handler.
+
+### Fixed
+- [#329](https://github.com/cloudcreativity/laravel-json-api/issues/329)
+Render JSON API error responses when a codec has matched, but the client has not explicitly
+asked for JSON API response (e.g. asked for `Accept: */*`).
+- [#313](https://github.com/cloudcreativity/laravel-json-api/issues/313)
+Ensure that the standard paging strategy uses the resource identifier so that pages have a
+[deterministic sort order](https://tighten.co/blog/a-cautionary-tale-of-nondeterministic-laravel-pagination).
+
 ## [1.0.1] - 2019-03-12
 
 ### Fixed

docs/fetching/pagination.md

@@ -327,16 +327,16 @@ means the most recently created model is the first in the list, and the oldest i
 column is not unique (there could be multiple rows created at the same time), it uses the resource id
 column as a secondary sort order, as the resource id must always be unique.
 
-To change the column that is used for the list order use the `withColumn` method. If you prefer your
-list to be in ascending order, use the `withAscending` method. For example:
+To change the column that is used for the list order use the `withQualifiedColumn` method. If you prefer
+your list to be in ascending order, use the `withAscending` method. For example:
 
 ```php
-$strategy->withColumn('published_at')->withAscending();
+$strategy->withQualfiedColumn('posts.published_at')->withAscending();
 ```
 
 > The Eloquent adapter will always set the secondary column for sort order to the same column that is
 being used for the resource ID. If you are using the cursor strategy in a custom adapter, you will
-need to set the unique column using the `withIdentifierColumn` method. Note that whatever you set the
+need to set the unique column using the `withQualifiedKeyName` method. Note that whatever you set the
 column to, this will mean the client needs to provide the value of that column for the `after` and
 `before` page parameters - so really it should always match whatever you are using for the resource ID.
 

docs/installation.md

@@ -71,7 +71,7 @@ add support for JSON API error rendering to your application's exception handler
 To do this, simply add the `CloudCreativity\LaravelJsonApi\Exceptions\HandlesErrors` trait to your handler and
 modify your `render()` method as follows:
 
-``` php
+```php
 namespace App\Exceptions;
 
 use CloudCreativity\LaravelJsonApi\Exceptions\HandlesErrors;
@@ -91,13 +91,22 @@ class Handler extends ExceptionHandler
 
 	// ...
 
-    public function render($request, Exception $e)
-    {
-      if ($this->isJsonApi($request, $e)) {
-        return $this->renderJsonApi($request, $e);
+  public function render($request, Exception $e)
+  {
+    if ($this->isJsonApi($request, $e)) {
+      return $this->renderJsonApi($request, $e);
+    }
+
+    // do standard exception rendering here...
+  }
+  
+  protected function prepareException(Exception $e)
+  {
+      if ($e instanceof JsonApiException) {
+        return $this->prepareJsonApiException($e);
       }
 
-      // do standard exception rendering here...
-    }
+      return parent::prepareException($e);
+  }
 }
 ```

src/Adapter/AbstractResourceAdapter.php

@@ -197,11 +197,32 @@ protected function isFillableRelation($field, $record)
     }
 
     /**
-     * @param $field
+     * Get the method name on this adapter for the supplied JSON API field.
+     *
+     * By default we expect the developer to be following the PSR1 standard,
+     * so the method name on the adapter should use camel case.
+     *
+     * However, some developers may prefer to use the actual JSON API field
+     * name. E.g. they could use `user_history` as the JSON API field name
+     * and the method name.
+     *
+     * Therefore we return the field name if it exactly exists on the adapter,
+     * otherwise we camelize it.
+     *
+     * A developer can use completely different logic by overloading this
+     * method.
+     *
+     * @param string $field
+     *      the JSON API field name.
      * @return string|null
+     *      the adapter's method name, or null if none is implemented.
      */
     protected function methodForRelation($field)
     {
+        if (method_exists($this, $field)) {
+            return $field;
+        }
+
         $method = Str::camelize($field);
 
         return method_exists($this, $method) ? $method : null;

src/Eloquent/AbstractAdapter.php

@@ -25,7 +25,6 @@
 use CloudCreativity\LaravelJsonApi\Contracts\Pagination\PagingStrategyInterface;
 use CloudCreativity\LaravelJsonApi\Document\ResourceObject;
 use CloudCreativity\LaravelJsonApi\Exceptions\RuntimeException;
-use CloudCreativity\LaravelJsonApi\Pagination\CursorStrategy;
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations;
@@ -431,9 +430,14 @@ protected function paginate($query, EncodingParametersInterface $parameters)
             throw new RuntimeException('Paging is not supported on adapter: ' . get_class($this));
         }
 
-        /** If using the cursor strategy, we need to set the key name for the cursor. */
-        if ($this->paging instanceof CursorStrategy) {
-            $this->paging->withIdentifierColumn($this->getKeyName());
+        /**
+         * Set the key name on the strategy, so it knows what column is being used
+         * for the resource's ID.
+         *
+         * @todo 2.0 add `withQualifiedKeyName` to the paging strategy interface.
+         */
+        if (method_exists($this->paging, 'withQualifiedKeyName')) {
+            $this->paging->withQualifiedKeyName($this->getQualifiedKeyName());
         }
 
         return $this->paging->paginate($query, $parameters);
@@ -622,7 +626,7 @@ private function guessRelation()
     {
         list($one, $two, $caller) = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 3);
 
-        return $caller['function'];
+        return $this->modelRelationForField($caller['function']);
     }
 
 }

src/Eloquent/Concerns/IncludesModels.php

@@ -79,6 +79,13 @@ trait IncludesModels
      */
     protected $includePaths = [];
 
+    /**
+     * Whether Eloquent relations are camel cased.
+     *
+     * @var bool
+     */
+    protected $camelCaseRelations = true;
+
     /**
      * Add eager loading to the query.
      *
@@ -145,7 +152,38 @@ protected function convertIncludePath($path)
         }
 
         return collect(explode('.', $path))->map(function ($segment) {
-            return Str::camelize($segment);
+            return $this->modelRelationForField($segment);
         })->implode('.');
     }
+
+    /**
+     * Convert a JSON API field name to an Eloquent model relation name.
+     *
+     * According to the PSR1 spec, method names on classes MUST be camel case.
+     * However, there seem to be some Laravel developers who snake case
+     * relationship methods on their models, so that the method name matches
+     * the snake case format of attributes (column values).
+     *
+     * The `$camelCaseRelations` property controls the behaviour of this
+     * conversion:
+     *
+     * - If `true`, a field name of `user-history` or `user_history` will
+     * expect the Eloquent model relation method to be `userHistory`.
+     * - If `false`, a field name of `user-history` or `user_history` will
+     * expect the Eloquent model relation method to be `user_history`. I.e.
+     * if PSR1 is not being followed, the best guess is that method names
+     * are snake case.
+     *
+     * If the developer has different conversion logic, they should overload
+     * this method and implement it themselves.
+     *
+     * @param string $field
+     *      the JSON API field name.
+     * @return string
+     *      the expected relation name on the Eloquent model.
+     */
+    protected function modelRelationForField($field)
+    {
+        return $this->camelCaseRelations ? Str::camelize($field) : Str::underscore($field);
+    }
 }

src/Exceptions/HandlesErrors.php

@@ -18,10 +18,15 @@
 
 namespace CloudCreativity\LaravelJsonApi\Exceptions;
 
+use CloudCreativity\LaravelJsonApi\Routing\Route;
+use CloudCreativity\LaravelJsonApi\Services\JsonApiService;
 use CloudCreativity\LaravelJsonApi\Utils\Helpers;
 use Exception;
 use Illuminate\Http\Request;
 use Illuminate\Http\Response;
+use Neomerx\JsonApi\Contracts\Document\ErrorInterface;
+use Neomerx\JsonApi\Exceptions\JsonApiException;
+use Symfony\Component\HttpKernel\Exception\HttpException;
 
 /**
  * Trait HandlesErrors
@@ -44,10 +49,19 @@ trait HandlesErrors
      */
     public function isJsonApi($request, Exception $e)
     {
-        return Helpers::wantsJsonApi($request);
+        if (Helpers::wantsJsonApi($request)) {
+            return true;
+        }
+
+        /** @var Route $route */
+        $route = app(JsonApiService::class)->currentRoute();
+
+        return $route->hasCodec() && $route->getCodec()->willEncode();
     }
 
     /**
+     * Render an exception as a JSON API error response.
+     *
      * @param Request $request
      * @param Exception $e
      * @return Response
@@ -57,4 +71,19 @@ public function renderJsonApi($request, Exception $e)
         return json_api()->response()->exception($e);
     }
 
+    /**
+     * Prepare JSON API exception for non-JSON API rendering.
+     *
+     * @param JsonApiException $ex
+     * @return HttpException
+     */
+    protected function prepareJsonApiException(JsonApiException $ex)
+    {
+        $error = collect($ex->getErrors())->map(function (ErrorInterface $err) {
+            return $err->getDetail() ?: $err->getTitle();
+        })->filter()->first();
+
+        return new HttpException($ex->getHttpCode(), $error, $ex);
+    }
+
 }

src/Pagination/CursorStrategy.php

@@ -161,6 +161,27 @@ public function withAscending()
      *
      * @param $column
      * @return $this
+     * @todo 2.0 pass qualified columns to the cursor builder.
+     */
+    public function withQualifiedColumn($column)
+    {
+        $parts = explode('.', $column);
+
+        if (!isset($parts[1])) {
+            throw new \InvalidArgumentException('Expecting a valid qualified column name.');
+        }
+
+        $this->withColumn($parts[1]);
+
+        return $this;
+    }
+
+    /**
+     * Set the cursor column.
+     *
+     * @param $column
+     * @return $this
+     * @deprecated 2.0 use `withQualifiedColumn` instead.
      */
     public function withColumn($column)
     {
@@ -169,11 +190,32 @@ public function withColumn($column)
         return $this;
     }
 
+    /**
+     * Set the column name for the resource's ID.
+     *
+     * @param string $keyName
+     * @return $this
+     * @todo 2.0 pass qualified key name to the cursor builder.
+     */
+    public function withQualifiedKeyName($keyName)
+    {
+        $parts = explode('.', $keyName);
+
+        if (!isset($parts[1])) {
+            throw new \InvalidArgumentException('Expecting a valid qualified column name.');
+        }
+
+        $this->withIdentifierColumn($parts[1]);
+
+        return $this;
+    }
+
     /**
      * Set the column for the before/after identifiers.
      *
      * @param string|null $column
      * @return $this
+     * @deprecated 2.0 use `withQualifiedKeyName` instead.
      */
     public function withIdentifierColumn($column)
     {
@@ -183,6 +225,8 @@ public function withIdentifierColumn($column)
     }
 
     /**
+     * Set the select columns for the query.
+     *
      * @param $cols
      * @return $this
      */