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

Author: lindyhopchris

CHANGELOG.md

@@ -3,6 +3,37 @@
 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-alpha.3] - 2021-02-09
+
+### Added
+
+- [#12](https://github.com/laravel-json-api/laravel/pull/12) Can now register routes for custom actions on a resource,
+  using the `actions()` helper method when registering resources. See the PR for examples.
+- The `JsonApiController` now has the Laravel `AuthorizesRequests`, `DispatchesJobs` and `ValidatesRequests` traits
+  applied.
+- [#6](https://github.com/laravel-json-api/laravel/issues/6) Resource class can now use conditional fields in their
+  relationships. This works in the same way as conditional attributes: the resource's `when()` and `mergeWhen()` method
+  should be used to add conditional relationships.
+- [#13](https://github.com/laravel-json-api/laravel/issues/13) Added French translations for JSON:API errors generated
+  by specification parsing and resource/query parameter validation.
+- [#7](https://github.com/laravel-json-api/laravel/issues/7) Eloquent schemas now support default eager loading via
+  their `$with` property.
+- [#15](https://github.com/laravel-json-api/laravel/issues/15) When parsing a JSON:API document for compliance with the
+  specification, the client will now receive a clearer error message if they submit a *to-one* relationship object for a
+  *to-many* relationship (and vice-versa).
+
+### Changed
+
+- [#2](https://github.com/laravel-json-api/laravel/issues/2) **BREAKING** Improved the extraction of existing resource
+  field values when constructing validation data for update requests:
+    - The `existingAttributes()` and `existingRelationships()` methods on the resource request class has been removed.
+      If you need to modify the existing values before the client values are merged, implement the `withExisting()`
+      method instead. This receives the model and its JSON representation (as an array).
+    - The `mustValidate()` method must now be called on a schema relationship field. (Previously this was on the
+      resource relation.) By default, belongs-to and morph-to relations will be included when extracting existing
+      values; all other relations will not. Use the `mustValidate()` or `notValidated()` method on the schema relation
+      to alter whether a relation is included in the extracted values.
+
 ## [1.0.0-alpha.2] - 2021-02-02
 
 ### Added

README.md

@@ -1,3 +1,5 @@
+![Tests](https://github.com/laravel-json-api/laravel/workflows/Tests/badge.svg)
+
 # JSON:API for Web Artisans
 
 Implement feature-rich [JSON:API](https://jsonapi.org) compliant APIs in your

composer.json

@@ -25,12 +25,12 @@
     "require": {
         "php": "^7.4|^8.0",
         "ext-json": "*",
-        "laravel-json-api/core": "^1.0.0-alpha.2",
-        "laravel-json-api/eloquent": "^1.0.0-alpha.2",
-        "laravel-json-api/encoder-neomerx": "^1.0.0-alpha.2",
-        "laravel-json-api/exceptions": "^1.0.0-alpha.1",
-        "laravel-json-api/spec": "^1.0.0-alpha.2",
-        "laravel-json-api/validation": "^1.0.0-alpha.2",
+        "laravel-json-api/core": "^1.0.0-alpha.3",
+        "laravel-json-api/eloquent": "^1.0.0-alpha.3",
+        "laravel-json-api/encoder-neomerx": "^1.0.0-alpha.3",
+        "laravel-json-api/exceptions": "^1.0.0-alpha.2",
+        "laravel-json-api/spec": "^1.0.0-alpha.3",
+        "laravel-json-api/validation": "^1.0.0-alpha.3",
         "laravel/framework": "^8.0"
     },
     "require-dev": {
@@ -65,7 +65,7 @@
             ]
         }
     },
-    "minimum-stability": "dev",
+    "minimum-stability": "stable",
     "prefer-stable": true,
     "config": {
         "sort-packages": true

src/Http/Controllers/JsonApiController.php

@@ -19,9 +19,16 @@
 
 namespace LaravelJsonApi\Laravel\Http\Controllers;
 
+use Illuminate\Foundation\Auth\Access\AuthorizesRequests;
+use Illuminate\Foundation\Bus\DispatchesJobs;
+use Illuminate\Foundation\Validation\ValidatesRequests;
+
 class JsonApiController
 {
 
+    /**
+     * JSON:API Actions
+     */
     use Actions\FetchMany;
     use Actions\FetchOne;
     use Actions\Store;
@@ -33,4 +40,11 @@ class JsonApiController
     use Actions\AttachRelationship;
     use Actions\DetachRelationship;
 
+    /**
+     * Laravel Controller Traits
+     */
+    use AuthorizesRequests;
+    use DispatchesJobs;
+    use ValidatesRequests;
+
 }

src/Http/Requests/ResourceRequest.php

@@ -24,11 +24,10 @@
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Http\Response;
 use LaravelJsonApi\Contracts\Auth\Authorizer;
-use LaravelJsonApi\Contracts\Resources\Container as ResourceContainer;
+use LaravelJsonApi\Contracts\Schema\Relation;
 use LaravelJsonApi\Core\Document\ResourceObject;
 use LaravelJsonApi\Core\Exceptions\JsonApiException;
-use LaravelJsonApi\Core\Resources\JsonApiResource;
-use LaravelJsonApi\Core\Resources\Relation;
+use LaravelJsonApi\Core\Query\IncludePaths;
 use LaravelJsonApi\Core\Support\Str;
 use LaravelJsonApi\Spec\RelationBuilder;
 use LaravelJsonApi\Spec\ResourceBuilder;
@@ -41,11 +40,6 @@
 class ResourceRequest extends FormRequest
 {
 
-    /**
-     * @var bool
-     */
-    protected bool $validateExisting = true;
-
     /**
      * @var callable|null
      */
@@ -353,43 +347,37 @@ protected function dataForCreate(array $document): array
      * @param Model|object $model
      *      the model being updated.
      * @param array $document
-     *      the JSON API document to validate.
+     *      the JSON:API document to validate.
      * @return array
      */
     protected function dataForUpdate(object $model, array $document): array
     {
-        $data = $document['data'] ?? [];
-
-        if ($this->mustValidateExisting($model, $document)) {
-            $data['attributes'] = $this->extractAttributes(
-                $model,
-                $data['attributes'] ?? []
-            );
+        $existing = $this->extractForUpdate($model);
 
-            $data['relationships'] = $this->extractRelationships(
-                $model,
-                $data['relationships'] ?? []
-            );
+        if (method_exists($this, 'withExisting')) {
+            $existing = $this->withExisting($model, $existing) ?? $existing;
         }
 
-        return $data;
+        return ResourceObject::fromArray($existing)->merge(
+            $document['data']
+        )->jsonSerialize();
     }
 
     /**
      * Get validation data for modifying a relationship.
      *
-     * @param Model|object $record
+     * @param Model|object $model
      * @param string $fieldName
      * @param array $document
      * @return array
      */
-    protected function dataForRelationship(object $record, string $fieldName, array $document): array
+    protected function dataForRelationship(object $model, string $fieldName, array $document): array
     {
-        $resource = $this->resources()->create($record);
+        $route = $this->jsonApi()->route();
 
         return [
-            'type' => $resource->type(),
-            'id' => $resource->id(),
+            'type' => $route->resourceType(),
+            'id' => $route->resourceId(),
             'relationships' => [
                 $fieldName => [
                     'data' => $document['data'],
@@ -406,14 +394,7 @@ protected function dataForRelationship(object $record, string $fieldName, array
      */
     protected function dataForDelete(object $record): array
     {
-        $route = $this->jsonApi()->route();
-
-        $data = $this->dataForUpdate($record, [
-            'data' => [
-                'type' => $route->resourceType(),
-                'id' => $route->resourceId(),
-            ],
-        ]);
+        $data = $this->extractForUpdate($record);
 
         if (method_exists($this, 'metaForDelete')) {
             $data['meta'] = (array) $this->metaForDelete($record);
@@ -423,80 +404,36 @@ protected function dataForDelete(object $record): array
     }
 
     /**
-     * Should existing resource values be provided to the validator for an update request?
+     * Extract the existing values for the provided model.
      *
-     * Child classes can overload this method if they need to programmatically work out
-     * if existing values must be provided to the validator instance for an update request.
-     *
-     * @param Model|object $model
-     *      the model being updated
-     * @param array $document
-     *      the JSON API document provided by the client.
-     * @return bool
-     */
-    protected function mustValidateExisting(object $model, array $document): bool
-    {
-        return false !== $this->validateExisting;
-    }
-
-    /**
-     * Extract existing attributes for the provided model.
-     *
-     * @param Model|object $model
-     * @return iterable
+     * @param object $model
+     * @return array
      */
-    protected function existingAttributes(object $model): iterable
+    private function extractForUpdate(object $model): array
     {
-        $resource = $this->resources()->create($model);
+        $encoder = $this->jsonApi()->server()->encoder();
 
-        return $resource->attributes($this);
+        return $encoder
+            ->withRequest($this)
+            ->withIncludePaths($this->includePathsToExtract($model))
+            ->withResource($model)
+            ->toArray()['data'];
     }
 
     /**
-     * Extract existing relationships for the provided model.
+     * Get the relationship paths that must be included when extracting the current field values.
      *
-     * @param Model|object $model
-     * @return iterable
+     * @param object $model
+     * @return IncludePaths
      */
-    protected function existingRelationships(object $model): iterable
+    private function includePathsToExtract(object $model): IncludePaths
     {
-        $resource = $this->resources()->create($model);
-
-        /** @var Relation $relationship */
-        foreach ($resource->relationships($this) as $relationship) {
-            if ($relationship->isValidated()) {
-                yield $relationship->fieldName() => $relationship->data();
-            }
-        }
-    }
+        $paths = collect($this->schema()->relationships())
+            ->filter(fn (Relation $relation) => $relation->isValidated())
+            ->map(fn (Relation $relation) => $relation->name())
+            ->values();
 
-    /**
-     * Extract attributes for a resource update.
-     *
-     * @param Model|object $model
-     * @param array $new
-     * @return array
-     */
-    private function extractAttributes(object $model, array $new): array
-    {
-        return collect($this->existingAttributes($model))
-            ->merge($new)
-            ->all();
-    }
-
-    /**
-     * Extract relationships for a resource update.
-     *
-     * @param Model|object $model
-     * @param array $new
-     * @return array
-     */
-    private function extractRelationships(object $model, array $new): array
-    {
-        return collect($this->existingRelationships($model))
-            ->map(fn($value) => $this->convertExistingRelationships($value))
-            ->merge($new)
-            ->all();
+        return IncludePaths::fromArray($paths);
     }
 
     /**
@@ -514,64 +451,6 @@ private function relationshipRules(): array
             ->all();
     }
 
-    /**
-     * Convert relationships returned by the `existingRelationships()` method.
-     *
-     * We support the method returning JSON API formatted relationships, e.g.:
-     *
-     * ```
-     * return [
-     *          'author' => [
-     *            'data' => [
-     *              'type' => 'users',
-     *              'id' => (string) $record->author->getRouteKey(),
-     *          ],
-     *      ],
-     * ];
-     * ```
-     *
-     * Or this shorthand:
-     *
-     * ```php
-     * return [
-     *      'author' => $record->author,
-     * ];
-     * ```
-     *
-     * This method converts the shorthand into the JSON API formatted relationships.
-     *
-     * @param $value
-     * @return array
-     */
-    private function convertExistingRelationships($value)
-    {
-        if (is_array($value) && array_key_exists('data', $value)) {
-            return $value;
-        }
-
-        if (is_null($value)) {
-            return ['data' => null];
-        }
-
-        $value = $this->resources()->resolve($value);
-
-        if ($value instanceof JsonApiResource) {
-            return [
-                'data' => [
-                    'type' => $value->type(),
-                    'id' => $value->id(),
-                ],
-            ];
-        }
-
-        return [
-            'data' => collect($value)->map(fn(JsonApiResource $resource) => [
-                'type' => $resource->type(),
-                'id' => $resource->id()
-            ])->all(),
-        ];
-    }
-
     /**
      * Validate the JSON API document for a resource request.
      *
@@ -618,12 +497,4 @@ private function validateRelationshipDocument(): void
         }
     }
 
-    /**
-     * @return ResourceContainer
-     */
-    final protected function resources(): ResourceContainer
-    {
-        return $this->jsonApi()->server()->resources();
-    }
-
 }