Add accessing related models from resource request class

lindyhopchris · lindyhopchris · commit a8da2e2a288b · 2022-02-20T15:42:13.000Z
diff --git a/2.0/requests/resources.md b/2.0/requests/resources.md
@@ -815,6 +815,34 @@ data that was validated for a resource create or update request.
 For relationship requests, you should use the `validatedForRelation`
 method to retrieve the validated value.
 
+## Accessing Related Models
+
+For requests that modify a relationship, it is possible to access the related
+model (for a to-one relationship) or models (for a to-many relationship). These
+are the models that are referenced in the `data` member of the request JSON.
+
+:::warning
+As the request JSON is _untrusted_ input, you should only access the related
+model or models _after_ validation has successfully completed.
+:::
+
+For to-one relationships, use the `toOne()` method. This method returns either
+the related model or `null`, depending on what is in the request JSON. For
+example:
+
+```php
+/** @var \App\Models\User|null $author */
+$author = $request->toOne();
+```
+
+For to-many relationships, use the `toMany()` method. This method returns a
+collection of the related models referenced in the request JSON. For example:
+
+```php
+/** @var \Illuminate\Support\Collection $tags */
+$tags = $request->toMany();
+```
+
 ## Deleting Resources
 
 It is possible to add validation rules for deleting resources. This is useful
diff --git a/2.0/routing/controllers.md b/2.0/routing/controllers.md
@@ -627,6 +627,9 @@ public function updatingAuthor(
 ): void
 {
   // do something...
+  // to access the author use:
+  /** @var \App\Models\User|null $author */
+  $author = $request->toOne();
 }
 
 public function updatingTags(
@@ -636,6 +639,9 @@ public function updatingTags(
 ): void
 {
   // do something...
+  // to access the tags, use:
+  /** @var \Illuminate\Support\Collection $tags */
+  $tags = $request->toMany();
 }
 ```
 
@@ -672,6 +678,9 @@ public function updatedAuthor(
 ): void
 {
   // do something...
+  // to access the author use:
+  /** @var \App\Models\User|null $author */
+  $author = $request->toOne();
 }
 
 public function updatedTags(
@@ -682,6 +691,9 @@ public function updatedTags(
 ): void
 {
   // do something...
+  // to access the tags, use:
+  /** @var \Illuminate\Support\Collection $tags */
+  $tags = $request->toMany();
 }
 ```
 
@@ -719,6 +731,9 @@ public function attachingTags(
 ): void
 {
   // do something...
+  // to access the tags, use:
+  /** @var \Illuminate\Support\Collection $tags */
+  $tags = $request->toMany();
 }
 ```
 
@@ -751,6 +766,9 @@ public function attachedTags(
 ): void
 {
   // do something...
+  // to access the tags, use:
+  /** @var \Illuminate\Support\Collection $tags */
+  $tags = $request->toMany();
 }
 ```
 
@@ -788,6 +806,9 @@ public function detachingTags(
 ): void
 {
   // do something...
+  // to access the tags, use:
+  /** @var \Illuminate\Support\Collection $tags */
+  $tags = $request->toMany();
 }
 ```
 
@@ -820,6 +841,9 @@ public function detachedTags(
 ): void
 {
   // do something...
+  // to access the tags, use:
+  /** @var \Illuminate\Support\Collection $tags */
+  $tags = $request->toMany();
 }
 ```
 

Original file line number	Diff line number	Diff line change
`@@ -627,6 +627,9 @@ public function updatingAuthor(`
`627`	`627`	`): void`
`628`	`628`	`{`
`629`	`629`	`// do something...`
	`630`	`+ // to access the author use:`
	`631`	`+ /** @var \App\Models\User\|null $author */`
	`632`	`+ $author = $request->toOne();`
`630`	`633`	`}`
`631`	`634`
`632`	`635`	`public function updatingTags(`
`@@ -636,6 +639,9 @@ public function updatingTags(`
`636`	`639`	`): void`
`637`	`640`	`{`
`638`	`641`	`// do something...`
	`642`	`+ // to access the tags, use:`
	`643`	`+ /** @var \Illuminate\Support\Collection $tags */`
	`644`	`+ $tags = $request->toMany();`
`639`	`645`	`}`
`640`	`646`	```
`641`	`647`
`@@ -672,6 +678,9 @@ public function updatedAuthor(`
`672`	`678`	`): void`
`673`	`679`	`{`
`674`	`680`	`// do something...`
	`681`	`+ // to access the author use:`
	`682`	`+ /** @var \App\Models\User\|null $author */`
	`683`	`+ $author = $request->toOne();`
`675`	`684`	`}`
`676`	`685`
`677`	`686`	`public function updatedTags(`
`@@ -682,6 +691,9 @@ public function updatedTags(`
`682`	`691`	`): void`
`683`	`692`	`{`
`684`	`693`	`// do something...`
	`694`	`+ // to access the tags, use:`
	`695`	`+ /** @var \Illuminate\Support\Collection $tags */`
	`696`	`+ $tags = $request->toMany();`
`685`	`697`	`}`
`686`	`698`	```
`687`	`699`
`@@ -719,6 +731,9 @@ public function attachingTags(`
`719`	`731`	`): void`
`720`	`732`	`{`
`721`	`733`	`// do something...`
	`734`	`+ // to access the tags, use:`
	`735`	`+ /** @var \Illuminate\Support\Collection $tags */`
	`736`	`+ $tags = $request->toMany();`
`722`	`737`	`}`
`723`	`738`	```
`724`	`739`
`@@ -751,6 +766,9 @@ public function attachedTags(`
`751`	`766`	`): void`
`752`	`767`	`{`
`753`	`768`	`// do something...`
	`769`	`+ // to access the tags, use:`
	`770`	`+ /** @var \Illuminate\Support\Collection $tags */`
	`771`	`+ $tags = $request->toMany();`
`754`	`772`	`}`
`755`	`773`	```
`756`	`774`
`@@ -788,6 +806,9 @@ public function detachingTags(`
`788`	`806`	`): void`
`789`	`807`	`{`
`790`	`808`	`// do something...`
	`809`	`+ // to access the tags, use:`
	`810`	`+ /** @var \Illuminate\Support\Collection $tags */`
	`811`	`+ $tags = $request->toMany();`
`791`	`812`	`}`
`792`	`813`	```
`793`	`814`
`@@ -820,6 +841,9 @@ public function detachedTags(`
`820`	`841`	`): void`
`821`	`842`	`{`
`822`	`843`	`// do something...`
	`844`	`+ // to access the tags, use:`
	`845`	`+ /** @var \Illuminate\Support\Collection $tags */`
	`846`	`+ $tags = $request->toMany();`
`823`	`847`	`}`
`824`	`848`	```
`825`	`849`