Merge branch 'release/1.0.0-beta.1' into main

Author: lindyhopchris

CHANGELOG.md

@@ -3,6 +3,39 @@
 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.0.0-beta.1] - 2021-03-30
+
+### 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.
+- [#55](https://github.com/laravel-json-api/laravel/pull/55) Encoding and decoding of resource IDs is now supported.
+  The `ID` field needs to implement the `LaravelJsonApi\Contracts\Schema\IdEncoder` interface for this to work.
+- [#41](https://github.com/laravel-json-api/laravel/issues/41) Hash IDs are now supported by installing the
+  `laravel-json-api/hashids` package and using the `HashId` field instead of the standard Eloquent `ID` field. Refer to
+  documentation for details.
+- [#30](https://github.com/laravel-json-api/laravel/issues/30) Non-Eloquent resources are no supported via the
+  `laravel-json-api/non-eloquent` package. 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.
+- The schema generator Artisan command now has a `--non-eloquent` option to generate a schema for a non-Eloquent
+  resource.
+
+### Changed
+
+- The `LaravelJsonApi::registerQuery()`, `LaravelJsonApi::registerCollectionQuery()` and
+  `LaravelJsonApi::registerRequest()` methods must now be used to register custom HTTP request classes for specified
+  resource types. Previously methods could be called on the `RequestResolver` classes, but these have now been removed.
+
+### 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

README.md

@@ -19,6 +19,11 @@ composer require laravel-json-api/laravel
 
 See our documentation for further installation instructions.
 
+## Example Application
+
+To view an example Laravel application that uses this package, see the
+[Dummy Application](https://github.com/laravel-json-api/laravel/tree/main/tests/dummy) within the tests folder.
+
 ## License
 
 Laravel JSON:API is open-sourced software licensed under the [Apache 2.0 License](./LICENSE).

composer.json

@@ -25,16 +25,17 @@
     "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": {
-        "laravel-json-api/testing": "^1.0.0-alpha.1",
+        "laravel-json-api/hashids": "^1.0.0-beta.1",
+        "laravel-json-api/testing": "^1.0.0-beta.1",
         "orchestra/testbench": "^6.9",
         "phpunit/phpunit": "^9.5"
     },

src/Console/MakeQuery.php

@@ -19,6 +19,7 @@
 
 namespace LaravelJsonApi\Laravel\Console;
 
+use LaravelJsonApi\Core\Query\Custom\ExtendedQueryParameters;
 use Symfony\Component\Console\Input\InputOption;
 
 class MakeQuery extends GeneratorCommand
@@ -82,6 +83,36 @@ protected function getClassType(): string
         return 'Query';
     }
 
+    /**
+     * @inheritDoc
+     */
+    protected function buildClass($name)
+    {
+        $stub = parent::buildClass($name);
+
+        return $this->replaceAdditional($stub);
+    }
+
+    /**
+     * Replace additional placeholders.
+     *
+     * @param string $stub
+     * @return string
+     */
+    protected function replaceAdditional(string $stub): string
+    {
+        $withCount = ExtendedQueryParameters::withCount();
+
+        $replace = [
+            '{{ withCount }}' => $withCount,
+            '{{withCount}}' => $withCount,
+        ];
+
+        return str_replace(
+            array_keys($replace), array_values($replace), $stub
+        );
+    }
+
     /**
      * @inheritDoc
      */

src/Console/MakeSchema.php

@@ -53,6 +53,10 @@ class MakeSchema extends GeneratorCommand
      */
     protected function getStub()
     {
+        if ($this->option('non-eloquent')) {
+            return $this->resolveStubPath('non-eloquent-schema.stub');
+        }
+
         return $this->resolveStubPath('schema.stub');
     }
 
@@ -108,6 +112,7 @@ protected function getOptions()
         return [
             ['force', null, InputOption::VALUE_NONE, 'Create the class even if the schema already exists'],
             ['model', 'm', InputOption::VALUE_REQUIRED, 'The model that the schema applies to.'],
+            ['non-eloquent', null, InputOption::VALUE_NONE, 'Create a schema for a non-Eloquent resource.'],
             ['proxy', 'p', InputOption::VALUE_NONE, 'Create a schema for an Eloquent model proxy.'],
             ['server', 's', InputOption::VALUE_REQUIRED, 'The JSON:API server the schema exists in.'],
         ];

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/RequestResolver.php

@@ -30,47 +30,37 @@
 class RequestResolver
 {
 
+    public const QUERY = 'Query';
+    public const COLLECTION_QUERY = 'CollectionQuery';
+    public const REQUEST = 'Request';
+
     /**
      * @var array
      */
     private static array $custom = [];
 
     /**
-     * @var string
+     * @var array
      */
-    private string $type;
+    private static array $defaults = [
+        self::QUERY => AnonymousQuery::class,
+        self::COLLECTION_QUERY => AnonymousCollectionQuery::class,
+    ];
 
     /**
-     * Register a custom binding for a query.
-     *
-     * @param string $resourceType
-     * @param string $class
-     */
-    public static function registerQuery(string $resourceType, string $class): void
-    {
-        self::register('Query', $resourceType, $class);
-    }
-
-    /**
-     * Register a custom binding for a collection query.
-     *
-     * @param string $resourceType
-     * @param string $class
+     * @var string
      */
-    public static function registerCollectionQuery(string $resourceType, string $class): void
-    {
-        self::register('CollectionQuery', $resourceType, $class);
-    }
+    private string $type;
 
     /**
-     * Register a custom binding for a resource request.
+     * Use the provided class as the default class for the specified request type.
      *
-     * @param string $resourceType
+     * @param string $type
      * @param string $class
      */
-    public static function registerRequest(string $resourceType, string $class): void
+    public static function useDefault(string $type, string $class): void
     {
-        self::register('Request', $resourceType, $class);
+        self::$defaults[$type] = $class;
     }
 
     /**
@@ -80,7 +70,7 @@ public static function registerRequest(string $resourceType, string $class): voi
      * @param string $resourceType
      * @param string $class
      */
-    private static function register(string $type, string $resourceType, string $class): void
+    public static function register(string $type, string $resourceType, string $class): void
     {
         self::$custom[$type] = self::$custom[$type] ?? [];
         self::$custom[$type][$resourceType] = $class;
@@ -113,10 +103,8 @@ public function __invoke(string $resourceType, bool $allowNull = false): ?FormRe
             if (!class_exists($fqn) && !$app->bound($fqn)) {
                 if (true === $allowNull) {
                     return null;
-                } else if ('CollectionQuery' === $this->type) {
-                    $fqn = AnonymousCollectionQuery::class;
-                } else if ('Query' === $this->type) {
-                    $fqn = AnonymousQuery::class;
+                } else if (isset(self::$defaults[$this->type])) {
+                    $fqn = self::$defaults[$this->type];
                 }
             }
 

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;
@@ -70,7 +71,7 @@ public static function guessQueryManyUsing(callable $resolver): void
      */
     public static function queryMany(string $resourceType): QueryParameters
     {
-        $resolver = self::$queryManyResolver ?: new RequestResolver('CollectionQuery');
+        $resolver = self::$queryManyResolver ?: new RequestResolver(RequestResolver::COLLECTION_QUERY);
 
         return $resolver($resourceType);
     }
@@ -94,7 +95,7 @@ public static function guessQueryOneUsing(callable $resolver): void
      */
     public static function queryOne(string $resourceType): QueryParameters
     {
-        $resolver = self::$queryManyResolver ?: new RequestResolver('Query');
+        $resolver = self::$queryManyResolver ?: new RequestResolver(RequestResolver::QUERY);
 
         return $resolver($resourceType);
     }
@@ -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/Http/Requests/ResourceRequest.php

@@ -69,7 +69,7 @@ public static function guessResourceRequestUsing(callable $resolver): void
      */
     public static function forResource(string $resourceType): ResourceRequest
     {
-        $resolver = self::$requestResolver ?: new RequestResolver('Request');
+        $resolver = self::$requestResolver ?: new RequestResolver(RequestResolver::REQUEST);
 
         return $resolver($resourceType);
     }
@@ -82,7 +82,7 @@ public static function forResource(string $resourceType): ResourceRequest
      */
     public static function forResourceIfExists(string $resourceType): ?ResourceRequest
     {
-        $resolver = self::$requestResolver ?: new RequestResolver('Request');
+        $resolver = self::$requestResolver ?: new RequestResolver(RequestResolver::REQUEST);
 
         return $resolver($resourceType, true);
     }