[Feature] Make related models accessible on resource request

Adds the `toMany` and `toOne` methods to the resource request
class. For modify relationship requests, this makes the models
referenced in the request JSON accessible.

Closes #110

Author: lindyhopchris

CHANGELOG.md

@@ -3,6 +3,14 @@
 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
+
+- [#110](https://github.com/laravel-json-api/laravel/issues/110) For requests that modify a relationship, it is now
+  possible to get the model or models referenced in the request JSON using the `toOne()` or `toMany()` methods on the
+  resource request class.
+
 ## [2.0.0] - 2022-02-09
 
 ### Added

src/Http/Requests/ResourceRequest.php

@@ -23,11 +23,13 @@
 use Illuminate\Contracts\Validation\Validator;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Http\Response;
+use Illuminate\Support\Collection;
 use LaravelJsonApi\Contracts\Auth\Authorizer;
 use LaravelJsonApi\Contracts\Schema\Relation;
 use LaravelJsonApi\Core\Document\ResourceObject;
 use LaravelJsonApi\Core\Exceptions\JsonApiException;
 use LaravelJsonApi\Core\Query\IncludePaths;
+use LaravelJsonApi\Core\Store\LazyRelation;
 use LaravelJsonApi\Core\Support\Str;
 use LaravelJsonApi\Spec\RelationBuilder;
 use LaravelJsonApi\Spec\ResourceBuilder;
@@ -49,6 +51,11 @@ class ResourceRequest extends FormRequest
      */
     private ?array $validationData = null;
 
+    /**
+     * @var LazyRelation|null
+     */
+    private ?LazyRelation $relation = null;
+
     /**
      * Specify the callback to use to guess the request class for a JSON API resource.
      *
@@ -116,6 +123,38 @@ public function modelOrFail(): object
         throw new LogicException('No model exists for this route.');
     }
 
+    /**
+     * Get the model referenced in a to-one relationship.
+     *
+     * @return Model|object|null
+     */
+    public function toOne(): ?object
+    {
+        if ($this->isModifyingRelationship()) {
+            return $this->relation()->get();
+        }
+
+        throw new LogicException(
+            'Can only retrieve the model for a to-one relationship when the relationship is being modified.'
+        );
+    }
+
+    /**
+     * Get the models referenced in a to-many relationship.
+     *
+     * @return Collection
+     */
+    public function toMany(): Collection
+    {
+        if ($this->isModifyingRelationship()) {
+            return $this->relation()->collect();
+        }
+
+        throw new LogicException(
+            'Can only retrieve the models for a to-many relationship when the relationship is being modified.'
+        );
+    }
+
     /**
      * Perform resource authorization.
      *
@@ -557,4 +596,22 @@ private function validateRelationshipDocument(): void
         }
     }
 
+    /**
+     * @return LazyRelation
+     */
+    private function relation(): LazyRelation
+    {
+        if ($this->relation) {
+            return $this->relation;
+        }
+
+        $jsonApi = $this->jsonApi();
+
+        return $this->relation = new LazyRelation(
+            $jsonApi->server(),
+            $jsonApi->route()->relation(),
+            $this->json()->all(),
+        );
+    }
+
 }