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

CHANGELOG.md

@@ -3,6 +3,19 @@
 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.3] - 2021-04-26
+
+### Added
+
+- [#14](https://github.com/laravel-json-api/laravel/issues/14) Additional sort parameters can now be added to Eloquent
+  schemas. Previously only sortable attributes were supported. These new classes are added to schemas in the
+  `sortables()` method.
+- Eloquent schemas now support a default sort order via the `$defaultSort` property.
+- New generator command `jsonapi:sort-field` to create a custom sort field class.
+- [#74](https://github.com/laravel-json-api/laravel/issues/74) Developers can now add default include paths to the query
+  request classes (e.g. `PostQuery` and `PostCollectionQuery`) via the `$defaultIncludePaths` property. These include
+  paths are used if the client does not provide any include paths.
+
 ## [1.0.0-beta.2] - 2021-04-20
 
 ### Added

composer.json

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

src/Console/MakeSortField.php

@@ -0,0 +1,75 @@
+<?php
+/*
+ * Copyright 2021 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 LaravelJsonApi\Laravel\Console;
+
+use Illuminate\Console\GeneratorCommand as BaseGeneratorCommand;
+use Symfony\Component\Console\Input\InputOption;
+
+class MakeSortField extends BaseGeneratorCommand
+{
+
+    use Concerns\ResolvesStub;
+
+    /**
+     * @var string
+     */
+    protected $name = 'jsonapi:sort-field';
+
+    /**
+     * @var string
+     */
+    protected $description = 'Create a new JSON:API sort field.';
+
+    /**
+     * @var string
+     */
+    protected $type = 'JSON:API sort field';
+
+    /**
+     * @inheritDoc
+     */
+    protected function getStub()
+    {
+        return $this->resolveStubPath('sort-field.stub');
+    }
+
+    /**
+     * @inheritDoc
+     */
+    protected function getDefaultNamespace($rootNamespace)
+    {
+        $jsonApi = trim(config('jsonapi.namespace') ?: 'JsonApi', '\\');
+
+        return $rootNamespace . '\\' . $jsonApi . '\\' . 'Sorting';
+    }
+
+    /**
+     * Get the console command options.
+     *
+     * @return array
+     */
+    protected function getOptions()
+    {
+        return [
+            ['force', null, InputOption::VALUE_NONE, 'Create the class even if the sort field already exists'],
+        ];
+    }
+
+}

src/Http/Controllers/Actions/FetchMany.php

@@ -61,6 +61,6 @@ public function index(Route $route, StoreContract $store)
             $response = $this->searched($data, $request);
         }
 
-        return $response ?: new DataResponse($data);
+        return $response ?: DataResponse::make($data)->withQueryParameters($request);
     }
 }

src/Http/Controllers/Actions/FetchOne.php

@@ -61,6 +61,6 @@ public function show(Route $route, StoreContract $store)
             $response = $this->read($model, $request);
         }
 
-        return $response ?: new DataResponse($model);
+        return $response ?: DataResponse::make($model)->withQueryParameters($request);
     }
 }

src/Http/Controllers/Actions/FetchRelated.php

@@ -76,10 +76,10 @@ public function showRelated(Route $route, StoreContract $store)
             $response = $this->{$hook}($model, $data, $request);
         }
 
-        return $response ?: new RelatedResponse(
+        return $response ?: RelatedResponse::make(
             $model,
             $relation->name(),
             $data,
-        );
+        )->withQueryParameters($request);
     }
 }

src/Http/Controllers/Actions/FetchRelationship.php

@@ -76,10 +76,10 @@ public function showRelationship(Route $route, StoreContract $store)
             $response = $this->{$hook}($model, $data, $request);
         }
 
-        return $response ?: new RelationshipResponse(
+        return $response ?: RelationshipResponse::make(
             $model,
             $relation->name(),
             $data
-        );
+        )->withQueryParameters($request);
     }
 }

src/Http/Controllers/Actions/Store.php

@@ -71,6 +71,6 @@ public function store(Route $route, StoreContract $store)
             $response = $this->saved($model, $request, $query);
         }
 
-        return $response ?: new DataResponse($model);
+        return $response ?: DataResponse::make($model)->withQueryParameters($query);
     }
 }

src/Http/Controllers/Actions/Update.php

@@ -73,6 +73,6 @@ public function update(Route $route, StoreContract $store)
             $response = $this->saved($model, $request, $query);
         }
 
-        return $response ?: new DataResponse($model);
+        return $response ?: DataResponse::make($model)->withQueryParameters($query);
     }
 }

src/Http/Controllers/Actions/UpdateRelationship.php

@@ -81,10 +81,10 @@ public function updateRelationship(Route $route, StoreContract $store)
             $response = $this->{$hook}($model, $result, $request, $query);
         }
 
-        return $response ?: new RelationshipResponse(
+        return $response ?: RelationshipResponse::make(
             $model,
             $fieldName,
             $result
-        );
+        )->withQueryParameters($query);
     }
 }

src/Http/Requests/RequestResolver.php

@@ -95,24 +95,24 @@ public function __invoke(string $resourceType, bool $allowNull = false): ?FormRe
     {
         $app = app();
 
-        try {
-            $fqn = $this->custom($resourceType) ?: Str::replaceLast('Schema', $this->type, get_class(
-                $app->make(SchemaContainer::class)->schemaFor($resourceType)
-            ));
-
-            if (!class_exists($fqn) && !$app->bound($fqn)) {
-                if (true === $allowNull) {
-                    return null;
-                } else if (isset(self::$defaults[$this->type])) {
-                    $fqn = self::$defaults[$this->type];
-                }
+        $fqn = $this->custom($resourceType) ?: Str::replaceLast('Schema', $this->type, get_class(
+            $app->make(SchemaContainer::class)->schemaFor($resourceType)
+        ));
+
+        if (!class_exists($fqn) && !$app->bound($fqn)) {
+            if (true === $allowNull) {
+                return null;
+            } else if (isset(self::$defaults[$this->type])) {
+                $fqn = self::$defaults[$this->type];
             }
+        }
 
+        try {
             return $app->make($fqn);
         } catch (BindingResolutionException $ex) {
            throw new LogicException(sprintf(
-               'Unable to create request class of type [%s] for resource type %s.',
-               $this->type,
+               'Unable to create request class %s for resource type %s.',
+               $fqn,
                $resourceType
            ), 0, $ex);
         }

src/Http/Requests/ResourceQuery.php

@@ -52,6 +52,13 @@ class ResourceQuery extends FormRequest implements QueryParameters
         self::JSON_API_MEDIA_TYPE,
     ];
 
+    /**
+     * The include paths to use if the client provides none.
+     *
+     * @var string[]|null
+     */
+    protected ?array $defaultIncludePaths = null;
+
     /**
      * Specify the callback to use to guess the request class for querying many resources.
      *
@@ -149,7 +156,7 @@ public function includePaths(): ?IncludePaths
             return IncludePaths::fromString($data['include'] ?: '');
         }
 
-        return null;
+        return IncludePaths::nullable($this->defaultIncludePaths());
     }
 
     /**
@@ -222,6 +229,16 @@ public function unrecognisedParameters(): array
         ])->all();
     }
 
+    /**
+     * Get the default include paths to use if the client has provided none.
+     *
+     * @return string[]|null
+     */
+    protected function defaultIncludePaths(): ?array
+    {
+        return $this->defaultIncludePaths;
+    }
+
     /**
      * @return void
      */

src/ServiceProvider.php

@@ -55,6 +55,7 @@ public function boot(Router $router): void
                 Console\MakeResource::class,
                 Console\MakeSchema::class,
                 Console\MakeServer::class,
+                Console\MakeSortField::class,
                 Console\StubPublish::class,
             ]);
         }

stubs/sort-field.stub

@@ -0,0 +1,59 @@
+<?php
+
+namespace {{ namespace }};
+
+use LaravelJsonApi\Eloquent\Contracts\SortField;
+
+class {{ class }} implements SortField
+{
+
+    /**
+     * @var string
+     */
+    private string $name;
+
+    /**
+     * Create a new sort field.
+     *
+     * @param string $name
+     * @param string|null $column
+     * @return {{ class }}
+     */
+    public static function make(string $name): self
+    {
+        return new static($name);
+    }
+
+    /**
+     * {{ class }} constructor.
+     *
+     * @param string $name
+     */
+    public function __construct(string $name)
+    {
+        $this->name = $name;
+    }
+
+    /**
+     * Get the name of the sort field.
+     *
+     * @return string
+     */
+    public function sortField(): string
+    {
+        return $this->name;
+    }
+
+    /**
+     * Apply the sort order to the query.
+     *
+     * @param \Illuminate\Database\Eloquent\Builder $query
+     * @param string $direction
+     * @return \Illuminate\Database\Eloquent\Builder
+     */
+    public function sort($query, string $direction = 'asc')
+    {
+        // @TODO
+    }
+
+}

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

@@ -34,6 +34,7 @@
 use LaravelJsonApi\Eloquent\Pagination\PagePagination;
 use LaravelJsonApi\Eloquent\Schema;
 use LaravelJsonApi\Eloquent\SoftDeletes;
+use LaravelJsonApi\Eloquent\Sorting\SortCountable;
 use LaravelJsonApi\HashIds\HashId;
 
 class PostSchema extends Schema
@@ -93,6 +94,16 @@ public function filters(): array
         ];
     }
 
+    /**
+     * @inheritDoc
+     */
+    public function sortables(): iterable
+    {
+        return [
+            SortCountable::make($this, 'comments'),
+        ];
+    }
+
     /**
      * @inheritDoc
      */