[Feature] Support countable relationships

Adds a query parameter that is used by the Eloquent implementation
to load relationship counts for to-many relations, and adds the
count value to the relationship's meta.

Closes #18

Author: lindyhopchris

CHANGELOG.md

@@ -3,6 +3,24 @@
 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
+
+- [#18](https://github.com/laravel-json-api/laravel/issues/18) Added a `withCount` query parameter. For Eloquent
+  resources, this allows a client to request the relationship count for the primary data's relationships. Refer to
+  documentation for implementation details.
+- There is now a `Core\Reponses\RelatedResponse` class for returning the result for a related resources endpoint. For
+  example, the `/api/v1/posts/1/comments` endpoint. Previously the `DataResponse` class was used. While this class can
+  still be used, the new `RelatedResponse` class merges relationship meta into the top-level `meta` member of the
+  response document. For *to-many* relationships that are countable, this will mean the top-level `meta` member will
+  contain the count of the relationship.
+
+### Fixed
+
+- Relationship endpoints that return resource identifiers now correctly include page meta in the top-level meta member
+  of the document, if the results are paginated. Previously the page meta was incorrectly omitted.
+
 ## [1.0.0-alpha.5] - 2021-03-12
 
 ### Added

composer.json

@@ -25,12 +25,12 @@
     "require": {
         "php": "^7.4|^8.0",
         "ext-json": "*",
-        "laravel-json-api/core": "^1.0.0-alpha.5",
-        "laravel-json-api/eloquent": "^1.0.0-alpha.5",
-        "laravel-json-api/encoder-neomerx": "^1.0.0-alpha.4",
-        "laravel-json-api/exceptions": "^1.0.0-alpha.2",
-        "laravel-json-api/spec": "^1.0.0-alpha.4",
-        "laravel-json-api/validation": "^1.0.0-alpha.5",
+        "laravel-json-api/core": "^1.0.0-beta.1",
+        "laravel-json-api/eloquent": "^1.0.0-beta.1",
+        "laravel-json-api/encoder-neomerx": "^1.0.0-beta.1",
+        "laravel-json-api/exceptions": "^1.0.0-beta.1",
+        "laravel-json-api/spec": "^1.0.0-beta.1",
+        "laravel-json-api/validation": "^1.0.0-beta.1",
         "laravel/framework": "^8.0"
     },
     "require-dev": {

src/Http/Controllers/Actions/FetchRelated.php

@@ -23,7 +23,7 @@
 use Illuminate\Http\Response;
 use LaravelJsonApi\Contracts\Routing\Route;
 use LaravelJsonApi\Contracts\Store\Store as StoreContract;
-use LaravelJsonApi\Core\Responses\DataResponse;
+use LaravelJsonApi\Core\Responses\RelatedResponse;
 use LaravelJsonApi\Core\Support\Str;
 use LaravelJsonApi\Laravel\Http\Requests\ResourceQuery;
 
@@ -76,6 +76,10 @@ public function showRelated(Route $route, StoreContract $store)
             $response = $this->{$hook}($model, $data, $request);
         }
 
-        return $response ?: new DataResponse($data);
+        return $response ?: new RelatedResponse(
+            $model,
+            $relation->name(),
+            $data,
+        );
     }
 }

src/Http/Requests/AnonymousCollectionQuery.php

@@ -17,6 +17,7 @@
 
 namespace LaravelJsonApi\Laravel\Http\Requests;
 
+use LaravelJsonApi\Core\Query\Custom\ExtendedQueryParameters;
 use LaravelJsonApi\Validation\Rule as JsonApiRule;
 
 class AnonymousCollectionQuery extends ResourceQuery
@@ -55,6 +56,11 @@ public function rules()
                 'string',
                 JsonApiRule::sort(),
             ],
+            ExtendedQueryParameters::withCount() => [
+                'nullable',
+                'string',
+                JsonApiRule::countable(),
+            ],
         ];
     }
 }

src/Http/Requests/AnonymousQuery.php

@@ -17,6 +17,7 @@
 
 namespace LaravelJsonApi\Laravel\Http\Requests;
 
+use LaravelJsonApi\Core\Query\Custom\ExtendedQueryParameters;
 use LaravelJsonApi\Validation\Rule as JsonApiRule;
 
 class AnonymousQuery extends ResourceQuery
@@ -47,6 +48,11 @@ public function rules()
             ],
             'page' => JsonApiRule::notSupported(),
             'sort' => JsonApiRule::notSupported(),
+            ExtendedQueryParameters::withCount() => [
+                'nullable',
+                'string',
+                JsonApiRule::countable(),
+            ],
         ];
     }
 }

src/Http/Requests/ResourceQuery.php

@@ -25,6 +25,7 @@
 use LaravelJsonApi\Contracts\Query\QueryParameters;
 use LaravelJsonApi\Core\Exceptions\JsonApiException;
 use LaravelJsonApi\Core\Query\FieldSets;
+use LaravelJsonApi\Core\Query\FilterParameters;
 use LaravelJsonApi\Core\Query\IncludePaths;
 use LaravelJsonApi\Core\Query\SortFields;
 use Symfony\Component\HttpKernel\Exception\HttpException;
@@ -196,17 +197,31 @@ public function page(): ?array
     /**
      * @inheritDoc
      */
-    public function filter(): ?array
+    public function filter(): ?FilterParameters
     {
         $data = $this->validated();
 
         if (array_key_exists('filter', $data)) {
-            return $data['filter'];
+            return FilterParameters::fromArray($data['filter'] ?? []);
         }
 
         return null;
     }
 
+    /**
+     * @inheritDoc
+     */
+    public function unrecognisedParameters(): array
+    {
+        return collect($this->validated())->forget([
+            'include',
+            'fields',
+            'sort',
+            'page',
+            'filter',
+        ])->all();
+    }
+
     /**
      * @return void
      */

src/LaravelJsonApi.php

@@ -20,7 +20,10 @@
 namespace LaravelJsonApi\Laravel;
 
 use Illuminate\Support\Arr;
+use InvalidArgumentException;
 use LaravelJsonApi\Core\Auth\AuthorizerResolver;
+use LaravelJsonApi\Core\Query\Custom\ExtendedQueryParameters;
+use LaravelJsonApi\Eloquent\Resources\Relation;
 
 final class LaravelJsonApi
 {
@@ -53,4 +56,36 @@ public static function defaultAuthorizer(string $authorizerClass): self
 
         return new self();
     }
+
+    /**
+     * Set the query parameter name for the countable implementation.
+     *
+     * @param string $parameter
+     * @return static
+     */
+    public static function withCountQueryParameter(string $parameter): self
+    {
+        if (!empty($parameter)) {
+            ExtendedQueryParameters::withCount($parameter);
+            return new self();
+        }
+
+        throw new InvalidArgumentException('Expecting a non-empty string for the countable query parameter.');
+    }
+
+    /**
+     * Set the relationship meta key for the countable implementation.
+     *
+     * @param string $key
+     * @return static
+     */
+    public static function withCountMetaKey(string $key): self
+    {
+        if (!empty($key)) {
+            Relation::withCount($key);
+            return new self();
+        }
+
+        throw new InvalidArgumentException('Expecting a non-empty string for the countable meta key.');
+    }
 }

tests/dummy/app/JsonApi/V1/Comments/CommentSchema.php

@@ -69,7 +69,7 @@ public function filters(): array
      */
     public function pagination(): ?Paginator
     {
-        return PagePagination::make()->withoutNestedMeta();
+        return PagePagination::make();
     }
 
 }

tests/dummy/app/JsonApi/V1/Media/MediaCollectionQuery.php

@@ -56,7 +56,12 @@ public function rules(): array
             'sort' => [
                 'nullable',
                 'string',
-                JsonApiRule::notSupported(),
+                JsonApiRule::sort(['id']),
+            ],
+            'withCount' => [
+                'nullable',
+                'string',
+                JsonApiRule::countableForPolymorph(),
             ],
         ];
     }

tests/dummy/app/JsonApi/V1/Posts/PostCollectionQuery.php

@@ -58,6 +58,11 @@ public function rules(): array
                 'string',
                 JsonApiRule::sort(),
             ],
+            'withCount' => [
+                'nullable',
+                'string',
+                JsonApiRule::countable(),
+            ],
         ];
     }
 }